Plastic SCM Administrator's guide


Chapter 1: Introduction

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.


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.


Chapter 2: Minimum requirements

  • Windows - The .NET Framework 4.5.1 is required.
  • Linux - A mono package is distributed with the Plastic SCM installer.
  • Windows:
    • all Windows versions back to Vista
    • Windows XP and Windows 2000 no longer supported due to .Net 4.5.1 restrictions
  • Linux (more info here):
    • Debian 6.0 and 8.1
    • Ubuntu 14.04
    • Fedora 17 and 20
    • Red Hat Enterprise 6.x
    • CentOS 6.x
    • OpenSUSE 12.2, 12.3 and 13.1
  • Mac OS:
    • Mac OS Mountain Lion (10.8) and above

Disk usage largely depends on your repository size.

RAM and CPU depend on the concurrent load that the server needs to handle. Get further information about how the Plastic SCM server is capable of handling high loads.


Chapter 3: Plastic SCM installation


Prerequisites

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


Server and Client installation

Read how to install Plastic SCM on your Windows, Linux or Mac OS system.

Windows

The table below details the steps to install Plastic SCM:

Choose the installation directory for the Plastic SCM components. Windows - Installation directory
Select the components.

By default, the CLI and GUI clients are always installed.

Optionally, the Plastic SCM server and integrations with 3rd party tools can be installed. Below is a description of each component.

Windows - Component selection
The available components are:
  • Client components:
    • Command line tool or command line client (the cm command) - Installed by default.
    • Graphical user interface client (plastic.exe) - Installed by default.
    • Mergetool - Installed by default.
    • Plastic Gluon - Installs the tool designed for users who typically work on a single branch with files that can't be merged. The typical users of the tool are artists involved with game development teams. See the Plastic Gluon guide for more info. Installed by default.
    • Windows Explorer shell extension - Installs the Plastic SCM Shell Extension that integrates Plastic SCM with the Windows Explorer. The integration lets the user do most of the operations available on the Plastic SCM GUI client directly from the Windows Explorer.
  • Server components - The Plastic SCM server.
  • IDE integrations:
    • Visual Studio integration package (2010 or higher) - This option installs a Source Code Control Package for Visual Studio to perform Plastic SCM operations and view Plastic SCM elements from the VS IDE. Also compatible with Atmel Studio 6.0. For more details, see the Plastic SCM IDE integrations guide.
    • Eclipse plugin - The Plastic SCM integration with the Eclipse platform. Learn more about it in the Plastic SCM IDE integrations guide.
    • Mylyn-Eclipse plugin - This options installs a plugin to integrate Mylyn for Eclipse with Plastic SCM. Requieres Eclipse plugin.
    • IntelliJ IDEA 12/13/14, 11 and 8.1 plugins - The Plastic SCM integration with diferent releases of IntelliJ IDEA platform.
    • SCC plugin - This is Plastic SCM implementation of MS-SCCI interface. It provides checkin/checkout/add and basic file-level operations.
      The SCC plugin is used by many tools, especially in the Windows world, as a way to interface with the version control backend. Check the documentation of your tool for compatibility with the MS-SCCI specification (also known as SCC). It used to be primarily used by Visual Studio, but deprecated since Visual Studio 2005. Plastic SCM offers a richer integration in the Visual Studio integration package.
  • Office plugins - The Plastic SCM integration with different versions of Microsoft Office. Learn how this plugin works in the Plastic SCM Office guide.
Application to be started.

Select what application will be started after the installation is finished: Plastic or Gluon.

Windows - Application to be started
Ready to install.

At this point the installer has all the needed information.

File copy progress. Windows - Installing
The Plastic SCM server installation has finished. Windows - Setup finished
Note: If the Windows Explorer Shell Extension has been installed, a reboot of the machine might be needed.
The Plastic SCM Server is now configured with the default values. Some of them are the following:
  • Plastic SCM Edition - Team.
  • User authentication mode - Local name.
  • Database backend - Jet.
If you need to change this configuration, please launch the webadmin.

Linux

To install Plastic SCM on Linux, just follow the instructions for your Linux distro.

Important: Remember to run the commands as sudo.
The Plastic SCM Server is now configured with the default values. Some of them are the following:
  • Plastic SCM Edition - Team.
  • User authentication mode - Local name.
  • Database backend - Jet.
If you need to change this configuration, please launch the webadmin.
Once the Plastic SCM Server and Client components are installed, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

Mac OS

To install the Plastic SCM server and client on your Mac OS system, first download the Server and Client components from the Plastic SCM download web page. You can find the server installer at the More installers section.

Mac OS - Plastic SCM Server

Follow these steps to install the Plastic SCM server:

Welcome to the Plastic SCM server installation. Mac - Plastic SCM server - Installation
Accept the license agreement and continue with the installation. Mac - Plastic SCM server - License agreement
Choose the installation disk for the MacPlastic SCM components. Mac - Plastic SCM server - Installation directory
Ready to install.

At this point the installer has all the needed information.

Mac - Plastic SCM server - Installation
Plastic SCM server installation process. Mac - Plastic SCM server - Installing MacPlastic
The Plastic SCM server installation has finished. Mac - Plastic SCM server - Installation finished
Mac OS - Plastic SCM client

Once the Plastic SCM Server is installed, follow these steps to install the Plastic SCM client:

Welcome to the MacPlastic SCM GUI client installation MacPlastic client - Installation
Accept the license agreement and continue with the installation. MacPlastic client - License agreement
Choose the installation disk for the MacPlastic SCM components. MacPlastic client - Installation directory
Ready to install.

At this point the installer has all the needed information.

MacPlastic client - Installation
MacPlastic installation process. MacPlastic client - Installing MacPlastic
The MacPlastic installation has finished. MacPlastic client - Installation finished
The Plastic SCM Server is now configured with the default values. Some of them are the following:
  • Plastic SCM Edition - Team.
  • User authentication mode - Local name.
  • Database backend - Jet.
If you need to change this configuration, please launch the webadmin.
Once the Plastic SCM Server and Client components are installed, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

Server configuration

After you install the Plastic SCM server for the first time, the server is configured with the default values. So the server is ready to go.

The Plastic Administrator can configure the server applying the new settings or configurations that are required (network, license, authentication, and so on).

Follow one of this methods to configure the Plastic SCM server

  • Launch the webadmin - Plastic SCM Server Administration Console - the cross-platform admin tool.
  • From the command line:
    1. Run the command line admin tool (remember to run the command as sudo.):
      • On Windows and Linux systems: clconfigureserver
      • On Mac OS systems: /Applications/PlasticSCMServer.app/Contents/Applications/clconfigureserver.app/Contents/MacOS/clconfigureserver
    2. Configure the required settings:
      • Language: Type the number related to the language you want to use to configure the Plastic SCM server.
      • Users authentication mode: Here you have to choose between the different authentication mechanisms available:
        • TCP port - By default, Plastic SCM will use 8087 as its TCP port number. If the default listening port is changed, Plastic SCM clients must be setup to this new port.
        • SSL port - By default, the SSL secured port is 8088.
      • Users authentication mode - Here you have to choose between the different authentication mechanisms available:
        • If the LDAP option is selected, then you must setup the LDAP authentication parameters:
          • LDAP server name and port (by default, 389);
          • the domain from which data must be retrieved;
          • a user name and a password to be used to access the LDAP server;
          • and, finally, choose whether the LDAP server is an Active Directory or a conventional LDAP server.

          LDAP Authentication configuration

          Remember: The LDAP and Active Directory authentication modes are only included with the Enterprise Edition.
        • If the User and password option is selected, then you need to create/configure the Plastic SCM users and groups.

        Learn how to configure the Authentication modes.

      • Database backend - Configure the database backend that you want to use. The available database backends list depends on the platforms.
      • License - In this section the user can configure the auto renewal option. Get more information about it in this chapter.

Client configuration

Each time a new client is installed on a developer's 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.

Read how to configure the Plastic SCM client in your Windows, Linux or Mac OS system.

Windows

To run the Client configuration wizard from the command line, use the following commands:
  • clconfigureclient - Configure the Plastic SCM client through the command line. Read this section to learn how this configuration works.
  • plastic --configure - Open the Plastic SCM client configuration GUI. See the steps below.
The Client configuration wizard GUI can also be run from the Plastic SCM startup menu entry.

Using the Client configuration wizard the user can configure:

Windows - Client configuration wizard

  • Plastic SCM server:
    • The user must fill in the host name or IP address of the Plastic SCM server using the server:port format. By default, the Plastic SCM server TCP port is 8087. If it has been changed on the server, set here the new port number. Once that information is entered, the user can check if the Plastic SCM client is able to connect to the Plastic SCM server just by clicking on the Connect button.

      The user can find servers in his/her network if he/she doesn't know the server host name. This is possible by launching the discovery service by clicking on the Scan network... button. The client sends a UDP packet using the broadcast IP (255.255.255.255). The server implements a little UDP server that listens for this message, which will contain the server's address, port, and version. The client listens for answers and filters servers that are not compatible with it. And then the user can select a server from the list:

      Scan network - Find servers

      This service is available by default, but you can disable it by editing the server.conf file and adding the following line:

      <EnableDiscoveryService>no</EnableDiscoveryService>
    • Use encryption: There is a checkbox available to select whether or not to use SSL when connecting to the server.
  • User's credentials: The Plastic SCM client automatically detects what authentication mode was configured on the connected server. The user must enter the data required (if needed) and, optionally, click on the Check button in order to check the connection with the configured user's credentials.
  • Proxy server: Optionally you can use a proxy server. Read more about how to install and configure the Plastic SCM proxy server.
Once the Plastic SCM Client is configured, if it's the first time you install Plastic, then you must configure your working project before Plastic SCM can be used.

Linux

To run the Client configuration wizard from the command line, use the following command:
  • clconfigureclient - Configure the Plastic SCM client through the command line. Read this section to learn how this configuration works.
  • gtkplastic --configure - Open the Plastic SCM client configuration GUI. See the steps below.
The Client configuration wizard GUI can also be run by right-clicking the Plastic SCM application and selecting the Configure Plastic SCM option.

Using the Client configuration wizard the user can configure:

Linux - Client configuration wizard

  • Plastic SCM server:
    • The user must fill in the host name or IP address of the Plastic SCM server using the server:port format. By default, the Plastic SCM server TCP port is 8087. If it has been changed on the server, set here the new port number. Once that information is entered, the user can check if the Plastic SCM client is able to connect to the Plastic SCM server just by clicking on the Connect button.
    • Use encryption: There is a checkbox available to select whether or not to use SSL when connecting to the server.
  • User's credentials: The Plastic SCM client automatically detects what authentication mode was configured on the connected server. The user must enter the data required (if needed) and, optionally, click on the Check button in order to check the connection with the configured user's credentials.
Once the Plastic SCM Client is configured, if it's the first time you install Plastic, then you must configure your working project before Plastic SCM can be used.

Mac OS

To run the Client configuration wizard from the command line, use the following command:
  • clconfigureclient - Configure the Plastic SCM client through the command line. Read this section to learn how this configuration works.
  • macplastic --configure - Open the Plastic SCM client configuration GUI. See the steps below.
The Client configuration wizard GUI can also be run by double-clicking the macplastic application.

Using the Client configuration wizard the user can configure:

Mac OS - Client configuration wizard

  • Plastic SCM server:
    • The user must fill in the host name or IP address of the Plastic SCM server using the server:port format. By default, the Plastic SCM server TCP port is 8087. If it has been changed on the server, set here the new port number. Once that information is entered, the user can check if the Plastic SCM client is able to connect to the Plastic SCM server just by clicking on the Connect button.
    • Use encryption: There is a checkbox available to select whether or not to use SSL when connecting to the server.
  • User's credentials: The Plastic SCM client automatically detects what authentication mode was configured on the connected server. The user must enter the data required (if needed) and, optionally, click on the Check button in order to check the connection with the configured user's credentials.
Once the Plastic SCM Client is configured, if it's the first time you install Plastic, then you must configure your working project before Plastic SCM can be used.

Command line

Client configuration - Command line

  • Language - Type the number related to the language you want to use to configure the Plastic SCM client.
  • Plastic SCM server address/port - First type the Plastic SCM server address (name or ip), and then, the server port.
  • Authentication mode configuration - Enter your credentials if they are required by the Plastic SCM server.
  • Proxy server - Optionally you can use a proxy server. Read more about how to install and configure the Plastic SCM proxy server.

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.
Important: The rules are executed in order, so the less restrictive ones must be at the bottom of the list. A catch-all rule for the file extension "*" is normally the latest.

The 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:

<MergeTools>
  <MergeToolData>
    <FileType>enTextFile</FileType>
    <FileExtensions>*</FileExtensions>
    <Tools>
      <string>mergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype"</string>
    </Tools>
  </MergeToolData>

  <MergeToolData>
    <FileType>enBinaryFile</FileType>
    <FileExtensions>.scs</FileExtensions>
    <Tools>
      <string>"mergetool.exe" -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="unicode" -m="onlyone"</string>
    </Tools>
  </MergeToolData>

  <MergeToolData>
    <FileType>enBinaryFile</FileType>
    <FileExtensions>*</FileExtensions>
    <Tools>
      <string>binmergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -m="@mergetype"</string>
    </Tools>
  </MergeToolData>
</MergeTools>

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:

 <DiffTools>
  <DiffToolData>
    <FileType>enTextFile</FileType>
    <FileExtensions>*</FileExtensions>
    <Tools>
      <string>mergetool -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod" -e="@fileencoding"</string>
    </Tools>
  </DiffToolData>

  <DiffToolData>
    <FileType>enBinaryFile</FileType>
    <FileExtensions>.scs</FileExtensions>
    <Tools>
      <string>"mergetool.exe" -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod" -e="unicode" </string>
    </Tools>
  </DiffToolData>

  <DiffToolData>
    <FileType>enBinaryFile</FileType>
    <FileExtensions>*</FileExtensions>
    <Tools>
      <string>binmergetool -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic"  -a -t="@filetype" -i="@comparationmethod" -e="@fileencoding"</string>
    </Tools>
  </DiffToolData>
</DiffTools>

Start working with Plastic SCM

The first time you install Plastic SCM, you must configure some options to start working with Plastic SCM.

Read how to start working with the Plastic SCM in your Windows, Linux or Mac OS system.

Windows

The first time you install Plastic SCM, after configuring the Plastic SCM server and client, you must set up the project that you'll work with.

You can choose one of the two following options to start working with Plastic SCM:

  • Start a new project - This means that you must create a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name that you want to create.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.
  • Join an existing project - This means that you must select an existing repository and create a new workspace to start working with:
    Start working with Plastic - Join an existing project
    • Repository - Select an existing repository.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will be launched showing you that workspace.

Linux

The first time you install Plastic SCM, after configuring the Plastic SCM server and client, you must set up the project that you'll work with.

You can choose one of the two following options to start working with Plastic SCM:

  • Start a new project - This means that you must create a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name that you want to create.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.
  • Join an existing project - This means that you must select an existing repository and create a new workspace to start working with:
    Start working with Plastic - Join an existing project
    • Repository - Select an existing repository.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will be launched showing you that workspace.

Mac OS

The first time you install Plastic SCM, after configuring the Plastic SCM server and client, you must set up the project that you'll work with.

You can choose one of the two following options to start working with Plastic SCM:

  • Start a new project - This means that you must create a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name that you want to create.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.
  • Join an existing project - This means that you must select an existing repository and create a new workspace to start working with:
    Start working with Plastic - Join an existing project
    • Repository - Select an existing repository.
    • Workspace name - Enter a workspace name. By default, the workspace name will be the same as the repository created, but you can enter a different name.
    • Path on disk - Then, select the place where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will be launched showing you that workspace.


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.

Read how to start/stop/restart the Plastic SCM server in your Windows, Linux or Mac OS system.

Windows

To start and stop the Plastic SCM service on Windows systems, use one of the following methods:

  1. Open the Windows Service Manager by going to Control Panel > Administrative Tools > Services or by running the services.msc command. Once the Services window is opened then you will find the Plastic SCM service in the list. You can use the start and stop actions available to normal services from the Services console.

    Managing Plastic SCM server service

  2. Run the command line and type the required action: plasticd {--start |--stop | --restart}

Linux

To start and stop the Plastic SCM service on Linux systems, use the plasticsd script as sudo. This script is located in the following locations:

  • In the /etc/init.d directory to help with automatic start on system boot.
  • In the server installation directory, /opt/plasticscm5/server, by default.
  • Or you can also use it through the service command.

This script has the following options:

plasticsd {start | stop | restart | status}

For example:

/etc/init.d/plasticsd start /opt/plasticscm5/server/plasticsd stop service plasticsd restart

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

You can check whether the server is up and running by running one of the previous command with the status option:

/etc/init.d/plasticsd status

The command will return the running process ID of the server.

Another way to check the server status is by looking at the repository list. Follow the next step: open a console and type cm lrep servername:port. It will list all the repositories on server servername:port.

Mac OS

To start/stop the Plastic server daemon, you will need to use the launchctl Mac command as sudo:

  • To start the Plastic server, run the following command: sudo launchctl load /Library/LaunchDaemons/com.codicesoftware.plasticscm.server.plist
  • And use this command to stop the Plastic server: sudo launchctl unload /Library/LaunchDaemons/com.codicesoftware.plasticscm.server.plist

Run Plastic SCM

Read how to run Plastic SCM in your Windows, Linux or Mac OS system.

Windows

Select one of the following methods to run the Plastic SCM client:

  • Open the Plastic SCM application from the startup menu:

    Windows - Run Plastic SCM

  • Type plastic in a command line interface window.

Linux

  • Open the Plastic SCM application from the Applications window:

    Linux - Run Plastic SCM

  • Type gtkplastic in a command line interface window.

Mac OS

Select one of the following methods to run the Plastic SCM client:

  • Open the Plastic SCM application from the Applications window:

    Mac OS - Run Plastic SCM

  • Type open /Applications/plasticscm.app in a command line interface window.

Chapter 4: Using a proxy server

Plastic SCM supports the idea of having a Proxy server to support balancing the traffic between the two machines: the possibly remote server machine and the probably local proxy machine. This proxy can be installed with minimum operating resources. No database backend is needed to run it, making it pretty easy to set up. It can be configured as a daemon, Windows service or started manually from the command line.

The cached data will always be read-only, meaning that only checked-in revision data is cached on the proxies. Since checked in revisions never change, it's safe and simple to cache them.

The Proxy server will start caching files from the repository server as data is requested from clients. Once cached, revision data stays on the proxy, so that future requests to the same revisions will be downloaded from the proxy machine instead of the remote repository server.

The proxy server will also use keep the most used revisions in memory, for improved performance. The administrator can configure the maximum amount of memory to be used.

This is a list of the benefits of using a Proxy with Plastic SCM:

  • 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 on a configurable disk directory for simplified administration.
  • 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:

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.

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.

Same network, improved by using two proxies


Installing the Plastic SCM Proxy server

The Proxy server is distributed as a separate download in the Plastic SCM website and can be installed stand alone: it doesn't require a Plastic SCM server or client to be present on the same machine.

The following table summarizes the installation steps after the installer is run and the license agreement accepted:

Installation directory selection.

This is the folder that contains the binary files for the proxy server.

Proxy installer binaries folder
Cache storage.

This is the folder that will hold the revision cache. It should be located on a fast and large enough disk, to benefit from the maximum performance.

Cached data directory location
TCP Listening port.

This is the TCP port that the proxy server will use. By default, it is 8085.

Proxy listening port
Binary files will be copied and the installation is complete.

The Plastic Proxy service is started at the end of the installation and is ready to begin caching data.


Configuring the clients

The Plastic SCM clients now need to configure a proxy server. In order to do this, run the Plastic SCM Client configuration wizard.

The proxy server is configured by checking the Configure a Proxy server box and entering the proxy server name in server:port format:

Configuring a proxy server in the Plastic SCM client

This is all the setup required in the client. When an operation downloads revisions from the server, the client will ask the proxy and download from it instead of the server if the data is cached.


Chapter 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.


Creating a new repository

An empty repository named default is created on the first server start up if no other repository exists yet, so that users can start working straight away.

From the administrator point view, it can be desirable to create repositories using the command line interface. This is achieved in with the cm makerepository or cm mkrep commands:

cm mkrep PlasticServer:8087 NewRepository

Where:

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

Repositories can also be created on the Plastic SCM GUI client by opening the repositories view and clicking on Create new repository button.

Creating a new repository in the Plastic SCM GUI client

The new repository dialog lets the user enter the repository name and the Plastic SCM server where it will be created.

New repository dialog

Listing available repositories

Listing available repositories can be done at the command line level or GUI client. On the command line, you use the cm listrepositories or cm lrep:

cm lrep backyard:8087

Will show the output:

default@backyard:8087 doom3scr@backyard:8087

The figure below shows the repositories view on the GUI tool, accessible from the Repositories view menu.

Repositories view

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.

First, list all repositories:

C:\scm3>cm lrep localhost:8087 --format=TABLE 1 default localhost:8087 3 myproject localhost:8087 5 nasa localhost:8087

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:

cm removerepository myproject@localhost:8087

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

  • It removes the repository from the list of registered repositories available to be used in workspaces.
  • It removes the repository from the list of available repositories.
Note: the removerepository command does not delete the database in the database backend.

The repository database in the physical database backend name follows this pattern:

rep_xx.plastic

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

rep_3.plastic

You can locate the database with that name in your database backend and back it up using the tool of your choice. After you have backed it up, you can delete the database from your backend if desired.


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)

C:\scm3>cm lrep localhost:8087 --format=TABLE 1 default localhost:8087 3 excel localhost:8087 4 word localhost:8087 5 PW point localhost:8087 6 access localhost:8087 7 outlook localhost:8087

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 database rep_3.plastic to rep_8.plastic. For instance, for an embedded Firebird database this means just renaming the database file on disk:

move rep_3.plastic.fdb rep_8.plastic.fdb

And now for reconnecting, add the repository to the list of available repositories using the cm addrepository command:

cm addrepository rep_8 myproject localhost:8084
  • The first argument is the database name (rep_8), without the .plastic.fdb extension.
  • The second argument is the name of the repository (myproject). This must be unique in the list of available repositories and is the name that Plastic SCM users will see.
  • The last argument is the repository server IP:TCP PORT (localhost:8084) where the repository will be connected.

Chapter 6: webadmin - Server configuration and administration


Accessing the webadmin

Once the Plastic SCM server is installed for the first time, it is configured with the default values. So, the server is ready and the Plastic clients are able to connect and run.

The Plastic SCM Server administration console is a cross-platform server configuration tool UI that lets the Plastic administrator configure those server settings to suit your organization needs.

To launch the server administration console:

  1. Open your favorite web browser.
  2. Connect to your server address like this: http://0.0.0.0:7178. We do not support HTTPS yet. So, don't open it up to the Internet.
  3. Enter the required credentials. You will be in one of the following situations:
    • If the server is just installed (no repositories created yet, except the default one and must be empty), then you must set a password to the administration console.
      Plastic SCM Server administration console - Register
    • If the server is already setup but the administration console password is not set, then you must configure a password using the adminconsolepwd utility:
      Plastic SCM Server administration console - Configure a password

      Follow these steps:
      1. Open the command line as an administrator user.
      2. Go to the Plastic SCM server directory.
      3. Run the following command: adminconsolepwd --pwd=yourpassword
      4. Then, go back to the Administration console and Refresh.
      5. Enter the configured password and Log in.
    • If the administration console password exists, just enter it!
      Plastic SCM Server administration console - Log in

Now, you can configure the required settings:

  • Network - Edit the Plastic listening ports for both encrypted and non-encrypted data.
  • Authentication - Configure the authentication mode used by the Plastic users and groups. By default, the configuration mode is Local name.
  • Repository storage - Configure the data backend that fits your needs.
  • Advanced features - Set up some advanced values related to global security settings, buffer pools, trigger variables, and so on.
  • Audit - Change the audit log level.
  • Security - Configure the data related to the Plastic SCM server administrator.
  • Lock rules - Set up the exclusive checkout rules.

And, you can also access to some other relevant information:

  • License - Configure all about the Plastic SCM license: buy a Plastic license, enter the plasticd.lic license file, or configure the auto renewal option.
  • Support - Find solutions to your issues, contact the Plastic support team or send us your suggestions.
  • Monitor - Examine the Plastic activity in real time.
server.conf, remoting.conf, db.conf and lock.conf are now reloaded on the fly. Make a change editing a file, and the Plastic SCM server will reload the config immediately.

Network configuration

The Plastic SCM server administrator can configure the ports where the server listens for both encrypted and non-encrypted data.

Don't forget to Apply for changes to take effect.

Configure the required values:

  • TCP ports - By default, Plastic SCM uses 8087 as its TCP port number. If this default listening port changes, the Plastic SCM clients must be setup to this new port.
    Network configuration - TCP
  • SSL ports - SSL requires a certificate to encrypt communication. A self-signed certificate is generated the first time the Plastic SCM server starts, bound to the current hostname.
    Network configuration - SSL

    It is possible to use your own certificate. To do that, enter the name of the certificate file and the required password to open the certificate file. If the password is wrong, the changes are not applied to the file.
    This certificate file must be located in the Plastic SCM server directory.
    Click Recreate self-signed cert to create a new self-signed certificate.
  • UDT ports (Windows only) - Configure the UDT ports if you're working with high-speed networks.
    Network configuration - UDT
  • UDP discovery service - Let the Plastic SCM server be reacheable by the clients in the LAN.
    Network configuration - UDP
  • Override host name - Set an IP address if you need to override the Plastic server host name.
    Network configuration - Override host name

Authentication configuration

This section lets the Plastic administrator configure the authentication mode used by the Plastic clients:

Authentication configuration

The authentication methods tell Plastic SCM how to integrate users and groups of users with the objects of the repository.

The Plastic 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.

Plastic SCM can use five different connectors for retrieving its user information:

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

You can also change the authentication mode when you need it.

Local name

In the Local name 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 relies on correct network configuration. 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.


How does the server obtain the user list?

It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it's not a local user.


How is the SEID built?

Just with the user name.

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.


How does the server obtain the user list?

It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it's not a local user.


How is the SEID built?

User name + ID: user id on Linux and SID on Windows.

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.

If needed, the Plastic server can set a timeout for the LDAP requests. It can be configured adding a new entry in the server.conf file as follows (time is in seconds):

<LdapTimeout>10</LdapTimeout>

How does the server obtain the user list?

From the LDAP Server using a given user and password.


How is the SEID built?

The ID used by the concrete LDAP mechanism.

Active Directory

Using this configuration mechanism, the user list will be retrieved from the current Active Directory server. This authentication method requires the server to be running on an operating system that supports Active Directory. In other words, it is designed to run on Windows-based operating systems.

Active Directory authentication can be used in single- or multi-domain environments. When using Plastic SCM in an Active Directory forest with multiple domains, usernames and groups should be entered in the DOMAIN\username and DOMAIN\group syntax.

For example, assume you have two domains, LONDON and MADRID. LONDON contains a user with the login LONDON\jsmith who is in the group LONDON\developers. MADRID contains a user with the login MADRID\ahernandez who is in the group MADRID\coordinators. LONDON\jsmith logs onto the network and changes repository server permissions.

Changing repository permissions

He adds an ACL entry which specifies that MADRID\coordinators are denied mkbranch and mkchildbranch permissions.

Specifying MADRID\coordinators

When user MADRID/ahernandez opens the GUI client and tries to create a child branch from main, you can expect her to receive an access denied error.


How does the server obtain the user list?

It retrieves it from the active directory main server. The server must be correctly configured.


How is the SEID built?

A Windows SID.

User and password

This is the traditional authentication method. It allows the Plastic SCM users to define their own users and groups on the Plastic server. This way, Plastic can work with an autonomous security mechanism, which could be the best option for many organizations that don't rely on systems like LDAP or Active Directory. The user and password (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.

When using UP mode, the Plastic SCM security system works exactly as it would do with LDAP, Active Directory or any other mode. The difference is that the Plastic SCM server itself stores the users and groups information.

The Plastic SCM 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.

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:

Configuration files in user/password mode

  • users.conf - Stores information about all the users and their encrypted passwords. The users.conf file contains the definition of the users known to the system in user/password 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:

    users.conf file format

  • groups.conf - Stores all the available groups and the users they contain. The groups.conf file contains all the groups known to the Plastic system in user/password mode. The file is a list of the groups, each one followed by the names of the users or groups it contains. Notice that a group inside another group must be preceding by a "@" symbol (in the example bellow, testers group inside developers group). Check the following figure for details:

    groups.conf file format

To configure the UP mode, you must use one of the following tools:

  • This Authentication configuration section from the Plastic SCM Server Administration console:

    The User and password configuration section is a simple and intuitive tool whose solely purpose is to help users configure the users.conf and groups.conf files.

    The administrator uses this tool to create users and groups, assign users to a specific group, change a user's password, and rename or delete users and groups:

    Authentication configuration - User and password authentication mode

    To configure the login and password, the user needs to run the Plastic SCM client configuration wizard as shown on the following figure:

    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:

    Login dialog

  • The User management tool from the command line:

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

    To learn how to use each command, please type the following:
    • Windows or Linux systems: umtool help <command_name>
    • Mac OS system: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool help <command_name>

    The umtool implements several commands detailed on the following table:

    Command name Short name Description
    addgrouptogroup agtg Include a new group into a group
    addusertogroup autg Include a new user into a group
    changeuserpassword passwd Change a user's password
    creategroup cg Create a new Plastic SCM group
    createuser cu Create a new Plastic SCM user
    help hlp Show a command's help
    listgroups lg Show a list with current Plastic SCM groups
    listmembersfromgroup lmfg Show a list with members of a group
    listusers lu Show a list with current Plastic SCM users
    removegroup rmg Delete an existing Plastic SCM group
    removegroupfromgroup rmgfg Delete a group from another group
    removeuser rmu Delete an existing Plastic SCM user
    removeuserfromgroup rmufg Delete a user from a group
    renamegroup rng Rename an existing Plastic SCM group
    renameuser rnu Rename an existing Plastic SCM user

    Here you can find some examples:

    Create a new user: umtool cu maria maria
    Create a new user in a Mac OS system: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool cu maria maria
    Create a new group: umtool cg developers
    Create a new group in a Mac OS system: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool cg developers
    Add a user to a group: umtool addusertogroup maria developers
    Add a user to a group in a Mac OS system: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool addusertogroup maria developers
User/Password mode common questions

How does the server obtain the user list?

It retrieves the list of users' names from the users.conf and the groups.conf files on the server folder.


What does the authentication contain?

It contains the username and the encoded password.

Change the authentication mode

  1. Click Change auth mode to select a new authentication mode:
    Authentication configuration - Change authentication mode
    These are the authentication modes available as you saw before:
    • Local name - Gets the users and groups from the operating system. Only the name is checked.
    • Name + ID - Gets users and groups from the operating system. The name and ID of the user is checked.
    • LDAP - Retrieves users and groups from a designated LDAP server.
    • Active Directory - Retrieves users and groups from the Active Directory configured for the server machine. For Windows servers only.
    • User and password - Uses the groups and users defined by the Plastic SCM administrator.
  2. Apply the new selected mode.
  3. Then, configure the new authentication mode:
    • Local name, Name + ID and Active Directory authentication modes don't need any particular configuration.
    • LDAP - Configure the required data to establish the connection and advanced connection and security settings. You can also configure some advanced features and if you want to use Plastic SCM groups.
      Don't forget to Apply for changes to take effect.
    • User and password - Manage the users and groups that will be identified by the Plastic SCM server. Both users and groups can be members of a group.

Repository storage

There are several backends that Plastic supports: Jet, SQL Server, Firebird...

The Repository storage section lets the administrator to:

  • Configure the data backend where the repositories information will be saved.
  • Change the storage to use a different backend.

Please see the Repository storage configuration chapter to learn how to configure the repository storage that you want to use.


Advanced

The Advanced configuration section lets the Plastic SCM administrator customize some other server features.

Lets see what they are and how you can configure them:

Request processing
  • Force client build number - Related to the ForceBuildNumberMatch parameter in the server.conf file.
    Use this parameter to force all clients to be upgraded to the same build number of the server. Optionally, you can set a minimum build number instead of forcing exactly the same as the server.
    Read more about how this setting works.
  • Abort request if socket closes - Related to the AbortRequestIfSocketCloses parameter in the server.conf file.
    When a client makes a request and closes the connection before the server finishes processing, the server will kill the request thread. This avoids long running cancelled requests to grow.
    Enabled by default on Windows, disabled on Linux due to instability issues.
  • Transaction timeout - Related to the TransactionTimeout parameter in the server.conf file.
    This is the time (in seconds) before a long running transaction is automatically cancelled by the server.
Global security settings
  • FIPS compliance - Related to the FIPSCompliant parameter in the server.conf file.
    Enable this parameter to force to use FIPS compliant algorithms only.
    Requires that the Plastic clients to enable FIPS in their client.conf file. Otherwise, they won't be able to connect to this server.
  • Enforce secured paths - Related to the SecuredPaths parameter in the server.conf file.
    If you use secured paths (permissions set to paths) and want to restrict users to access file revisions by item id if they don't have access to (using cm cat), then enable this setting.
    Good for high security environments.
    Read more about how to use the Secured paths.
Worker Thread Pool
This is the thread pool that attends client requests. Each thread is reused for better performance. Only experts should tweak this value.
  • Min threads - Related to the MinWorkerThreads parameter in the server.conf file.
  • Max threads - Related to the MaxWorkerThreads parameter in the server.conf file.
    By default, the max number of threads matches the number of cores of the server.
Buffer pools
The buffer pools help reducing memory allocations by reusing pre-allocated buffers. Reducing allocations greatly increase performance under heavy load.
  • Number of Tree buffers - Related to the TreeBufferPoolCount parameter in the server.conf file.
    Use this parameter to serialize directory trees. Under heavy load, this value should match the number of worker threads to avoid contention.
  • Number of Blob buffers - Related to the BlobBufferPoolCount parameter in the server.conf file.
    Configure this value to read and write file data to the storage. These buffers reduce allocating 4MB blocks on every data transfer.
  • Tree buffers size - Related to the TreeBufferSizeInMB parameter in the server.conf file.
    Set this size (in MB) to serialize directory trees. With large trees (+50k files and directories), increasing this number greatly helps reducing memory allocations.
Trigger variables
Use this section to add the custom global variables that are used in triggers.
Learn how triggers work and how to define them.

Audit configuration

The Plastic SCM administrator can set up the auditing level as well as the auditing log file name.

Don't forget to Apply for changes to take effect.

Audit configuration

By default, the audit log is active and set to log level 1 on the file audit.log. The audit log file is stored in the Plastic SCM server installation directory.

There are 5 auditing levels:

  • 0. Do not log anything on the audit log - No operation will be logged in the audit file.
  • 1. Log deleted objects - Only the operations related to deleting objects will be logged.
  • 2. Log access denied to objects - If a user is denied access to objects and tries to access them, then this operation will be logged.
  • 3. Log Added/Edited/Renamed objects - Log any action related to the operations add, edit or rename over a Plastic object.
  • 4. Log read access to revisions - Log any access to any revision, for example, when switching to a changeset or a branch, or when diffing two revisions.
  • Note that each auditing level includes the previous one.

An audit log file includes a line for any logged operation with the following structure:

<HASH> <user> (<machine>) <timestamp> [<repository>]: <operation>

Where:

  • HASH - It's the unique identifier of the logged operation.
  • user - The user/developer who performed the operation.
  • machine - The machine which operation is performed from.
  • timestamp - When the operation was performed.
  • repository - The repository that was affected by the operation.
  • operation - The description of the performed operation.

This is an example of an audit log file:

MHXET08/RpZQaJWXLlU/v7ovDPugjEOBSG9/74HFgD8= maria (HERMES) 6/23/2017 5:11:31 PM [doom3src]: Branch deleted: scm15478 (7991)
ZDSSKBGFy6SRg/O38WiyJzHbhqmUCq7SMoMp3Eqfiuc= maria (HERMES) 6/23/2017 5:44:06 PM [doom3src]: Deleted '/README.txt' (changeset 8375)
dhZG9IWM10FoHTGF+amMEeErFmHkZ2KIIL1t/uwxtYI= sue (HERMES) 6/23/2017 5:49:46 PM [doom3src]: Access denied to object 'rep:10', operation 'view'
q23jnDUDPZAicF2bYWZOWihMbXRn3/JLYSJDqOW1xJ4= maria (HERMES) 6/23/2017 5:56:14 PM [doom3src]: New label: BL064 (8408) applied to changeset 8398
k2L9HjEMqktYo7tDZQuo9PghlHgs+BMH+q3oFspRm/8= maria (HERMES) 6/23/2017 5:58:04 PM [doom3src]: Comment changed on '8408' from '' to 'Label audit test'
u84wRigufEZTKUcQrwJSjcLIxyV9b3LjwyyuX8pLUII= maria (HERMES) 6/23/2017 5:58:25 PM [doom3src]: New attribute: 'review' (8409)
AJSY/4c4QeuHU8GKIYzIdI92k6JiZoa5/ye73YIzolI= maria (HERMES) 6/23/2017 6:04:49 PM [rep03]: New branch: /main (3)
e7Mb3A49LcohQWzOCk9pAnT6Pvz5JgWNIuqthgh69BA= maria (HERMES) 6/23/2017 6:04:49 PM [rep03]: New repository: rep03 (577)
3B4jcQwNsgpi7NueKwV6rFU7vgfH1rAAQ6t+hQyXZ6U= maria (HERMES) 6/23/2017 6:17:45 PM [doom3src]: Attribute 'review' renamed to 'reviewed' (8409)
/BKLej1sb66/FlqJ/9Hr/8oiV/R50nP/oR5UEwCmbO4= maria (HERMES) 6/23/2017 6:19:58 PM [doom3src]: Comment changed on '8425' from 'Renamed' to 'File renamed'
jvck2dfnGSosVXSeLYkSzNOaFZZY1Z8AcEJtWoSx59w= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 2276
2YqWTWGEw+UbuZRYfo2ZiDEKYRMBZyGc+Tc+myQqtPc= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 7343
WrA0T9Pq276DqFxDLhoVI1gnfdWzKNEo69refw8q640= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 8016
FxFNosrb4XuAOyzwsOsiOsISgdy5S7kY5wXxPKyP/5E= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 8320

It is possible to collect hashes regularly by scheduling the tail command, for example tail -n 1 audit.log |mail admin@myorg.com.


Security

This section lets you configure the following settings:

  • Change the Administration console password - This is the password you must enter to access to the Plastic SCM Server Administration Console to apply the required changes to the server settings.
  • Reset the Plastic SCM Server administrator - The server administrator is the owner of the repository server. You can reset the server administrator from here.
Security configuration

Lock rules

Locking is useful to handle files that cannot be merged. Learn how to manage the required lock rules.


License

The Plastic SCM administrator can configure the Plastic license information such as type, licensed users, license file, and so on.

License

Support

If you have any issues, want to request us to include a new Plastic SCM feature, or need some help from our support team, the Support section will help you to contact us:

  • You can go to the Plastic SCM forum or to our Stack Overflow site if you need to solve any issues.
    If you need to directly contact to our support team, then you can Create a ticket to tell us how we can help you.
    Support - Issues
  • Don't hesitate to contact us too if you have an idea about a new Plastic feature or improvement. We invite you to join to our UserVoice space where you can leave your suggestions and rank ideas.
    Support - Suggestions
  • Sometimes we need you to send us some Plastic information like configurations, log files, and so on. To ease this process, just click to Create a bundle. This action creates a zip with the required files. Then, send it to the support team member you are in contact.
    Support - Info bundle

Monitor

The Plastic SCM Server Administration console includes several pages and panels that let you monitor the Plastic SCM Server live activity:

  • Performance:
    Monitor - Performance
  • Performance - Counters:
    Monitor - Performance counters
  • Performance - Active method calls:
    Monitor - Performance active method calls

Chapter 7: Configuring exclusive checkout (Lock)

Exclusive checkout, or locking a file, is useful in many scenarios where it's impossible to merge changes, like with:

  • Binary files
  • Images, art, and 3D content
  • Excel files

How does the exclusive checkout work?

Each time Plastic SCM is going to perform a check-out, the client asks the server whether the file needs to be exclusively checked out or not.

The system performs the following operations:

  • Is the file locked? If so, it can't be checked out.
  • If it isn't locked, the file is potentially "lockable". Plastic SCM will check whether the file name matches any of the rules defined on lock.conf. If the file name matches the rules, the file will be locked.
lock.conf diagram

In fact, checking whether the files are candidates for a lock is performed at the client side so that files that are not potentially lockable are never checked and overall performance is not affected.


Configuring the exclusive checkout

Configuring exclusive checkout is as simple as adding or editing locking rules to the required repositories. Just follow one of these methods:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Lock rules.
    Lock rules configuration
  3. Click Add to specify the rules related to a particular repository.
  4. Enter the name of the repository where the rules will apply.
  5. Specify your own rules or load the suggested common lock rules by clicking Generate common rules (you can edit them as well).
  6. Repeat the steps above as many repositories need lock rules. Or Delete the rules for a repository if they aren't needed.
  7. Click Apply to save the changes.

Using the lock.conf file

  1. Create or edit the lock.conf file on the server's directory with the following format:
    rep:<repname> lockserver:<server>:<port>

    Where:

    • repname is the name of the repository where you want to perform exclusive checkouts.
    • server is the ip or the name of the lock server.
    • port is the port where the lock server is configured.
  2. Then, configure the paths that will be exclusive checkouts. You can specify complete paths or patterns. Specify each rule in a new line. For example,
    rep:default lockserver:mainsvr:8084
    *.doc
    *.xls
    *.jpg
    document.vcs
    

    This means that the *.doc, *.xls, *.jpg and document.vcs files are going to be locked on checkout for repository default.

    See more examples in the next section.

  3. Repeat the steps above to create exclusive checkouts for the required repositories.
  4. Save the lock.conf file.

Locks and paths

Previously, we saw how to lock some types of files existing in a repository. But sometimes what you'll need is to lock a directory or some files under a specific folder.

We're going to see how to use these locks using some examples.

Rule Description
\prj\Assets\Standard Assets\Toon Shading
Lock everything under the \prj\Assets\Standard Assets\Toon Shading folder
\prj\Assets\Standard Assets\Tree Creator\Trees\Big*.meta
Lock everything under the \prj\Assets\Standard Assets\Tree Creator\Trees folder that begins with Big and ends with .meta
!\prj\Assets\Standard Assets\Tree Creator\Trees\BigTree_textures.meta
Never lock the BigTree_textures.meta file under the \prj\Assets\Standard Assets\Tree Creator\Trees folder. This rule overwrites the previous one
**\Library\*.prefs
Lock every file that ends with .prefs and is under any folder called Library

Each time you checkout on a path that meets any of the filtered rules, this path will be in exclusive checkout so that no one else can perform a checkout on it at the same time.


Chapter 8: Repository storage configuration

Plastic SCM supports several backends to store the repository data. This is the list of the supported backends:

After the first installation, the Plastic SCM server is configured, by default, with the Jet backend.

This chapter will show you how to configure Plastic SCM to work with certain backends assuming you are going to start up from a clean state. But, what if you need to migrate your current repositories into another backend?

Plastic SCM uses both standard databases and structures and our own backend:

  • You'll just have to import the data using a standard migration tool (a quick search on google will help, see also DbNetCopy or the built-in SQL Server migration tool, in case you want to migrate to MS SQL Server).
  • Or, just read this chapter to learn how to migrate your data using the Plastic SCM Server Administration console.

Configure Plastic SCM with Jet

We have designed a new storage for our repositories:

  • Jet is super-fast and scalable.
  • Jet has been designed specifically to deal with the way in which Plastic handles data and metadata read and writes. As a special purpose storage, it is hard to beat in terms of efficiency.

We created support for 2 different workloads in Jet:

  • Small server workload support - Perfect to handle local repository replicas on laptops and workstations and even small team servers. It focuses on performance and not scalability.
  • High-scalability workload support - A more complex alternative focused on scalability workloads.

We still support SQL databases (MySQL, SQL Server, SQLite, Firebird and a few others), but Jet is enabled as the default backend during evaluations. For Enterprise, the high-scalability engine is enabled.

In terms of performance, Jet runs circles around all the other alternatives. It is about 10 to 40 times faster than SQLite and SQL Server in metadata reads and writes, which makes the server up to 3-5 times faster in operations like big checkins. Jet is so fast that we were able to find other hotspots once the data layer was no longer the slow part, and we continue optimizing the server thanks to it. We will share the results of the benchmarks we ran both on Windows and Linux to compare to the other databases and also Git, which we now consistently beat even on Linux.

Follow one of these methods to configure the Plastic SCM Server to work with Jet:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Repository storage
  3. If the server is configured to work with another backend different from Jet, then you need to change to the Jet repository storage:
    1. Click Change storage.
    2. Select Jet as your new repository storage.
    3. If you want to create the databases on an specific path, then enter a Database path. Or, leave it empty to save the databases under the server folder in the Plastic SCM installation directory.
    4. Choose whether you want to Migrate existing repositories or start with new empty repositories.
    5. Click Change storage to change to the new storage.
      Please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.
    6. You will see the migration status page, indicating the overall progress of the operation and the progress of each individual repository.
  4. Configure the needed values for the following parameters:
    • Database path - Optionally, you can set the directory where the Plastic SCM server will ask the Jet backend to store the physical files.
      Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
    • Max size of blob files - Each repository contains one or more blob files to store versioned file contents. Once the maximum size (in GB) for a file is reached, a new file is created. This way, files don't grow too large for the underlying file system.
    • Max cached trees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.

Using the jet.conf file

Edit/Create the jet.conf file under the server folder in the Plastic SCM installation directory to work with Jet:

  1. Specify the basepath where the repositories data files will be stored.
    Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
  2. You can also specify the following parameters:
    • prefix and suffix values:
      This is a valid jet.conf file:
      basepath=c:\Users\maria\plasticdb
      prefix=zero
      suffix=
      
    • datafilesize - Each repository contains one or more blob files to store versioned file contents. Once the maximum size (in GB) for a file is reached, a new file is created. This way, files don't grow too large for the underlying file system.
    • maxcachedtrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.

Configure Plastic SCM with Firebird, SQLite or SQL Server CE (Embedded)

Plastic SCM is flexible and it supports a great number of database engines. Some of them are embedded systems which means that you don't need anything external to start working with them.

Firebird, SQLite and SQL Server Compact Edition belong to this group.

Follow one of these methods to configure the Plastic SCM Server to work with one of those embedded backends:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Repository storage
  3. If you don't want to change your repository storage to use another embedded backend, then jump to step 4. Otherwise:
    1. Click Change storage.
    2. Select Firebird, SQLite or SQL Server Compact Edition as your new embedded repository storage.
    3. Enter a Database path if you want to create the databases on an specific path. Or, leave it empty to save the databases under the server folder in the Plastic SCM installation directory.
    4. Choose whether you want to Migrate existing repositories or start with new empty repositories.
    5. Click Change storage to change to the new storage.
      Please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.
    6. You will see the migration status page, indicating the overall progress of the operation and the progress of each individual repository.
  4. Configure the needed values for the following parameters:
    • Connection string - In general, you only need to fill in the database server name, the user and the password values to connect to the database backend.
      Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
    • Database path - Optionally, you can set the directory where the Plastic SCM server will ask the database backend to store the database physical files.
      Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
      It is common to have a database server with a faster or bigger secondary disk (different than the one used for the system). Normally, you can specify where to create databases when you create them in a backend, but since Plastic SCM creates the databases itself, it's easier to specify the location here, in case you don't want to use the default.
    • Max cached trees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • Command timeout - Set the time (in seconds) available for each database command.
    • Comment limit - You can also set the maximum lenght for the comment strings in the database.
    • Tree revisions single read limit - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.

Using the db.conf file

Edit/Create the db.conf file under the server folder in the Plastic SCM installation directory to work with Firebird, SQLite or SQL Server CE:

  1. Enter the required value for the ProviderName key: firebird, sqlite or sqlserverce.
  2. Specify the ConnectionString - In general, you only need to fill in the database server name, the user and the password to connect to the database backend.
    Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
  3. Optionally, specify the DatabasePath where the database will be created. If you don't add this line, then the databases will be saved under the server folder in the Plastic SCM installation directory.
    Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
    It is common to have a database server with a faster or bigger secondary disk (different than the one used for the system). Normally, you can specify where to create databases when you create them in a backend, but since Plastic SCM creates the databases itself, it's easier to specify the location here, in case you don't want to use the default.

    This is a valid db.conf file for using with an embedded Firebird backend:

    <DbConfig>
      <ProviderName>firebird</ProviderName>
      <ConnectionString>ServerType=1;User=SYSDBA;Password=masterkey;Database={0};Pooling=true;connection lifetime=60;Charset=UNICODE_FSS;</ConnectionString>
      <DatabasePath>d:\plasticrep</DatabasePath>
    </DbConfig>
    
    Note that you can use this db.conf file if you want to work with a Firebird Server installation instead the embedded one. In this case you only have to change the value of the ServerType parameter to assign a 0 and the DatabasePath.

    For the embedded SQLite database backend this is a sample for the db.conf file:

    <DbConfig>
      <ProviderName>sqlite</ProviderName>
      <ConnectionString>Data Source={0};Pooling=true</ConnectionString>
    </DbConfig>
    

    This is the case for the embedded MS SQL Server CE database backend:

    <DbConfig>
      <ProviderName>sqlserverce</ProviderName>
        <ConnectionString>DataSource={0};Persist Security Info=False;Max Database Size=4090;Max Buffer Size = 4096;Password=;</ConnectionString>
      <DatabasePath>d:\plasticrep</DatabasePath>
    </DbConfig>
    
  4. And, you can also configure the following parameters:
    • DatabasePrefix - You can create prefixes for your database.
      Here is a SQLite db.conf example using this option:
      <DbConfig>
        <ProviderName>sqlite</ProviderName>
        <ConnectionString>Data Source={0};Pooling=true</ConnectionString>
        <DatabasePrefix>production_databases_</DatabasePrefix>
      </DbConfig>
      
      Or you can use the Plastic command line as follows: plasticd --console --dbprefix=production_databases_
    • DatabaseSuffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
    • CommandTimeout - Set the time (in seconds) available for each database command.
    • MaxCachedTrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • FullTreeRevisionsLoad - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
    • CommentLimit - You can also set the maximum lenght for the comment strings in the database.
    • IsolationLevel - Override the ACID isolation level setting for the configured embedded database backend.
      Important remark! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. We recommend not to touch this setting on your own. For further info, ask Plastic SCM support at support@codicesoftware.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Configure Plastic SCM with PostgreSQL

Follow one of these methods to configure the Plastic SCM Server to work with PostgreSQL:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Repository storage
  3. If the server is configured to work with another backend different from PostgreSQL, then you need to change to the PostgreSQL repository storage:
    1. Click Change storage.
    2. Select PostgreSQL as your new repository storage.
    3. Configure the connection information:
      • Enter the Server, User and Password values to connect to your PostgreSQL server. And Generate connection string.
      • Or, directly enter the Connection string value.
    4. Choose whether you want to Migrate existing repositories or start with new empty repositories.
    5. Click Change storage to change to the new storage.
      Please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.
    6. You will see the migration status page, indicating the overall progress of the operation and the progress of each individual repository.
  4. If you need to edit some settings, then configure the needed values for the following parameters:
    • Connection string - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to PostgreSQL.
      Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
    • Max cached trees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • Command timeout - Set the time (in seconds) available for each database command.
    • Comment limit - You can also set the maximum lenght for the comment strings in the database.
    • Tree revisions single read limit - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.

Using the db.conf file

Edit/Create the db.conf file under the server folder in the Plastic SCM installation directory to work with PostgreSQL:

  1. Enter the postgresql value for the ProviderName key.
  2. Specify the ConnectionString - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to PostgreSQL. But, the Port value can be also needed.
    Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

    This is a valid db.conf file configured with PostgreSQL:

    <DbConfig>
      <ProviderName>postgresql</ProviderName>
      <ConnectionString>
        Server=venus;Port=5432;Database={0};User ID=postgres;Password=mypwd;Pooling=false;
      </ConnectionString>
      <DatabasePath></DatabasePath>
    </DbConfig>
    
  3. And, you can also configure the following parameters:
    • DatabasePrefix - You can create prefixes for your database.
      Or you can use the Plastic command line as follows: plasticd --console --dbprefix=production_databases_
    • DatabaseSuffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
    • CommandTimeout - Set the time (in seconds) available for each database command.
    • MaxCachedTrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • FullTreeRevisionsLoad - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
    • CommentLimit - You can also set the maximum lenght for the comment strings in the database.
    • IsolationLevel - Override the ACID isolation level setting for the configured embedded database backend.
      Important remark! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. We recommend not to touch this setting on your own. For further info, ask Plastic SCM support at support@codicesoftware.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Configure Plastic SCM with SQL Server

Supported SQL Server versions
Plastic SCM supports SQL Server 2005 or higher, basically due to new transaction isolation levels introduced with 2005. It can be configured to work with both SQL Server and SQL Server Express editions, but remember the latter has some size constraints. For instance, if you prefer SQL Server Express edition over Firebird, you can use it in your laptop (remember, we support distributed development and replication) to work with Plastic SCM while you're disconnected.

Follow one of these methods to configure the Plastic SCM Server to work with SQL Server:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Repository storage
  3. If the server is configured to work with another backend different from SQL Server, then you need to change to the SQL Server repository storage:
    1. Click Change storage.
    2. Select SQL Server as your new repository storage.
    3. Configure the connection information:
      • Enter the Server, User and Password values to connect to your SQL Server. And Generate connection string.
      • Or, directly enter the Connection string value.
    4. If you want to create the databases on an specific path, then enter a Database path. Or, leave it empty to save the databases under the server folder in the Plastic SCM installation directory.
    5. Choose whether you want to Migrate existing repositories or start with new empty repositories.
    6. Click Change storage to change to the new storage.
      Please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.
    7. You will see the migration status page, indicating the overall progress of the operation and the progress of each individual repository.
  4. If you need to edit some settings, then configure the needed values for the following parameters:
    • Connection string - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to PostgreSQL.
      Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
    • Database path - Optionally, you can set the directory where the Plastic SCM server will ask the database backend to store the database physical files.
      Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
      It is common to have a database server with a faster or bigger secondary disk (different than the one used for the system). Normally, you can specify where to create databases when you create them in a backend, but since Plastic SCM creates the databases itself, it's easier to specify the location here, in case you don't want to use the default.
    • Max cached trees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • Command timeout - Set the time (in seconds) available for each database command.
    • Comment limit - You can also set the maximum lenght for the comment strings in the database.
    • Tree revisions single read limit - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
    • Database creation command - You can customize the creation of SQL Server databases (repositories). Learn how to configure this Database creation command.
    • Database collation - By default, Latin1_General_CI_AI. It can be modified to support special characters on specific cultures.
    • Column collation - By default, is the collation of the master database.
    • IN clause limit - When searching for individual objects, SQL Server uses an IN clause for sets smaller than the value of this setting. Otherwise, they use a temporary table.
    • BULK insert min rows - Threshold to use bulk copy to insert many rows.
    • Temp table min rows for select - Number of objects to use a temporary table for faster queries.
    • Bulk copy lock table min rows - Minimum number of rows to insert in bulk copy that will apply table lock for faster performance.
    • Max rows for multi-row insert - Disabled if set to zero. The server will insert as many rows as stated by this setting with each INSERT clause.

Using the db.conf file

Edit/Create the db.conf file under the server folder in the Plastic SCM installation directory to work with SQL Server:

  1. Enter the sqlserver value for the ProviderName key.
  2. Specify the ConnectionString - In general, you only need to fill in the database Server name, the User ID and the Pwd values to connect to SQL Server.
    Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

    This is a valid db.conf file configured with SQL Server Express:

    <DbConfig>
      <ProviderName>sqlserver</ProviderName>
      <ConnectionString>
        SERVER=beardtongue\SQLEXPRESS;User Id=sa;Pwd=master;DATABASE={0};
      </ConnectionString>
    </DbConfig>
    

    In the example above, the connection string use built-in SQL Server authentication which is basically telling Plastic to use a given user and password. If you want to use built-in Windows authentication, then you need to replace the user and password values with the trusted_connection=yes key:

    <DbConfig>
      <ProviderName>sqlserver</ProviderName>
      <ConnectionString>
          SERVER=beardtongue\SQLEXPRESS;trusted_connection=yes;DATABASE={0};
      </ConnectionString>
    </DbConfig>
    
    Since you'll normally run the Plastic SCM server under the system account on Windows, you need to ensure that account has rights to access to your SQL Server database under trusted connection. You can always change the Plastic SCM service configuration to make it run under different credentials.
  3. Optionally, specify the DatabasePath where the database will be created. If you don't add this line, then the databases will be saved under the server folder in the Plastic SCM installation directory.
    Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
    It is common to have a database server with a faster or bigger secondary disk (different than the one used for the system). Normally, you can specify where to create databases when you create them in a backend, but since Plastic SCM creates the databases itself, it's easier to specify the location here, in case you don't want to use the default.
  4. And, you can also configure the following parameters:
    • DatabaseCreationCommands - You can customize the creation of SQL Server databases (repositories). Learn how to configure this Database creation command.
    • DatabasePrefix - You can create prefixes for your database.
      Or you can use the Plastic command line as follows: plasticd --console --dbprefix=production_databases_
    • DatabaseSuffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
    • DatabaseCollation - By default, Latin1_General_CI_AI. It can be modified to support special characters on specific cultures.
    • ColumnCollation - By default, is the collation of the master database.
    • CommandTimeout - Set the time (in seconds) available for each database command.
    • MaxCachedTrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • FullTreeRevisionsLoad - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
    • CommentLimit - You can also set the maximum lenght for the comment strings in the database.
    • InClauseLimit - When searching for individual objects, SQL Server uses an IN clause for sets smaller than the value of this setting. Otherwise, they use a temporary table.
    • BulkInsertMinSize - Threshold to use bulk copy to insert many rows.
    • MultiFieldTmpTableMinSize - Number of objects to use a temporary table for faster queries.
    • BulkLockTableMinSize - Minimum number of rows to insert in bulk copy that will apply table lock for faster performance.
    • MultiRowInsertMaxSize - Disabled if set to zero. The server will insert as many rows as stated by this setting with each INSERT clause.
    • IsolationLevel - Override the ACID isolation level setting for the configured embedded database backend.
      Important remark! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. We recommend not to touch this setting on your own. For further info, ask Plastic SCM support at support@codicesoftware.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Database creation command

The SQL Server database creation command can be customized with your own settings.

Remember that the command must be written in a single line. The following is an example written in several lines to improve the readability.
<DbConfig>
  <ProviderName>sqlserver</ProviderName>
  <ConnectionString>SERVER=beardtongue\SQLEXPRESS;trusted_connection=yes;DATABASE={0};</ConnectionString>
  <DatabaseCreationCommands>
    CREATE DATABASE @PlasticDatabase ON PRIMARY
    (NAME=@PlasticDatabase_custom, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100) 
    LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100) 
    COLLATE @PlasticDefaultCollation
  </DatabaseCreationCommands>
  <DatabasePath></DatabasePath>
</DbConfig>

You can use the following variables to build your own database creation command:

Variable Description
@PlasticDatabase

The database name. It's mandatory that the database creation command begins with CREATE DATABASE @PlasticDatabase.

@PlasticDefaultDatabaseFile

The default database file. Can be overwritten with a path that includes @PlasticDatabase as a part of the database file name.

@PlasticDatabase_log

The default log file name. Can be overwritten.

@PlasticDefaultLogFile

The default log file path. Can be overwritten using @PlasticDatabase as a part of the file name or appending a suffix to the variable @PlasticDefaultDatabaseFile, for example, @PlasticDefaultDatabaseFile.log.

@PlasticDefaultCollation

It's the collation defined in the db.conf with the key DatabaseCollation. If it doesn't exist then the collation mode will be the default one used by Plastic: Latin1_General_CI_AI. You can override it in the custom command. The collation in the custom command has priority over the DatabaseCollation value in the db.conf file.

Important: you must specify a valid collation in the custom creation command if your SQL Server default collation is not case insensitive or accent insensitive. Valid collations are "Case Insenstive" and "Accent Insensitive" collations (CI_AI or KI_KS collation suffixes). Otherwise, this could generate some strange behaviors.

This is the default command Plastic uses to create databases when the <DatabaseCreationCommands> key is not in your db.conf file:

CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100) 
LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100) 
COLLATE @PlasticDefaultCollation 

Here are some custom database creation command examples:

The commands here are splitted in several lines for readability purposes.
  • Multiple commands. Must be separated with ";" and specified in a single line. You can't use the "GO" clause:
    <DatabaseCreationCommands>
      CREATE DATABASE @PlasticDatabase ON PRIMARY
      (NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100) 
      LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100) 
      COLLATE @PlasticDefaultCollation;ALTER DATABASE @PlasticDatabase SET PAGE_VERIFY CHECKSUM;ALTER DATABASE @PlasticDatabase SET ANSI_WARNINGS OFF
    </DatabaseCreationCommands>
    
  • Change database file location and log names and paths:
    <DatabaseCreationCommands>
      CREATE DATABASE @PlasticDatabase ON PRIMARY
      (NAME=@PlasticDatabase, FILENAME='C:/databases/dbs/@PlasticDatabase.db', SIZE=10, FILEGROWTH=100) 
      LOG ON (NAME=PlasticLog_@PlasticDatabase, FILENAME='C:/databases/logs/@PlasticDatabase.log', SIZE=10, FILEGROWTH=100) 
      COLLATE @PlasticDefaultCollation 
    </DatabaseCreationCommands>
    
  • Change size parameters or collation:
    <DatabaseCreationCommands>
      CREATE DATABASE @PlasticDatabase ON PRIMARY
      (NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=100, FILEGROWTH=50) 
      LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=100, FILEGROWTH=50) 
      COLLATE SQL_Latin1_General_CP1_CS_AS
    </DatabaseCreationCommands>
    

Troubleshooting the new connection

Setting up a SQL Server backend should be really easy, but you know problems can always show up! If this is the case, remember to check the loader.log.txt file under the server folder in the Plastic SCM installation directory. This file contains the Plastic server log. The most common connection problems to check are:

  • You incorrectly typed the server.
  • The user and password are not correct (integrated security).
  • The account running the Plastic SCM server doesn't have rights to connect to SQL Server (trusted connection).

Configure SQL Server memory usage

Memory is an important feature to configure in your SQL Server installation particularly if you don't have a dedicated server for it. The system will perfom better if you limit your SQL Server memory than if you let it grow as much as it can.

So, how can you limit SQL Server memory? If you're using SQL Server Express you'll have to do it with the sp_configure stored procedure. If you use a regular SQL Server, you'll be able to configure it from the admin application. Running the stored procedure is simple:

USE master
EXEC sp_configure 'show advanced options', 1
RECONFIGURE WITH OVERRIDE

USE master
EXEC sp_configure 'max server memory (MB)', 300
RECONFIGURE WITH OVERRIDE

This limits it to 300Mb.

Check out the following links for more information:


Configure Plastic SCM with MySQL

Follow one of these methods to configure the Plastic SCM Server to work with MySQL:

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Go to Configuration > Repository storage
  3. If the server is configured to work with another backend different from MySQL, then you need to change to the MySQL repository storage:
    1. Click Change storage.
    2. Select MySQL as your new repository storage.
    3. Configure the connection information:
      • Enter the Server, User and Password values to connect to your MySQL server. And Generate connection string.
      • Or, directly enter the Connection string value.
    4. Choose whether you want to Migrate existing repositories or start with new empty repositories.
    5. Click Change storage to change to the new storage.
      Please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.
    6. You will see the migration status page, indicating the overall progress of the operation and the progress of each individual repository.
  4. If you need to edit some settings, then configure the needed values for the following parameters:
    • Connection string - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to MySQL.
      Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
    • Max cached trees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • Command timeout - Set the time (in seconds) available for each database command.
    • Comment limit - You can also set the maximum lenght for the comment strings in the database.
    • Tree revisions single read limit - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.

Using the db.conf file

Edit/Create the db.conf file under the server folder in the Plastic SCM installation directory to work with PostgreSQL:

  1. Enter the mysql value for the ProviderName key.
  2. Specify the ConnectionString - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to MySQL.
    Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

    This is a valid db.conf file configured with PostgreSQL:

    <DbConfig>
      <ProviderName>mysql</ProviderName>
      <ConnectionString>
        Server=venus;User ID=myuser;Password=mypwd;Database={0};Pooling=true
      </ConnectionString>
      <DatabasePath></DatabasePath>
    </DbConfig>
    
  3. And, you can also configure the following parameters:
    • DatabasePrefix - You can create prefixes for your database.
      Or you can use the Plastic command line as follows: plasticd --console --dbprefix=production_databases_
    • DatabaseSuffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
    • CommandTimeout - Set the time (in seconds) available for each database command.
    • MaxCachedTrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • FullTreeRevisionsLoad - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
    • CommentLimit - You can also set the maximum lenght for the comment strings in the database.
    • IsolationLevel - Override the ACID isolation level setting for the configured embedded database backend.
      Important remark! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. We recommend not to touch this setting on your own. For further info, ask Plastic SCM support at support@codicesoftware.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Finally, we must set the MySQL configuration parameter max_allowed_packet to support up to 10MB. If you require more information about how configure this parameter, you can take a look at this article.

Note:In some Linux distributions like Arch Linux, the MySQL server does not listen on the TCP port 3306 by default. To allow (remote) TCP connections, comment the following line in /etc/mysql/my.cnf: skip-networking

How to fine tune MySQL for Plastic SCM

Out of the box, MySQL installations have a pretty conservative default configuration. If you have server machine to be used with Plastic SCM, you may want to adjust these configuration settings in the my.cnf file (or my.ini, in Windows) to improve the performance of the server. These adjustments have a huge impact in the speed of Plastic SCM.

Hardware

The performance of MySQL and the Plastic SCM server depend largely on the amount of memory and CPU available. As usual with performance tuning, there is no one-size-fits-all answer, but these guidelines may be useful to squeeze more out of your hardware.

For this article, we are assuming that you have a decent machine, dedicated to the Plastic SCM server and MySQL exclusively, with 4GB of RAM.

Edit the my.cnf file, normally located in /etc or /etc/mysql in Linux, or the c:\Program Files\MySQL\my.ini file in Windows. Add or edit the lines below:


  • The innodb_buffer_pool_size should be around half of the memory of your server machine. This is the most important value. Note that due to a limitation in MySQL, this value should be maximum 4GB (more details here):
    innodb_buffer_pool_size = 2G
  • innodb_additional_mem_pool_size should be a 5% of the innodb_buffer_pool_size:
    innodb_additional_mem_pool_size = 100M
  • Set innodb_log_file_size to 25% of buffer pool size:
    innodb_log_file_size = 500M

    Keep in mind that changing this value renders your ib_logfileX files unusable (they are located in the data directory), and MySQL may refuse to start until the files are removed and MySQL can recreate them. Make sure that MySQL was shut down correctly before removing these files.

  • innodb_log_buffer_size can be around 2% of the buffer pool size or, at a minimum, 8MB:
    innodb_log_buffer_size = 40M

Once these settings are in place, restart the MySQL service.

Also, don't forget to set the max_allowed_packet to 10MB. This is mandatory for correct Plastic SCM operation:

max_allowed_packet = 10M

Chapter 9: Backup and restore

The backup and restore procedures are closely related to the database backend used in Plastic SCM.

Important: The instructions in this chapter are meant only for the embedded and Jet backends.
If you configured a different database backend, please check with your database administrator what are the best backup procedures for it.

How to backup and restore the embedded databases

How to backup the embedded databases

Backing up the embedded databases is just about copying the database files from disk. Each database will be a single file, so the operation is pretty simple. However, backing such a database file requires that the Plastic SCM server be stopped.

Note: This is one of the drawbacks of the embedded backends that is normally better handled by the other supported backends such as MySQL, MS SQL Server or PostgreSQL. This is one of the reasons why we recommend using the embedded backends for evaluation purposes only.

Starting and stopping the Plastic SCM server on the command line has been described in the previous sections, so the following procedure can be easily automated with scripts.

Steps to backup:

  1. Stop the Plastic server.
  2. Backup the database files. You can find them in the server installation directory or in the database path specified during the database setup. The database files are repositories.plastic.* and rep_**.plastic.*.
  3. Start the Plastic server again.

Restore embedded databases

The restore procedure is very similar to backup in reverse order:

  1. Stop the Plastic server.
  2. Copy all the backup files to the server installation directory or to the database path you want (remember to set the right setting for the database path in the db.conf file).
    If you want to restore only one repository, restore only the rep_xx.plastic.* file for that repository.
    The repositories.plastic.* file contains the list of repositories that are registered on the system, while the rep_xx.plastic.* files contain the data for each repository.
  3. Start the Plastic server again.

How to backup and restore the Jet backend

The Jet backup operation is easy to achieve. You can follow one of these options to backup and restore your Jet data:

  • Cold copy - This procedure requires to stop and start the Plastic SCM server.
  • Hot copy - This method requires to switch the Plastic SCM server between normal and read-only modes.

Cold copy

In this section, you can find the steps to follow to perform the cold backup and restore operations.

You can also check an example explaining how to perform cold backup with Rdiff.

Backup
  1. Stop the Plastic server.
  2. Backup the Jet content. You can find it in the basepath parameter specified during the database setup (check the jet.conf file).
  3. Start the Plastic server again.
Restore
  1. Stop the Plastic server.
  2. Restore all the backup files to the path you configured (remember to set the right setting for the path in the jet.conf file).
  3. Start the Plastic server again.

Hot copy

This section explains how to perform the hot backup and restore operations.

Check an example explaining how to perform a hot backup with Rdiff.

Backup
  1. Set the Plastic server to read-only mode ( cm admin readonly enter ).
  2. Backup the Jet content. You can find it in the basepath parameter specified during the database setup (check the jet.conf file).
  3. Set the Plastic server to normal mode.
Restore
  1. Set the Plastic server to read-only mode.
  2. Restore all the backup files to the path you configured (remember to set the right setting for the path in the jet.conf file).
  3. Set the Plastic server to normal mode.

Tools

You can perform the backup and restore operations manually or using your backup tool. We tested the following tools both on Windows and Linux:

Tool Restore Incremental Comments
Bvckup2 Minimalistic tool, really easy to use.
This tool doesn't provide a retore backup feature. You just need to re-copy the backup content to the original path.
CrashPlan Cloud backup solution.
Rsync Widely used for Unix platforms. You'll likely have this tool as part of your Unix OS.
This tool also allows remote machines copies through ssh:
rsync -a -e ssh source/ username@remotemachine.com:/path/to/destination/
Rdiff-backup Widely used for Unix platforms, it supports Windows too. Very easy to use and robust.
You can see below two examples using this tool to perform a cold backup and a hot backup.
Duplicati Easy to install and use, provides a web interface in order to setup and trigger incremental backups.
Nticorp Local and Cloud backup/restore.
Rdiff-backup - Cold copy example

Let's see how we setup a weekly and incremental backup using rdiff-backup on a Linux machine:

  1. We installed rdiff-backup 1.2.8 in our server.
  2. Then, we configured autofs to auto-mount backup NFS folder in the /cifs/backup folder.
  3. We added a cron job which is executed everyday at 3.30AM local time. This is the script job:
    #!/bin/bash
    export weekNumber='date +%V'
    export year='date +%Y'
    export today='date +%Y%m%d'
    export lastActinLogFile="/root/backup_jet.log"
    
    export dirName="week_$weekNumber"
    export baseBackupDstLocation="/cifs/backup/backups/myserver_jet"
    export backupFinalDstLocation="$baseBackupDstLocation/$year/$dirName"
    export weekIncrementsTarGzDstFile=$backupFinalDstLocation/myserver_ddbb_jetfs.rdiff-backup_$year_week_$weekNumber.tar.gz
    
    #rdiff-backup source and destination params
    export srcJetFolder="/home/mydata/jet"
    #export rdiffBackupWeekIncrementsAuxDir="/home/mydata/local_jet_backup_rsync"
    export rdiffBackupWeekIncrementsAuxDir="$baseBackupDstLocation/tmp"
    
    echo "starting daily backup $today on dst dir: $backupFinalDstLocation" > $lastActionLogFile
    
    #if we're starting a new week, reset the increments dst dir so rdiff-backup will start a fresh backup from scratch
    if [ ! -d "$backupFinalDstLocation" ]; then
      mkdir -p $backupFinalDstLocation
      #reset weekly backup local folder
      rm -rf $rdiffBackupWeekIncrementsAuxDir
    fi
    
    echo "about to stop and targz $today" > $lastActionLogFile
    /usr/sbin/plasticsd stop
    sleep 20
    rdiff-backup $srcJetFolder $rdiffBackupWeekIncrementsAuxDir
    rm $weekIncrementsTarGzDstFile
    tar cvzf $weekIncrementsTarGzDstFile  $rdiffBackupWeekIncrementsAuxDir
    sleep 20
    /usr/sbin/plasticsd start
    echo "done! $today" > $lastActionLogFile
    

How it works?

  • Incremental backups last a week.
  • At the beginning of every week, a new full-backup is created. And the following days of the week, just increments are added using rdiff-backup.
  • rdiff-backup uses a dst tmp aux folder to store the full backup plus the increments.
  • Every day, the contents of the dst tmp aux folder is tar.gz-ed and stored in a "week_xx" folder, replacing any older tar.gz file (the new tar.gz has a new increment).
  • Because the dst tmp aux folder is reset at the beginning of each week, a initial full-backup will be created the first day.

And these are the commands used to:

  • Create backups (full and also incremental if you reuse the target path): sudo rdiff-backup "/media/codice/New Volume/jet_ubuntu" "/media/codice/New Volume/rdiff_backups/"
  • How to list the incremental backups stored that you can restore them later: sudo rdiff-backup --list-increments "/media/codice/New Volume/rdiff_backups/rep_4" [sudo] password for codice: Found 3 increments: rep_4.2017-01-16T08:28:58-08:00.dir Mon Jan 16 08:28:58 2017 rep_4.2017-01-16T09:34:15-08:00.dir Mon Jan 16 09:34:15 2017 rep_4.2017-01-17T01:54:14-08:00.dir Tue Jan 17 01:54:14 2017 Current mirror: Tue Jan 17 02:01:13 2017
  • Restore an incremental backup: sudo rdiff-backup -r 8h30m --force --tempdir "/media/codice/New Volume/tmp_path" "/media/codice/New Volume/rdiff_backups/rep_4" "/media/codice/New Volume/jet_ubuntu/rep_4"

    The command above restores the last backup done prior to 8h and 30m.

    --tempdir path is used to avoid using the system tmp path and run out of disk.

Rdiff-backup - Hot copy example

We can execute the same example above, but remember that we are going to perform a hot copy, so we need to switch the server between normal and read-only modes ( cm admin readonly ) instead of stop/start it.

So, the script will be something like this:

#!/bin/bash
export weekNumber='date +%V'
export year='date +%Y'
export today='date +%Y%m%d'
export lastActinLogFile="/root/backup_jet.log"

export dirName="week_$weekNumber"
export baseBackupDstLocation="/cifs/backup/backups/myserver_jet"
export backupFinalDstLocation="$baseBackupDstLocation/$year/$dirName"
export weekIncrementsTarGzDstFile=$backupFinalDstLocation/myserver_ddbb_jetfs.rdiff-backup_$year_week_$weekNumber.tar.gz

#rdiff-backup source and destination params
export srcJetFolder="/home/mydata/jet"
#export rdiffBackupWeekIncrementsAuxDir="/home/mydata/local_jet_backup_rsync"
export rdiffBackupWeekIncrementsAuxDir="$baseBackupDstLocation/tmp"

echo "starting daily backup $today on dst dir: $backupFinalDstLocation" > $lastActionLogFile

#if we're starting a new week, reset the increments dst dir so rdiff-backup will start a fresh backup from scratch
if [ ! -d "$backupFinalDstLocation" ]; then
  mkdir -p $backupFinalDstLocation
  #reset weekly backup local folder
  rm -rf $rdiffBackupWeekIncrementsAuxDir
fi

echo "about to stop and targz $today" > $lastActionLogFile
cm admin readonly enter
sleep 20
rdiff-backup $srcJetFolder $rdiffBackupWeekIncrementsAuxDir
rm $weekIncrementsTarGzDstFile
tar cvzf $weekIncrementsTarGzDstFile  $rdiffBackupWeekIncrementsAuxDir
sleep 20
cm admin readonly leave
echo "done! $today" > $lastActionLogFile

Chapter 10: Archiving revisions


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 mentioned 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, every time 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.

How archive command works


How to archive my revisions

To archive revisions use the archive command:

cm archive C:\mybigfile.tar#br:/main#0 -c="big file of libraries" -f="/home/plastic/bigfileTARrev0"

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 (-c parameter) 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 cm help archive.

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.

Note: To create archived revisions it is mandatory that the user that executes the archive command is the repository owner. Otherwise the revision will not be archived correctly and Plastic SCM will continue using the database to access the data.
Warning: An archived revision cannot be archived again. Once a revision has been archived it is taken out the database. Be especially careful with the archived revisions or you will lose them definitely.

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:

E:\archivesOfRepository1
D:\mybigfiles\revisionsOfBigFileTAR
F:\revisionsOfThe2_9Release

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:

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.


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:

cm archive C:\mybigfile.tar#br:/main#0 --restore

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 file must be available.

To get more information of this command, type on a command line cm help archive.


Chapter 11: Upgrade system

When a new Plastic SCM release is out you have to upgrade both server and clients. Upgrading the server is easy just because it's only one machine.

In this chapter you will learn how to auto upgrade all the Plastic SCM clients.


How to configure it

Your Plastic SCM server installation should have a directory called upgrade (if not, download it from here). Inside the $plastic_install_dir\server\upgrade directory you will find four files. The upgradefiles.conf file is just an index to the location of the other 3 files; it only sets the path of the Windows, Linux and MacOS configuration files.

Then, for each operating system you can setup a few parameters, the most important is the Url: replace the default release address with the one you want to distribute along your Plastic SCM clients.


Example

This is a basic example of the upgrade-windows.xml file:

<ScriptActions>
  <Actions>
    <SetStatus Msg = "Downloading Plastic SCM installer (5.4.16.619) ..." />
    <SetDistraction Msg = "" />
    <SetProgress Value = "20" />
    <Download
      Url = "https://www.plasticscm.com/releases/5.4.16.619/plasticscm/windows/PlasticSCM-5.4.16.619-windows-installer.exe"
      ExecuteAfterDownload = "true"
      DeleteAfterExecute = "true"
      ContinueOnError = "false"
      ShowProcessWindow = "true"
      CloseUpgradeAfterRun = "true" 
      FinalProgress = "100"
    />
  </Actions>
</ScriptActions>

The SetStatus and SetDistraction inside Actions let you customize the messages displayed to the user while downloading.

Inside the Download tag we can use internal functional settings that will allow the admin to choose, for example, the behavior when something goes wrong or if the installer must be deleted after using it.

We do recommend to enable the ExecuteAfterDownload. This indicates that the installer will be automatically executed and the upgrade workflow will flow smoothly.


How it works

The Plastic SCM client checks during the start sequence if the communication with the Plastic SCM server can be established, if it's not possible due to both releases are not compatible the upgrader will ask the information of the new release to the Plastic SCM server, if the upgrade system is configured the client will show an upgrade dialog like the following one.

Dialog - New version available

Clicking the Yes button will trigger the new installer download; the download progress will be shown accordingly with the settings configured in the server upgrade files.

Dialog - Plastic SCM Upgrade

Once the new installer is downloaded, if it's configured in this way, the new Plastic SCM updater will automatically execute it.

Follow the installer wizard sequence by clicking the Next buttons.

The preferences chosen from the first Plastic SCM installation are stored so although you can change them it's not needed to modify any parameter to get the new version up and running.


How to force clients to upgrade to a given version

The Plastic SCM server can reject clients that are older than a given version. This is a great way for sysadmins to ensure the users upgrade their clients correctly.

To force a given build number, add the key ForceBuildNumberMatch in the server.conf file. This key admits the following values:

  • true - Exact build number matching is required. It means that any client or server connecting to this server must run exactly the same version.
  • false - No version match required. This is the default.
  • number - The server will reject any connections from callers running a version with a build number smaller than number. Example: 800 means any version bigger or equal than 800 will be accepted:
    <ForceBuildNumberMatch>800</ForceBuildNumberMatch>
    

Chapter 12: Plastic SCM SSL certificates

For internal application development and testing, it is often preferable to use a self-signed SSL certificate in order to avoid the cost of one signed by an external certificate authority. In this chapter, we will explain the process of creating a self-signed certificate and root Certificate Authority (CA) certificate that can be used with Plastic SCM.


Tools

Depending on your OS, you will need different tools to create a certificate. Let's see the required tools to create a certificate for your Windows, Linux or Mac system.

Windows

For Windows, you will need to install the makecert and pvk2pfx tools, available on the Windows SDK here.

You can find a complete help site for both commands in the links below:

  1. makecert (Makecert.exe) is a command-line CryptoAPI tool that creates an X.509 certificate that is signed by a system test root key or by another specified key. The certificate binds a certificate name to the public part of the key pair. The certificate is saved to a file, a system certificate store, or both.
    You can read more about MakeCert by clicking on this link: https://msdn.microsoft.com/en-us/library/windows/hardware/ff548309(v=vs.85).aspx
  2. pvk2pfx (Pvk2Pfx.exe) is a command-line tool that transfers public key and private key information contained in .spc, .cer, and .pvk files to a Personal Information Exchange (.pfx) file.
    You can read more about Pvk2Pfx by clicking on this link: https://msdn.microsoft.com/en-us/library/windows/hardware/ff550672(v=vs.85).aspx

Linux and Mac

For Linux and Mac OS, one of the most versatile SSL tools is openssl. This tool is an open source implementation of the SSL protocol.

openssl is commonly used to create the Certificate Signing Request (CSR) and private key for many different platforms. This tool comes with almost every Linux distribution so it is usually already installed and ready to use.


Creating the self-Signed certificate

Let's see how to use that tools on your Windows, Linux or Mac system.

Windows

  1. To create the self-signed certificate, you must run the makecert command to generate the .pvk and .cer files: makecert -n "CN=TARDIS" -r -a sha1 -sky exchange -sv Tardis.pvk Tardis.cer

    During the creation process, you will be asked for a password. Make a note of the password because you'll need it later for the pvk2pfx command.

  2. To create the .pfx file needed for the Plastic SCM server, you will use the pvk2pfx tool to combine the generated .pvk and .cer files into the final .pfx file: pvk2pfx -pvk "Tardis.pvk" -spc "Tardis.cer" -pfx "Tardis.pfx" -pi <password>

    It is a good idea to name the .pvk, .cer and .pfx files with the machine hostname where the Plastic SCM server is installed. If you do not use the machine hostname, you will continuously receive warnings saying that the certificate doesn't match the Plastic SCM server hostname. As you can see in the example above, we are issuing the certificate for a Plastic SCM server called Tardis, so the resulting output files are labeled as Tardis.pvk, Tardis.cer and Tardis.pfx.

The creation of the .pvk certificate is now ready to be used with the Plastic SCM server.

Linux and Mac

  1. To create the self-signed certificate, you must execute the openssl command to create the .pem file as follows: openssl req -x509 -nodes -days 3650 -newkey rsa:4098 -keyout key.pem -out key.pem

    When you execute the command, you will be prompted to answer a few questions that are required to create the certificate. The most important question is the Common Name value. It is important that you use the Plastic SCM host name that the clients use to connect with the server machine.

    In the following example, the server name is Tardis, so that is the name that is used for the Common Name field:

    Generating a 4098 bit RSA private key .............................++ ..................................++ writing new private key to 'key.pem' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:ES State or Province Name (full name) [Some-State]:VLL Locality Name (eg, city) []:BOEC Organization Name (eg, company) [Internet Widgits Pty Ltd]:Codice Organizational Unit Name (eg, section) []:Dev Common Name (e.g. server FQDN or YOUR name) []:Tardis Email Address []:info@codice.es
  2. Run the following command to export the .pem certificate file into a .pfx file: openssl pkcs12 -export -out ssl-certificate.pfx -in key.pem -name "PlasticSCM Certificate"

The .pfx file is now ready to be used with the Plastic SCM server.


Creating a CA-Signed Certificate

The Certificate Authority (CA) certificate will be used to generate additional SSL certificates for other sites or services such as the Plastic SCM server.

Let's see how to do it on your Windows, Linux or Mac system.

Windows

  1. To create a CA certificate, you need to run the makecert command to generate the .pvk and .cer files: makecert -n "CN=Codice Software S.L" -r -a sha1 -sv CodiceCA.pvk CodiceCA.cer
  2. Once the CA certificate is generated, you can create an SSL certificate by executing the following command: makecert -n "CN=TARDIS" -iv CodiceCA.pvk -ic CodiceCA.cer -sky exchange -a sha1 -pe -sv "PlasticServerTardis.pvk" PlasticServerTardis.cer
  3. Just as you did for the self-signed certificate, you will execute the pvk2pfx command which will combine the .pvk and .cer files to generate the .pfx file as follows: pvk2pfx -pvk "PlasticServerTardis.pvk" -spc "PlasticServerTardis.cer" -pfx "PlasticServerTardis.pfx" -pi <password>

Linux and Mac

  1. To create the root key, you need to execute the following openssl command : openssl genrsa -out rootCA.key 2048
  2. Once the rootCA.key file is created, it can be used to generate the self-signed certificates by executing the following command: openssl req -x509 -new -nodes -days 3560 -key rootCA.key -out key.pem
  3. Just as you did with the self-signed certificate, you will generate the .pfx file by exporting the recently created .pem file. Run the following command to export the certificate into a .pfx file: openssl pkcs12 -export -out ssl-certificate.pfx -in key.pem -name "PlasticSCM Certificate"

Using the certificate for the Plastic SCM Secure channel

By default, the Plastic SCM server SSL channel is configured to listen on port 8088 using the default SSL Plastic SCM SSL certificate.

To use your own self-signed certificate, you will need to edit the remoting.conf file that is located inside the Plastic SCM server directory. There, you must modify the following two values:

  • sslPfxFile - to use your .pfx certificate
  • sslPfxFilePassword - to specify the certificate password. You can write it in plain text but it is recommended that you encrypt it using the cm crypt command and use the cipher value instead.

Once the remoting.conf file is saved, restart the Plastic SCM server to apply the change.

The following example shows you the server remoting.conf file using the new Tardis.pfx certificate and the ciphered password:

<configuration>
    <system.runtime.remoting>
        <application>
            <channels>
                <channel type="Codice.Channels.PlasticTcpChannel,plastictcpchannel" port="8087" name="normal">
                    <serverProviders>
                        <formatter type="Codice.Channels.PlasticBinaryServerFormatterSinkProvider, plastictcpchannel" typeFilterLevel="Full" Compression="sinklevel" SerializationObjectsAtSink="true" BufferPoolMax="10"/>
                        <provider type="Codice.CM.Server.ExceptionTracerSinkProvider, servercommon" />
                    </serverProviders>
                    <clientProviders>
                        <provider type="Codice.Channels.ClientSinkProvider, plastictcpchannel" />
                        <formatter ref="binary" />
                    </clientProviders>
                </channel>
                
                <channel type="Codice.Channels.PlasticSecuredTcpChannel, plastictcpchannel" port="8088" sslPfxFile="Tardis.pfx" sslPfxFilePassword="|SoC|2ogBDa8GmifTjC7UKp4KuoF0/jWYlXy2" name="secured">
                    <serverProviders>
                        <formatter type="Codice.Channels.PlasticBinaryServerFormatterSinkProvider, plastictcpchannel" typeFilterLevel="Full" Compression="sinklevel" SerializationObjectsAtSink="true" BufferPoolMax="10"/>
                        <provider type="Codice.CM.Server.ExceptionTracerSinkProvider, servercommon" />
                    </serverProviders>
                    <clientProviders>
                        <provider type="Codice.Channels.ClientSinkProvider, plastictcpchannel" />
                        <formatter ref="binary" />
                    </clientProviders>
                </channel>
            </channels>
        </application>
    </system.runtime.remoting>
</configuration>

Accepting and installing SSL certificates for Plastic SCM

There are several methods that you can use to install the Plastic SCM certificate. You can do it by implementing one of the following methods:

Plastic SCM GUI

The first time that the Plastic SCM GUI connects with the Plastic SCM server, using the SSL port, a popup window will appear and prompt you to accept and install the new Plastic SCM server certificate:

Install certificate using the Plastic SCM GUI

Since you trust the host you will hit Yes to add the key to the Plastic SCM key store which is recommended as this is the first time you are connecting to the server using the SSL server port.

Plastic SCM Command Line Interface (CLI)

The Plastic SCM command line tool is also known as the cm executable. When you use this method to install the Plastic SCM certificate you will be prompted with a dialog to accept and install the Plastic SCM server certificate:

>cm lrep ssl://TARDIS:8088 The server you are connecting to has sent a certificate that is not in the store. This is normal if it is the first time that you connect to this server. Certificate details: - Issued to: CN=TARDIS - Issued by: CN=TARDIS - Expiration date: 01/01/2040 0:59:59 - Certificate hash: D104DDF745C50BCAF6A742280633A1D39C3D814E If you trust this host, choose 'Yes' to add the key to Plastic SCM's key store (recommended if it is the first time you connect to this server). If you want to carry on connecting just once, without adding the key to the store, choose 'No'. If you do not trust this host, choose 'Cancel' to abandon the connection. Choose an option (Y)es, (N)o, (C)ancel (hitting Enter cancels): Y default@ssl://TARDIS:8088 Cmd@ssl://TARDIS:8088 CmdRunner@ssl://TARDIS:8088 2dShooter@ssl://TARDIS:8088

Since you trust the host, you will choose Yes to add the key to the Plastic SCM key store which is recommended as this is the first time you are connecting to the server using the SSL server port.

Manual installation

In certain situations, the certificate will need to be accepted and installed without using the Plastic SCM client, for example, when a Plastic SCM server has to connect with another Plastic SCM server using the SSL port during a replication operation. Since the server itself is not able to accept a certificate, it is necessary to install the certificate file (.cer) manually.

Please keep in mind that the certificate you install will only be valid for the system user who accepts the certificate on the server. If you need to install a certificate that will be used by the Plastic SCM server, then the system user on the server will need to run the Plastic SCM server/daemon as "Administrator" or "root" user.

Let's see how to manually install the certificate on a Windows, Linux or Mac OS based server:

Windows
  1. The Microsoft Windows certmgr.msc tool is used to install the certificate files (.cer) that can be read by external applications.
  2. The certificates are imported by clicking the Action > All tasks > Import option:

    Certificate import wizard

  3. The next step is to specify the location of the certificate file (.cer) using the Browse button:

    Certificate import wizard - specify location

  4. Then, you must place the certificate file (.cer) in the "Plastic Client" store. So, click Next to place the certificate in the store:

    Certificate import wizard - store certificate

  5. The final step is to click Finish to install the certificate:

    Certificate import wizard - completing

You can confirm that the certificate is correctly installed by expanding the "Plastic Client" store and viewing the installed certificates.

Linux and MacOS

Installing the certificate on a Linux or MacOS server is as simple as copying the certificate file (.cer) to a directory:

  • For Linux use this directory path:

    /home/<Your_User>/.config/.mono/certs/Plastic Client

  • For MacOS use this directory path:

    /Users/<Your_User>/.config/.mono/certs/Plastic Client

Please remember that only the system user <Your_User> will have the certificate installed. If you need to install certificates for other users then you will need to repeat the process for each of those users. For example, the root user will need to have the certificate installed on Linux because the plastic SCM server is started by root.

Chapter 13: Support alternative connections to the same server

New in 5.4

Plastic SCM allows reaching the same server by different IPs and protocols.

The serveralias.conf file enables this feature on the Plastic SCM client. This file will contain a pair of connections that are aliases of each other:

alias1 alias2

With this file the client will know what connection use at every moment.


Configuring the server aliases file

Suppose you connect to localserver.office-network.com:8084 from the office, but when you go home you connect through the public SSL-protected IP: ssl://plastic.external-network.com:8090. Somehow the client must know that server:8084 and ssl://externalserver:8085 are aliases of each other.

Using the server aliases the Plastic SCM client will be able to switch from one server URL to the other transparently.


To solve this situation a serveralias.conf file must be created under the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the plastic-global-config repository so that all clients have the same settings by default. Optionally, it can be under the client folder in the Plastic SCM installation directory.

The content of the serveralias.conf file will be:

localserver.office-network.com:8084 ssl://plastic.external-network.com:8090
Please note it can jump not only to a different URL but also a different protocol (in this case from regular TCP to SSL).

Chapter 14: Choose a compression method

New in 5.4

The Plastic SCM user is able to select what type of compression method will be used by Plastic to store a new revision of a file in the database. The new revision will be created with one of the following Plastic SCM operations:

A new configuration file called compression.conf on the Plastic SCM client lets the user select the compression type by using patterns. The file supports two types of compression:

  • none
  • zip

If the compression.conf doesn't exist then the compression type of any file is "zip".


Configuring the compression file

Each line of the compression.conf file will define a compression type followed by a whitespace and a rule to match with the file path. For example:

none .jpg
zip .txt

This example means that any .jpg file wont be compressed and all the .txt files will be compressed using the zip compression method.

The compression.conf file can be defined in the following locations:

  • Root of the workspace: the rules included in the file will ve valid only for that workspace
  • User config folder (usually \Users\<username>\AppData\Local\plastic4): the rules in the file will be applied for all workspaces

If both files exist their rules will be combined.

There are 4 types of rules that can be specified, and the order of application is the following:

  1. File path rule
  2. File name rule
  3. File extension rule
  4. Wildcard rule

For instance:

  1. /dir/foo.png
  2. foo.png
  3. .png
  4. /**/foo*.???

If a file path match with a path rule, then that rule will be the chosen compression type. If not it will try to match with a file name rule, and so on.

Having the following compression.conf file under the wkstest workspace...

zip .png
none /test01/main-test.png

...if the user performs a checkin on the main-test.png, user1-test.png and test-result.png files then all the .png files but the /test01/main-test.png file will be checked-in using the zip compression method.


Chapter 15: How to configure the license autorenewal

To configure your server to use the license autorenewal, you must use the Server configuration wizard.

Read how to configure the auto renewal option in your Windows, Linux or Mac OS system.

Windows

If you run the Server configuration wizard...
  • ...from the command line, please read this section.
  • ...from the GUI, please follow the next steps.
  1. The first step is to launch the Server configuration wizard GUI. In this window click the Configure button in the License section:
    Configure the Plastic SCM license
  2. Then, in the License configuration window, click the Configure button to set up the server to autorenew the subscription licenses:
    Configure the server to autorenew the subscription licenses
  3. Once the new view shows, click the URL to go to your Plastic SCM dashboard:
    Configure the server to autorenew the subscription licenses
  4. Sign in into the Plastic SCM dashboard where you can see your licenses. To get the license token available with your license, click the create license token link:
    Create license token
  5. Copy the license token:
    Copy the license token
  6. And paste it into the Server configuration tool. Then click OK to use the autorenewal license feature:
    Enter the license token
  7. The license will be autorenewed and the token will download the new one:
    License token configured

Linux

Because the Server configuration wizard is run from the command line, you must follow the steps in this section.

Mac Os

Because the Server configuration wizard is run from the command line, you must follow the steps in this section.

Command line

The last step when configuring the Plastic SCM server is about configuring the autorenewal for subscription licenses. It's as easier as typing your license token:

To do this follow these steps:

  1. Go to your Plastic SCM dashboard.
  2. Sign in into the Plastic SCM dashboard where you can see your licenses. To get the license token available with your license, click the create license token link:
    Create license token
  3. Copy the license token:
    Copy the license token
  4. And paste it into the Server configuration tool:
    Enter the license token
  5. The license will be autorenewed and the token will download the new one.

Chapter 16: Configuration files

Plastic SCM works with several configuration files. These files allow the user to set up global parameters that will be used for the Plastic server and client. Most of them will be configured through the Plastic GUI. But the user and the administrator will be able to modify them directly.


File Description
branchexplorer.cfg (Windows)
branchexplorer.conf (Linux and Mac OS)

Contains the configuration information related to the Branch Explorer.

This config file is located in:

  • The plastic4 directory containing user settings (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
  • Or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to globally configure the Branch Explorer for all users.

client.conf

Contains important client configuration settings including the default server, user credentials and merge and diff tools.

This config file is located in the plastic4 directory containing user settings (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).

cloaked.conf

Contains the paths of the controlled files to cloak. Cloaked files and directories won't be downloaded during the update (or not updated if they were already on the workspace before being cloaked).

This config file is located in the root directory of the workspace, or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to configure the cloaked list.

compression.conf

Lets the user select the compression type by using patterns.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or at the root directory of the workspace.

Learn about how to configure these patterns.

cryptedservers.conf

Stores the information to set up encryption in Plastic Cloud.

This config file is placed at your Plastic SCM server installation directory.

Learn about how to encrypt all the data going to Plastic Cloud.

customextensions.conf

Stores the Plastic SCM custom extensions (your own issue tracker integration extensions).

This config file is placed at your Plastic SCM client installation directory.

Learn about how to create your custom extension.

db.conf

Stores the database backend settings that Plastic will use.

This config file is placed at your Plastic SCM server installation directory.

Learn about how to work with this file and how to configure it when changing the database backend.

externaldata.conf

Contains the external locations (paths) of the stored revisions when archiving them.

This config file is located in your Plastic SCM server installation directory, or in your Plastic SCM client installation directory, or in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows)

Learn about how to archive revisions and create this file.

filetypes.conf

Allows users to associate the file extensions to file types (binary or text).

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), in the root directory of the workspace, or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how this file is created.

gitserver.conf

It is the file controlling the GitServer configuration.

This config file is placed at your Plastic SCM server installation directory.

Learn about how to create this file to configure GitServer.

gitsync.conf

Lets the user include information that will be automatically used during the GitSync operations.

This config file is located in your Plastic SCM client installation directory, or in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).

Learn about how this file works.

groups.conf

Stores the Plastic groups configured from the User management tool.

This config file is placed at your Plastic SCM server installation directory.

guiclient.conf

Stores the Plastic GUI settings, like the Pending changes, Annotate, "Other options", Merge configurations, Plastic Drive, and more.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).

Learn about how to work with this file or how to mount a changeset in Plastic Drive.

hidden_changes.conf

Contains the paths of the controlled files to hide from the Pending changes view. The hidden changes are controlled items that can be changed but the user doesn't want them to appear by default on the Pending changes view.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), in the root directory of the workspace, or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to configure the hidden changes list.

ignore.conf

Contains the paths of the private files to be ignored in the Pending changes view. The ignored files are files that you have no intention of placing under source control.

This config file is placed at the root directory of the workspace, or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to configure the ignored list.

languages.conf

Lets the user customize the language extensions to syntax highlight the code when the files/revisions are compared in the Side-by-side Diff tool.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).

Learn about how to configure this file.

lock.conf

Stores the rules to configure exclusive lockouts.

This config file is placed at your Plastic SCM server installation directory.

Learn about how to create these rules.

openwith.conf

Stores the Open With context menu applications and shortcuts.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).

Learn about how to customize the tools that will be displayed in the "Open with..." menu.

readonly.conf

Contains the paths of the controlled items to keep as "readonly" after an update.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to configure this attribute.

remoting.conf

Stores the listening ports configuration values.

This config file is placed at your Plastic SCM server installation directory.

Learn about how this file works and how to edit it when using your own self-signed certificate.

server.conf

Stores the authentication mode, the audit log level, and more server settings.

This config file is placed at your Plastic SCM server installation directory.

The server settings can be configured from the webadmin.

serveralias.conf

Contains a pair of connections that are aliases of each other. This way you can reach the same server by different IPs and protocols.

This config file is placed at your Plastic SCM client installation directory, or in the plastic-global-config repository so that all clients have the same settings by default..

Learn about how to support alternative connections to the same server.

upgradefiles.conf

It's one of the files needed to auto upgrade all the Plastic SCM clients.

This config file is placed in the upgrade folder at your Plastic SCM server installation directory.

Learn about how to upgrade the system.

users.conf

Stores the Plastic users configured from the User management tool.

This config file is placed at your Plastic SCM server installation directory.

writable.conf

Contains the paths of the controlled items to keep "writable" after an update.

This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the plastic-global-config repository so that all clients have the same settings by default.

Learn about how to configure this attribute.


Global file configuration

It's possible to set a global file configuration in the server. This way, all the Plastic clients have the same settings by default. This means that the configuration files will consult the global configuration as well as the local (workspace relative) and main (client relative) files.

Once the global configuration is created at the server side, the server configuration will be downloaded at the client side when the Plastic GUI starts.

This is the same behaviour as if you're configuring the Global extension configuration when using task and issue tracking systems.

To set up the global configuration in the server, create a repository named plastic-global-config (or update it if you just created it when setting the global extension configuration).

The plastic-global-config repository will have the following structure:

  • Global configuration for a specific repository: /repname/configuration_file.conf.
    For example, /doomsrc/ignore.conf.
  • Global configuration for all the repositories: /allrepos/configuration_file.conf.
    For example, /allrepos/filetypes.conf.
Note: For submodules, you should use the '-' char instead of '/': /myrepo-mysubrepo/configuration_file.conf.
For example, /plugins-3dplugin/cloaked.conf, where plugins is the main repo and 3dplugin is the submodule.
Important: These are the files that can be globally configured:

It is necessary to restart the GUI for the changes to take effect.

How the global configuration is loaded

The plastic-global-config repository can be configured with more than one configuration file. The Plastic client will load first the specific configuration for the repository the user is working on. If the specific configuration doesn't exist, then the allrepos configuration will be loaded.

How to set up the global configuration

To set up the global file configuration, the first step is to create the plastic-global-config repository in the server (if it doesn't exist yet because it was previously created to set up the global extension configuration):

Create the plastic-global-config repository

Then, the repository must have the needed structure as you've seen previously. In the following example, the repository corefx will have a cloaked.conf configuration file and the rest of the repositories will be have a hidden_changes.conf:

Example plastic-global-config

When the client GUI starts, each server configuration is downloaded in a hidden workspace which will be created automatically in the user local directory (in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows)). For example: C:\Users\user\AppData\Local\plastic4\globalconfig\server_port.

In the picture below you can see how this global file configuration and the global extension configuration coexist:

plastic-global-config - Extensions and Configuration files

How the set up the Branch Explorer global configuration

How to create a branchexplorer.conf global configuration file
  1. Go to your Plastic SCM GUI and set your Branch Explorer configuration preferences.
  2. Then, find the generated configuration file at:
    • Windows: C:\Users\user\AppData\Local\plastic4\branchexplorer.cfg
    • Linux and Mac OS: $HOME/.plastic4/branchexplorer.conf
  3. Copy the resulting file to the global configuration repository under the allrepos folder.
What can be globally configured?
  • Only the filters and conditional format rules can be globally configured.
  • The user-specific configuration, such as displaying full branch names, merge links, the start and end date, and so on, will always prevail from the local configuration file. If these settings are set globally, they will be ignored during the "merge" of global and local rules.
How it works?

A global branchexplorer.conf file looks as follows:

[Default]
filters.conditional.numrules=1
filters.conditional.rule0.branches_query=attribute = 'status' and attrvalue = 'RESOLVED'
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=exclusion_rule
Remark: use rule0 if you only have one rule. Start on 0 and continue, or it won't work.

While a local branchexplorer.conf contains user-specific information too:

[Default]
display.attributes.visible=true
display.changestats.visible=true
display.extension.visible=true
display.navigator.visible=false
display.options.branch_level_filter=-1
display.options.changeset_color=1
display.options.dag_mergelinks=false
display.options.draw_branches=true
display.options.draw_crossbranch_changeset_links=true
display.options.draw_labels=true
display.options.draw_merge_links=true
display.options.draw_only_relevant_changesets=false
display.options.draw_taskinfo=true
display.options.end_date=0
display.options.end_date_enablement=false
display.options.full_branch_names=true
display.options.layout_mode=0
display.options.show_parent_to_child_arrows=false
display.options.start_date=636136983268496003
display.options.visible=false
display.properties.legend=false
display.properties.visible=true
display.properties.zoom=0,9999999
filters.conditional.numrules=1
filters.conditional.rule0.branches_query=
filters.conditional.rule0.color=0,128,192
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=non_integrated_branches
filters.conditional.visible=true

The GUIs will combine the global and local filters. The resulting configuration for filters will be as follows:

filters.conditional.numrules=2
filters.conditional.rule0.branches_query=attribute = 'status' and attrvalue = 'RESOLVED'
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=exclusion_rule
filters.conditional.rule1.branches_query=
filters.conditional.rule1.color=0,128,192
filters.conditional.rule1.description=Unresolved branches
filters.conditional.rule1.enabled=true
filters.conditional.rule1.related.branches=None
filters.conditional.rule1.type=non_integrated_branches

As a result of the combined rules in the example above:

  • Users will NOT see branches which the status attribute is set to RESOLVED (because the rule type is exclusion_rule) -> Global config.
  • Users will see the branches that are not merged (type non_integrated_branches) colored blue (RGB 0,128,192) -> Local config.

Chapter 17: Transformable workspaces

The workspace content can be locally transformed based on some rules. It means, workspace items can be moved to different locations or even not loaded.

These are some advantages of the transformable workspaces:

  • You need to configure your workspace by moving some folders to run a correct build.
  • You're working with big repositories that store a great number of files and/or big files, and you don't want to load some of them into your workspaces.

Transformer rules

A transformable workspace is configured through the transformer rules.

These rules are specified in a file named plastic.transformerrules inside the workspace .plastic configuration directory. This file must be created manually first.

Two kind of rules are currently supported:

Move rules

This rule moves a controlled path to a different location. The source path and the parent folder of the destination path must be also controlled.

Parts of one repository can be loaded inside a different repository without any restriction.

Examples:

mv /Game /TnT/Game
mv /src/libs/nh3 /nh3
Remove rules

This rule avoids loading certain parts of the tree. The specified path must be a controlled path.

Examples:

rm /src/bin
rm /textures/hugefile.map

Transformer rules - How to use them

After editing the file to add, remove or change any rule, an update operation must be manually executed to make the workspace changes effective (forgetting the update operation after editing the file can lead to weird issues).

There cannot be pending changes in the workspace when editing the rules file.

Let's see an example:

  1. Imagine the following workspace. We want to transform it by executing the following actions:
    • move the irix folder to the root because it's a requirement for a correct build;
    • remove the armory.afdesign big file.

    Transformable rules - Workspace before transformer rules

  2. We must first create the plastic.transformerrules file inside the workspace directory .plastic with the following rules:
    mv /lcc/mips/irix /irix
    rm /art/armory.afdesign
    

    We verified that there's no pending changes.

  3. It's time now to Update workspace. And we'll see that the transformer rules are applied:

    Transformable rules - Workspace after transformer rules

    The moved directory has now the Directory / Transformed type.

Transformer rules - Current status

This functionality is still under development although a standard working cycle can be normally performed.

The most common operations are supported: add, rm, co, unco, ci, merge, status, ls, etc.


Current limitations

Not supported scenarios with transformer rules

  • Fast-update operation.
  • Update with controlled pending changes.
  • Cloaked functionality.
  • Merge inside rm rules.

Known issues

  • The unco operation of a local delete operation with a move rule inside cannot be completed. This issue can be workarounded by running a standard update once there aren't controlled changes in the workspace.
  • The edited xlinks are automatically checked in when they contain a transfomed item with changes inside it.
  • The Retry update or Update forced buttons from the Update report view can lead to an uncontrolled exception if message says that some rule couldn't be applied. A partial update (unrecommended operation) from the command line could end up with the same error.
  • A directory can be kept as checked out after a merge operation if a replace operation involves a transfomed moved item (the move rule must involve different parents).

Restrictions

  • The xlinks cannot be moved by transformer rules.

    Example:

    mv /src/xlink /xlink
    

  • The tranformer rules cannot modify an already applied rule.

    Example:

    mv /src/foo.c /src/bar.c
    mv /src /source
    

  • The rm rules cannot be applied when they contain the source or destination of a mv rule.

    Example:

    mv /src/foo.c /doc/foo.c
    rm /src or rm /doc
    

  • The rm operation cannot be applied when it contains the source or destination of a mv rule.

    Example:

    mv /src/foo.c /doc/foo.c
    $cm rm src
    

  • The transformed moved nodes cannot be moved again.

    Example:

    mv /src/foo.c /doc/foo.c
    $cm mv doc/foo.c foo.c
    


Chapter 18: Floating license system

We have implemented a new system for companies who require floating licenses.

The traditional licenses so far are based on "named users". If you have 3 licenses, then John, Mike and Sara can access Plastic and consume the 3 licenses. If Sara leaves the company, then the admin will need to deactivate Sara to allow Paul to use the server.

With floating it is different. The server handles a number of free spots. On startup, all spots are free. And as soon as users access the server, spots are reserved. Spots stay reserved for a given time (typically 30-60 minutes) then can be renewed or taken by a different user.

Consider the same scenario described above but this time with floating licenses. We have 3 spots. Then Sara accesses the server and one license spot is reserved and kept for a period of time. Later John does the same and then Mike. Suppose Paul wants to access immediately after: since you only have 3 licenses, his connection will be rejected. But as soon as Sara, Mike or John reserved spots expire, Paul will gain access, without administration intervention.

Floating licenses are great for teams with a central server and offices around the globe: if you have 20 users in Madrid and 20 in Seattle, you won't need 40 licenses but only 20 floating ones.


Chapter 19: The Plastic SCM server read-only mode

It is possible to switch the Plastic SCM server between normal mode and read-only mode. You can do that executing the following command:

cm admin readonly action
This command can only be executed by the Plastic SCM server administrator.

When the server is in read-only mode, only read operations are allowed, so no data will be changed. This is useful using Jet backend because it allows backup operations to be performed without stopping the server.

The cm admin readonly command allows to:

  • Enter in read-only mode using cm admin readonly enter
    Once it's executed no more write operation will be allowed. The command will wait for all currently running write operations to end before it finishes.
  • Leave read-only mode using cm admin readonly leave
    This action brings the server back to normal mode; for example, write operations are allowed again.
  • Retrieve the read-only mode status using cm admin readonly status

Last updated


October 24, 2017
  • Now, you can configure the Plastic SCM server from the webadmin - the new web based server administration console.
    • The new web user interface will replace the old Windows-only admintool and configureserver and it is available on Linux and OS X. This way we close one long term request: cross-platform admin tool.
    • webadmin also implements an interface to configure users and groups (users.conf and groups.conf) replacing the previous Windows-only umtoolgui.exe.
    • webadmin provides not only a way to finely tune the server but also comprehensive documentation about what each parameter means and how to use it, and links to more information when needed.
  • September 26, 2017
  • The link required to download the Windows tools to create the Plastic SCM SSL Certificates is now updated.
  • September 13, 2017
  • We included the instructions to backup and restore the Jet backend.
  • Learn how to switch the Plastic SCM server between normal and read-only modes.
  • July 4, 2017
  • Learn how to configure Jet as your default storage backend.
  • June 09, 2017
  • Now, you can configure a timeout for LDAP requests.
  • June 02, 2017
  • Learn how the floating license system works.
  • June 01, 2017
  • Now, the Branch Explorer can be globally configured for all users.
  • May 19, 2017
  • Learn how to force clients to upgrade to a given version.
  • May 12, 2017
  • We updated some screenshots because we changed the repository-related dialogs replacing their server text boxes with a combo box containing a list of recently used servers.
  • February 24, 2017
  • Transformable workspaces, an advanced management feature for your workspaces.
  • February 21, 2017
  • Some commands related to the Plastic SCM server and client configuration are now updated.
  • Jan 24, 2017
  • The Server and Client installation, and Server and Client configuration processes have been improved. Some screenshots are updated.
  • Follow these steps to start working with Plastic SCM if it's the first time you install Plastic SCM in your machine.
  • December 17, 2016
  • The server aliases configuration file location has been fixed.
  • July 4, 2016
  • Find a list of the configuration files used by Plastic.
  • Read how to set up a global file configuration in the server so that all clients have the same settings by default.
  • June 27, 2016
  • The umtool commands have been updated.
  • May 10, 2016
  • The Plastic SCM installation chapter has been updated. Now includes the Plastic SCM installation and configuration in Linux and Mac OS systems.
  • The license autorenewal configuration chapter now includes the steps to follow when working in Linux or Mac OS systems.
  • November 5, 2015
  • The Plastic SCM Server and Client installation and configuration chapter has been updated.
  • September 7, 2015
  • Review the new minimum requirements in order to install and use Plastic SCM.
  • August 7, 2015
  • The auditing log documentation has been updated.
  • July 22, 2015
  • Updated documentation about the following commands to work with the Plastic SCM Server on Windows, Linux and Mac systems:
  • May 27, 2015
  • Follow the steps to configure your server to use the license autorenewal
  • March 27, 2015
  • New in 5.4 Learn how to create a SQL Server database using the db.conf file
  • March 20, 2015
  • New in 5.4 Included compression.conf file to choose a storage compression type
  • March 18, 2015
  • Updated lock.conf documentation. Added sample patterns
  • March 18, 2015
  • New in 5.4 Learn how Plastic SCM supports alternative connections to the same server
  • February 25, 2015
  • How to create and use SSL certificates to be used with Plastic SCM