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 all sizes.

Plastic SCM provides high-end SCM capabilities without imposing restrictions associated with 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, create repositories, workspaces and make backups.


Components

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

  • The Server: responsible for storing project information and managing client access.
  • 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 graphics-oriented interface. It gives visual 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 inside Visual Studio, and full access to GUI views like Branch Explorer, labels and checkouts.
      • Eclipse integration: provides access to commonly 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 (formerly OnTime)
      • Version One
      • Fog Creek's FogBugz
      • Trac
      • Bugzilla
      • Mantis

Chapter 2: Minimum requirements

  • Windows - The .NET Framework 4.6 is required.
  • Windows:
    • All Windows
    • Windows XP, Windows 2000, and Window Vista no supported due to .NET restrictions
  • Linux: The following distros are supported (more info here)
    • Debian
    • Ubuntu
    • Fedora
    • Red Hat Enterprise
    • CentOS
    • OpenSUSE
  • 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 the installation of the server component.


Server and Client installation

Install Plastic SCM on your Windows, Linux or Mac OS system.

Windows

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 Explorer. The integration lets the user do most of the operations available on the Plastic SCM GUI client directly from the 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 option 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 different releases of the IntelliJ IDEA platform.
    • SCC plugin - This is a Plastic SCM implementation of the 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, 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 has 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 which 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, launch the webadmin.

Linux

To install Plastic SCM on Linux, complete 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, launch the webadmin.
If you're installing Plastic for the first time, you must complete the client configuration before using Plastic.

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 in the More installers section.

Mac OS - 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. 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, complete the 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. 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, launch the webadmin.
If you're installing Plastic for the first time, you must complete the client configuration before using Plastic.

Server configuration

After installing the Plastic SCM server for the first time, the server is configured with the default values.

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

Complete one of these steps to configure the Plastic SCM server.

  • Launch the webadmin - Plastic SCM Server Administration Console - the cross-platform admin tool.
  • or
  • Open a command line:
    1. Run the command line admin tool as an administrator:
      • On Windows: plasticd configure
      • On Linux: /opt/plasticscm5/server/plasticd configure
      • On Mac OS: /Applications/PlasticSCMServer.app/Contents/MacOS/plasticd configure
    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: 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 set up to this new port.
        • SSL port - By default, the SSL secured port is 8088.
      • Users authentication mode - Choose between the different authentication mechanisms available:
        • If the LDAP option is selected, 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;
          • Choose whether the LDAP server is an Active Directory or a conventional LDAP server.

          LDAP Authentication configuration

          Note: The LDAP and Active Directory authentication modes are only included with the Enterprise Edition.
        • If you select the User and password option, 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 - You can configure the auto-renewal option for subscription licenses. You only need your license token. To get it, complete these steps:
        1. Navigate 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. 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.

Client configuration

Each time a new client is installed on a developer's machine, it must be configured to connect to a Plastic SCM server. This can be quickly 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:
  • cm configure - Configure the Plastic SCM client through the command line. Read the command line section to learn how this configuration works.
  • plastic --configure - Open the Plastic SCM client configuration GUI.
The Client configuration wizard GUI can also be run from the Plastic SCM startup menu entry.

Using the Client configuration wizard you can configure:

Windows - Client configuration wizard

  • Plastic SCM server:
    • You must fill in the hostname 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 the new port number. Once that information is entered, check if the Plastic SCM client can connect to the Plastic SCM server by clicking on the Connect button.

      You can find servers in your network if you don't know the server hostname by launching the discovery service and 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; You 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: Choose whether or not to use SSL when connecting to the server.
  • User credentials: The Plastic SCM client automatically detects the authentication mode configured on the connected server. Enter the data required (as needed) and, optionally, click on the Check button 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.
If you're installing Plastic SCM for the first time, 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:
  • cm configure - Configure the Plastic SCM client. Read the command line section to learn how this configuration works.
  • plasticgui --configure - Open the Plastic SCM client configuration GUI.
The Client configuration wizard GUI can also be run by right-clicking the Plastic SCM application and selecting Configure Plastic SCM.

Using the Client configuration wizard the user can configure:

Linux - Client configuration wizard

  • Plastic SCM server:
    • You must fill in the hostname 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 the new port number. Once that information is entered, check if the Plastic SCM client can connect to the Plastic SCM server 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.
If you're installing Plastic SCM for the first time, 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:
  • cm configure - Configure the Plastic SCM client through the command line. Read the command line section to learn how this configuration works.
  • plasticgui --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:
    • You must fill in the hostname 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 the new port number. Once that information is entered, check if the Plastic SCM client can connect to the Plastic SCM server 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.
If you're installing Plastic SCM for the first time, you must configure your working project before Plastic SCM can be used.

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 - Type the Plastic SCM server address (name or IP) and 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: 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 about the type of file (binary or text) or the file extension to which this rule applies.

The default rules for the merge tool are:

FileType:
Indicates the types of files the rule will apply to. For example, 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 there is 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 differences. These tools must have every mandatory parameter using the variables given, replaced by the system value during execution. For the system to use a specific value for a rule instead of a variable, that value would need to be set. The given variables are the following:
@basefile
path containing the merge common ancestor.
@basesymbolic
name shown on the tool to refer to the base file. 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. 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 binary (.scs). For the file to be considered as text and given fixed parameters, the type of merge should be automatic (if one of the contributors has submitted changes and the file codification is 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 different tools, rules are built similarly, but there are fewer variables. For example, to add a rule to calculate differences on a binary file (.scs) as a text file with the Unicode format, you'd 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

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

Windows

After configuring the Plastic SCM server and client, you must set up the project that you'll work with.

Choose one of the two following options:

  • Start a new project - This means creating a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name.
    • 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 - Select the path where your workspace files will be stored on your disk.
  • Join an existing project - 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 - Select the path where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will launch, showing you the new workspace.

Linux

After configuring the Plastic SCM server and client, you must set up the project that you'll work with.

Choose one of the two following options:

  • Start a new project - This means creating a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name.
    • 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 - Select the path where your workspace files will be stored on your disk.
  • Join an existing project - 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 - Select the path where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will launch, showing you the new workspace.

Mac OS

After configuring the Plastic SCM server and client, you must set up the project that you'll work with.

Choose one of the two following options:

  • Start a new project - This means creating a new repository:
    Start working with Plastic - Start a new project
    • New repository name - Enter the repository name.
    • 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 - Select the path where your workspace files will be stored on your disk.
  • Join an existing project - 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 - Select the path where your workspace files will be stored on your disk.

Once the repository and/or workspace is created, the Plastic SCM GUI will launch, showing you the new 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

Use one of the following methods:

  1. To open the Windows Service Manager, navigate to Control Panel > Administrative Tools > Services or or run the services.msc command. Once the Services window is opened, you'll find the Plastic SCM service in the list. 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 following: 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 has started, a default repository is created to ease the initial system usage.

Check whether the server is up and running by running one of the previous commands 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: 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
  • Use this command to stop the Plastic server: sudo launchctl unload /Library/LaunchDaemons/com.codicesoftware.plasticscm.server.plist

Run Plastic SCM

Select one of the following methods to run the Plastic SCM client in Windows, Linux or Mac OS.

Windows

  • Open the Plastic SCM application from the startup menu:

    Windows - Run Plastic SCM

    Or:

  • Type plastic in a command line interface window.

Linux

  • Open the Plastic SCM application from the Applications window:

    Linux - Run Plastic SCM

    Or:

  • Type plasticgui in a command line interface window.

Mac OS

  • Open the Plastic SCM application from the Applications window:

    Mac OS - Run Plastic SCM

    Or:

  • 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: For example, a remote server and the 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 keep the most used revisions in memory for improved performance. The administrator can configure the maximum amount of memory to be used.

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 in the following set of figures. The typical scenario for a 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 simple proxy server, which will increase the overall system performance by reducing network traffic over distant networks.

Same network, improved by using two proxies


Starting the Plastic Proxy

The Plastic Proxy is bundled as a subcommand of Plastic SCM Server executable file.

You can start the Plastic Proxy by running plasticd proxy. (No arguments required.)


Managing the Plastic Proxy service on Windows

These operations are available for Windows systems only.

These are the operations available with the plasticd proxy subcommand:

  • Install the Plastic Proxy service:

    plasticd proxy --installservice

    This command install the service but it doesn't start it up.

  • Start the Plastic Proxy service:

    plasticd proxy --start

  • Stop the Plastic Proxy service:

    plasticd proxy --stop

  • Restart the Plastic Proxy service:

    plasticd proxy --restart

  • Print the status of the Plastic Proxy service:

    plasticd proxy --status

  • Stop and uninstall the Plastic Proxy service:

    plasticd proxy --uninstallservice


Configuring the Proxy server

For the proper way of working of the proxy server, remember creating a plasticcached.network.conf configuration file in the Plastic SCM Server installation directory.

This is an example of a plasticcached.network.conf file:

[
  {
    "port": 8085,
    "type": "tcp",
    "security": "none"
  }
]

You can find a copy of this example configuration file in the config_samples folder in the Plastic SCM Server installation directory.


Configuring the clients

The Plastic SCM clients now need to configure a proxy server. To do this, open the Preferences dialog.

Check the Use a Proxy server box and enter the proxy server name in server:port format. By default, the port is 8085.

You can click Connect to verify the connection is ready.

Configuring a proxy server in the Plastic SCM client

That's it! When revisions are downloaded from the server, the client will ask the proxy and download them from there instead of the server (if the data is cached).


Support to cache data from Plastic Cloud

To cache data from the cloud, install a Proxy (and your client too if you use encrypted data in the Cloud) and start caching data.


Disk cache limit

The proxy can limit the size of its on-disk cache.

How to configure

Use the MaxCacheSizeInGb in the plasticcached.conf file.

For example:

<PlasticCacheConf>
  <MaxCacheSizeInGb>20.5</MaxCacheSizeInGb>
</PlasticCacheConf>

The Proxy will make sure that its cache size doesn't exceed 20.5 Gb.

A value of 0 means that the clean is disabled.

How it works

  • The Proxy maintains an LRU (Least Recently Used list) and updates it on every data access.
  • Every 10 minutes, it checks if the total cache size is bigger than the value configured. If the maximum size is exceeded, the Proxy retrieves the least recently used entries and removes them from the disk.
  • Every 3 minutes, the Proxy saves the LRU info to the disk, to proxy-data-path/proxy-lru.dat. The Proxy also writes data on shutdown.
  • On startup and every 8 hours, the Proxy checks if it needs to walk the entire cache directory to rebuild the LRU and recover from possible inconsistencies. While the check runs every 8 hours, a rebuild only happens once every 3 days. The Proxy stores the date of the last rebuild under proxy-data-path/proxy-last-cache-walk.dat.
proxy-data-path is the directory where the proxy is configured to store the cache. For existing Proxy installations, the new version will rebuild the cache on the fly.

Some logs

During the startup of the Proxy, you'll see:

INFO  LRU - Walking the disk to build the LRU (least recently used). c:\plastic\proxydata
INFO  LRU - Last LRU rebuild from disk happened less than 3 days ago. Skipping. 11/04/2019 16:50:00
INFO  Daemon - Load LRU info from c:\plastic\proxydata\proxy-lru.dat
INFO  Daemon - LRU info loaded in 656 ms. 107299 entries. 5.89 Gb total in cache

You can see how the Proxy skips the rebuild and how it loaded 107k entries to the LRU.

Then, every 3 minutes, and during shutdown:

INFO  Daemon - Save LRU to c:\plastic\proxydata\proxy-lru.dat
INFO  Daemon - LRU info saved in 312 ms. 107299 entries. 5.89 Gb total in cache

And during a clean up:

INFO  Daemon - Cleaning up 0.69 Gb (17564 entries) of cached data to enforce the 5.20 Gb limit
INFO  Daemon - Cleaned up 0.69 (17564 entries) Gb in 5110 ms
INFO  Daemon - Save LRU to c:\plastic\proxydata\proxy-lru.dat
INFO  Daemon - LRU info saved in 265 ms. 89735 entries. 5.20 Gb total in cache

Monitor free space

The Plastic Proxy can monitor free space on the disk and clean up the cache to avoid running out of space.

You'll see something as follows in the log when it runs out of space:

INFO  Daemon - Disk is running out of space. 5.78 Gb available. Will delete 1.15 Gb from cache
INFO  Daemon - Cleaning up 1.15 Gb (9576 entries)
INFO  Daemon - Cleaned up 1.15 Gb (9576 entries) in 2578 ms

And, if there is enough room (twice the size of the cache) then something as follows:

INFO  Daemon - Disk still has enough space: 19.53 Gb available.

More info in the log file

The log shows the caller's IP and the user name. This information appears in the log line after the GetObjectsData call.

The log is as follows:

Proxy - Request:     39. Type: downl. Files requested:   10. Cache misses:    10. Total time:    16 ms. Downloaded: 3.78 Mb from default@localhost:8084. Total returned: 3.78 Mb. IP: 127.0.0.1. User: 'pablo'.

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 startup if no other repository exists yet. You're all set!

From the administrator's point of view, it can be fun to create repositories using the command line interface. This is achieved in with the cm repository create or cm repo mk commands:

cm repo mk 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

In the new repository dialog, you can enter the repository name and the Plastic SCM server where it will be created.

New repository dialog

Listing available repositories

To view available repositories, open the command line or GUI client. Use cm listrepositories or cm lrep:

cm lrep backyard:8087

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.

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 example above, archive repository 3 will be removed (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 the 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 the 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

Several repositories have appeared/created in the example above since myproject was archived, which was previously 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

To reconnect, 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 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. The server is ready, and the Plastic clients can 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 the organization's needs.

To launch the server administration console, follow one of these methods:

    • Open your favorite web browser and connect to your server address like this:
      • Use http://ipserver:7178 if you don't have any SSL ports defined in your server network configuration. The webadmin HTTP endpoint listens on port 7178 by default and it's bound to localhost only.
      • Use https://ipserver:7179 if you do have any SSL ports defined in your server network configuration. You can configure that port using the WebAdminToolSslPort setting in server.conf file. This endpoint will listen on any network interface.
      The web server automatically uses the first certificate you configured in your network settings. This means that the web interface will automatically use the same certificate for your Plastic SCM SSL connections without any further configuration. If you don't have any SSL ports defined in your server network configuration, only the HTTP endpoint will start.
      If you change the certificate you use for the SSL port at any point, make sure you restart the server to refresh the certificate information in the webadmin.
    • Or, directly run the webadmin tool:
      • From Windows: Launch the Server Admin Console tool from the Windows start menu.
      • From Mac OS and Linux: Run the Plastic SCM Server application.
  1. Enter the required credentials.
    • If the server is just installed (no repositories created yet, except the default repository), you must set a password to access 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 by using the plasticd adminpwd utility:
      Plastic SCM Server administration console - Configure a password

      Complete these steps:
      1. Open the command line as an administrator.
      2. Run the following command:
        • Windows: Plastic SCM installation directory\server\plasticd adminpwd --pwd=yourpassword
        • Linux: /opt/plasticscm5/server/plasticd adminpwd --pwd=yourpassword
        • Mac OS: /Applications/PlasticSCMServer.app/Contents/MacOS/plasticd adminpwd --pwd=yourpassword
      3. Navigate back to the Administration console and Refresh.
      4. Enter the configured password and Log in.
    • If an 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.

You can also access other relevant information:

  • License - Configure everything 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 - Monitor the Plastic Server activity live.
The server.conf, network.conf, db.conf, and lock.conf files are now reloaded.
This means that you can edit any of those files, 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.

Note: Don't forget to click 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 set up 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

    To use your own certificate, 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 security information to the server to be validated. The basic token sent from client to server is called SEID, short for SEcurity IDentifier. The mechanisms to be described are 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.

This system relies on the correct network configuration. It can be used on secured networks to easily configure a mixed Unix / Windows environment, depending, 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). It will take the current user for Windows machines inside a domain if it's not a local user.


How is the SEID built?

With the user name.

Name + ID

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

It is a straightforward way to prevent or complicate 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, will 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). It will take the current user for Windows machines inside a domain 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 great method for Windows / Unix mixed environments. 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.

You can configure the following settings in the server.conf file:

  • Timeout for the LDAP requests
    The Plastic server can set a timeout for the LDAP requests (time in seconds). Use the LdapTimeoutSeconds setting. For example:
    <LdapTimeoutSeconds>10</LdapTimeoutSeconds>
  • LDAP token expiration time
    You can also configure the LDAP token expiration time. Use the LdapTokenExpirationTimeSpan setting. You can set any expiration time using the format [d.]hh:mm:ss:
    <LdapTokenExpirationTimeSpan>05:00:00</LdapTokenExpirationTimeSpan>
    By default, the expiration time is 1 hour.
  • Override for LDAP user filter
    Warning!
    This is considered an advanced-level feature to be used ideally after consultation with our Support team.
    To support LDAP setups that are not compatible with our default LDAP user search filters, you can use the limited ability to override the filter with a user-specified filter. Use the MemberNameFilterOverride setting.

    Enter the following to specify the filter override:

    <LdapSettings>
      <MemberNameFilterOverride>_user_filter_</MemberNameFilterOverride>
    </LdapSettings>
    

    For example, LDAP setups without the uid attribute can use the following filter: (|(sAMAccountName={user})(cn={user})).



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 Windows-based operating systems.

Active Directory authentication can be used in single- or multi-domain environments. 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

LONDON\jsmith 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, they'll receive an access denied error.


You can configure the following setting in the server.conf file:

  • Time to reload users and groups
    By default, the Plastic server reloads every 5 minutes the users and groups information from the authentication provider. Use the ReloadUsersRefreshTimeSpan setting. You can configure this time using this format [d.]hh:mm:ss.

    In the following example, the refresh will occur every hour:

    <ReloadUsersRefreshTimeSpan>01:00:00</ReloadUsersRefreshTimeSpan>

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 with 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 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, 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 here:

    users.conf file format

  • groups.conf - Stores all the available groups and the users they contain. The groups.conf file has 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 preceded by a "@" symbol (in the example below, 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 sole 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, use the Plastic SCM client configuration wizard as shown here:

    User and password configuration screen

    If the credentials don't match, a login screen will pop up once the GUI client starts:

    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.

    Replace %serverinstalldir% with your directory path.

    Learn how to use each command, by typing:

    %serverinstalldir%/plasticd umtool help <command_name>

    The umtool implements several commands:

    Command name Abbreviation Description
    addgrouptogroup agtg Add a new group into a group
    addusertogroup autg Add 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 are some examples:

    Create a new user: %serverinstalldir%/plasticd umtool cu maria
    Create a new group: %serverinstalldir%/plasticd umtool cg developers
    Add a user to a group: %serverinstalldir%/plasticd 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:
    • 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. 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 click 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 backend technologies that Plastic supports: Jet, SQL Server, Firebird and others.

The Repository storage section lets the administrator:

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

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 administrator customize other server features.

Request processing
  • Force client build number - Related to the ForceBuildNumberMatch parameter in the server.conf file.
    Use this parameter to mandate all clients upgrading to the same build number of the server. Optionally, you can set a minimum build number instead of mandating 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 requests and closes the connection before the server finishes processing, the server will kill the request thread. This avoids long-running canceled 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 mandate the use of 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.
    Suitable 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 advanced users 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 increases 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.

Note: Don't forget to click 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>
  • HASH - Unique identifier of the logged operation.
  • user - The user/developer who performed the operation.
  • machine - The machine from 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 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

In the License section, you can find all the information about your Plastic SCM license information such as type, licensed users, and license file. you can also configure the license auto-renewal option or change your license.

License

License autorenewal configuration

In this section, you can configure the auto-renewal option for subscription licenses. You only need your license token. To get it, complete these steps:

  1. Navigate to your Plastic SCM dashboard by clicking the related link in your webadmin:
    License autorenewal configuration
  2. Sign in into the Plastic SCM dashboard where you can see your licenses. Click the create license token link to get the license token available with your license:
    Create license token
  3. Copy the license token:
    Copy the license token
  4. Paste it into the License token autorenew box and click Change:
    Enter the license token
  5. Your license is now Configured to be auto-renewed and the token will download the new one:
    License autorenewal configured

Change license

If you need to change your license, you can upload the license file. Select your plasticd.lic file and click Upload:

Change license

Support

If you have any issues, want to request a new Plastic SCM feature, or need some help from the Plastic SCM support team:

  • Navigate to to the Plastic SCM forum or to our Stack Overflow site if you need help solving any issues.
  • Or Create a ticket to contact the support team.
    Support - Issues
  • Contact the support team for suggestions about a new Plastic feature or improvements. Join UserVoice space where you can leave your suggestions and rank ideas.
    Support - Suggestions
  • Occasionally, you may need to send the support team Plastic information like configurations and log files. Click Create a bundle. This creates a zip with the required files. Send it to the support team member you are in contact with.
    Support - Info bundle

Monitor

The Plastic SCM Server Administration console includes several pages and panels that allows you to 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 check-out (Lock)

There are many kinds of files that present a challenge for merging content changes:

  • Unity scenes.
  • 3D models.
  • Images and texture maps.
  • Sound files.
  • Excel spreadsheets.
  • Etc…

The main goal of exclusive check-outs is to avoid the need of merging different revisions of those files. It achieves it by:

  • Preventing multiple developers from making changes to the same file in parallel.
  • Enforcing that developers always build from the last revision of the file.

Whenever an item is checked out, the current lock rules are checked to see if it is subject to them. If so, the item is locked and is now regarded as "exclusively checked out".

Users and tools can check out files they intend to edit for guaranteeing exclusive access to them while they are making changes. As soon as they are done with changes and they are checked in — or instead, unchecked out —, the item gets unlocked again.

To start working on an file (checking it out and creating a new lock), the lock must be created from the "last" revision of the file. This revision is the one loaded in the "destination branch", our source of truth. Once the check-out is completed, the item is locked. However, the operation will fail if the check-out is not done from the revision loaded in the destination branch. Checking the file directly in the destination branch will always remove the lock.

However, if the item were exclusively checked out in a different branch, checking the file in won't make the lock disappear. Instead, the lock will transtion from "locked" to "retained" status as the changes must still get integrated back into the destination branch, and only then the lock will be removed. While in this status, the system tracks which is the last revision in the "holder branch" and allows to keep checking out the file and iterating on it to either the original developer or any other one. This way, developers can work in turns as if they where "passing the torch" among themselves to know who is holding an asset and enforcing the single line of development. In other words: the lock will be retained by the task branch all the way through, protecting the item from parallel changes, but allowing multiple users to collaborate.

Exclusive check-out is also referred as "locking", and it is controlled by the lock rules, set up either globaly or by repository.


How does the exclusive check-out work?

Each time Plastic SCM performs 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

Checking the files for a lock is performed at the client-side. This is so that files that are not potentially lockable are never checked, and overall performance is not affected.

Locks can be found in two different states:

  • Locked – when a workspace has an item exclusively checked out while making changes.
  • Retained – where an item is modified in a branch pending to be integrated. Developers can lock it and keep adding changes.

Configuring the exclusive check-out: creating the lock rules

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

Using the Plastic SCM Server Administration Console

  1. Launch the webadmin - Plastic SCM Server Administration console.
  2. Navigate to Configuration > Lock rules.
    Lock rules configuration
  3. You can specify lock rules for all your repositories (global rules) and for specific repositories (repository-specific rules).
  4. The global rules apply to all repositories and they will be used for all repositories unless there are repository-specific rules that apply to them. To override the global lock rules for one of your repositories, create lock rules for it.
    1. Click Generate common rules (you can edit these rules) to specify your own global rules or load the suggested common lock rules.
    2. If you leave the global rules empty, no rules will apply.
  5. The repository-specific rules apply to a single repository. These rules overwrite the global lock rules.
    1. Click Add to specify the rules related to a particular repository.
    2. Enter the name of the repository (the auto-complete feature will help you here) where the rules will apply.
    3. Click Generate common rules (you can edit these rules) to specify your own global rules or load the suggested common lock rules.
    4. Repeat the steps above as many repositories need lock rules.
    5. Delete the rules for a repository if they aren't needed.
  6. 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> [br:[<destination_branch>]] [excluded_branches:<exclusion_pattern>…]

    Where:

    • repname is one of the following:
      • The name of the repository where you want to perform exclusive checkouts by applying repository-specific rules.
      • The character * meaning "all repositories" to apply global rules to all the repositories.
    • destination_branch is the source of truth when creating a new lock: the revision loaded here is considered the last revision. Locks created in other branches are not released until they get integrated back to the destination branch. It is /main by default.
    • excluded_branches are branches where lock rules are ignored. Branches are matched by name, and therefore, renames are not taken into account.
    • exclusion_pattern might be a full branch name (e.g.: /main/experiment), start or end by a wildcard (e.g: /main/experiments/* /main/experiment-* */art-concepts/*).
  2. 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 br:/main
    *.doc
    *.xls
    *.jpg
    document.vcs
    

    This means that the *.doc, *.xls, *.jpg and document.vcs files are going to be locked on checkout on the default repository in the repository server mainsvr:8084.

    Or, for example:

    rep:battlegame br:/main
    *.png
    /assets/textures/model*.*
    

    Where the *.png pictures and all files under the /assets/textures folder that begin with model will be locked on checkout on the battlegame repository.

    See more examples about paths and patterns in the next section.

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

This is an example of a valid lock.conf file with global rules and repository-specific rules:

rep: * br:/main
# Audio and video formats
*.mkv
*.mp3
*.mp4
*.ogg
*.wav
*.wave

# Image formats
*.bmp
*.jpg
*.jpeg
*.png
*.gif
*.eps
*.exif
*.icns
*.ico
*.psd
*.ai
*.svg
*.pcx

rep: doom3src br:/main excluded_branches: /main/experiment /main/experiments/* */art-concept */art-concepts/*
**/sys/*.xlib
*.def

Locks and paths

Occasionally, you'll need to lock a directory or files under a specific folder.

Look at the below exzamples to see how to use these locks:

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 backend languages and technologies to store the repository data:

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

In this chapter, you'll be able to configure Plastic SCM to work with certain backends assuming you're starting from a clean state. You can also migrate your current repositories into another backend.

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

  • 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, read this chapter to learn how to migrate your data using the Plastic SCM Server Administration console.

Configure Plastic SCM with Jet

Plastic has a new storage for 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.

There is 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.

Plastic still supports 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 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.

Complete 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. Navigate to Configuration > Repository storage
  3. If the server is configured to work with another backend different from Jet, you'll 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, 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.
      Note: Migrating your data requires stopping the Plastic SCM server which 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.
  4. Configure the values for the following parameters:
    • Database path - 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 maximum 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 configure the following parameters to work with Jet:

  1. basepath: Specify 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. Optionally, you can also configure the following parameters:
    • blobspath - Specify the path where Jet will store blobs. This way, Jet stores blobs and metadata in different paths. This is useful because it makes it possible to put metadata in faster and more expensive storage and blobs in slightly slower and cheaper ones (blobs will need much more storage than metadata).
    • prefix - Create prefixes for your database name.
    • suffix - 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.
    • 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 maximum number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
    • maxcachessizeingb and maxcachessizefreepercent - Use these parameters to configure the maximum amount of memory used by caches. When the process reaches the memory limit, it starts to clean the caches of the least recently used repositories. The server will clean the configured percentage of the total number of caches.
      By default, there is no memory size limit. You need to configure it to enable this functionality. In that case, the default percentage to free will be 25% (not used unless a size limit is set).
      Bear in mind that the memory will not be released until the garbage collector (GC) runs the next full collection.

These are valid jet.conf files:

  1. basepath=/mnt/metadata
    blobspath=/mnt/blobs
    maxcachedtrees=50
    datafilesize=4
    
  2. basepath=c:\Users\maria\plasticdb
    prefix=zero
    suffix=
    
  3. basepath=/mnt/data
    maxcachessizeingb=2
    maxcachessizefreepercent=30
    

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.

Complete 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. Navvigate 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.
      Note: 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.
  4. Configure the 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: 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 - 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 allows 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: 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>
    
    You can use this db.conf file if you want to work with a Firebird Server installation instead of 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. 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 allows 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! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. It is recommended not to touch this setting on your own. For further info, ask Plastic SCM support at devops-vcs-support@unity3d.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Configure Plastic SCM with PostgreSQL

Complete 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. Navigate 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.
      Note: 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.
  4. To edit settings, configure the 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: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 allows 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. The Port value can be also needed. But, don't change the Database={0}; key.
    Note: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. You can also configure the following parameters:
    • DatabasePrefix - 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! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. It is recommended not to touch this setting on your own. For further info, ask Plastic SCM support at devops-vcs-support@unity3d.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, due to new transaction isolation levels introduced with 2005. It can be configured to work with 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 on your laptop (Plastic supports distributed development and replication) to work with Plastic SCM while you're disconnected.

Complete 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. Navigate 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. To create the databases on an specific path, 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.
      Note: 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.
  4. If you need to edit some settings, configure the 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: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. But, don't change the DATABASE={0}; key.
    Note: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 where the connection string use built-in SQL Server authentication which is telling Plastic to use a given user and password:

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

    To use built-in Windows authentication, 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! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. It is recommended not to touch this setting on your own. For further info, ask Plastic SCM support at devops-vcs-support@unity3d.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 split into 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 if problems show up, 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.

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

Complete 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. Navigate 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.
      Note: 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.
  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: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 allows 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. But, don't change the Database={0}; key.
    Note: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. You can also configure the following parameters:
    • DatabasePrefix - 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! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. It is recommended not to touch this setting on your own. For further info, ask Plastic SCM support at devops-vcs-support@unity3d.com.
      These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

Finally, you 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 remark

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, it is assumed 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.

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 for the embedded and Jet backends only.
If you configured a different database backend, please check with your database administrator to find out 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 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 are usually better handled by the other supported backends such as MySQL, MS SQL Server or PostgreSQL. This is one of the reasons why it is recommended to use 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 complete 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. The following tools are tested on Windows and Linux:

Tool Restore Incremental Comments
Bvckup2 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

This example shows the setup for a weekly and incremental backup using rdiff-backup on a Linux machine:

  1. Install rdiff-backup 1.2.8 in the server.
  2. Configure autofs to auto-mount backup NFS folder in the /cifs/backup folder.
  3. Add 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.

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/"
  • 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

You can execute the same example above, but as it is a hot copy, you'll need to switch the server between normal and read-only modes ( cm admin readonly ) instead of stop/start it.

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 archive revisions?

There are third party compiled tools, programs, binaries, big documents and other kinds of big files that rarely change and/or are rarely accessed in a production environment. This can consume disk space and time when storing and retrieving those revisions from the database.

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

How archive command works


How to archive my revisions

To archive revisions, use the archive command (cm archive):

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

A breakdown of the archive example above:

  1. This command will archive the revision 0 of the main branch of the mybigfile.tar item, creating several chunks of the revision, each one containing a part of the revision content.
  2. The archive's comment (-c parameter) is "big file of libraries", and the archive files will be created in /home/plastic/bigfileTARrev0.
  3. 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 current directory.

You can archive several revisions by 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 a user tries to access that data, Plastic SCM will retrieve it from the external storage area.

Note: The user that executes the archive command must be the repository owner. If not, 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.

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 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, Users in Vista/Seven, or home in UNIX based systems).

If a user tries to access any stored revision from the GUI by, for example, executing an update, 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 the archived revisions from that location. If Plastic SCM cannot access the data at a certain point in time, it will show the same dialog again. 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 always be available. If not, 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 they archives can be safely deleted. From there, the database will be used to get the data.

Example:

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

A break down of the example above:

  • 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 no longer be used.
  • 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 on this command, run cm help archive on a command line.


Chapter 11: Upgrade to a given version

How to force client upgrades

The Plastic SCM server can reject clients that are older than the current 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.

    For example:

    <ForceBuildNumberMatch>800</ForceBuildNumberMatch>
    

    800 means any version bigger or equal than 800 will be accepted.


Chapter 12: Plastic SCM SSL certificates

For internal application development and testing, it is often preferable to use a self-signed SSL certificate to avoid the cost of one signed by an external certificate authority. This lesson explains 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. Use 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.

  1. makecert (Makecert.exe) is a command-line CryptoAPI tool that creates an X.509 certificate signed by a system test root key or 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.
    Read more about MakeCert.
  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.
    Read more about Pvk2Pfx.

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

Use the tools on your Windows, Linux or Mac system.

Windows

  1. To create the self-signed certificate, 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'll be asked for a password. Make a note of the password; 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>

    Note: 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. In the example above, the server is 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, execute the openssl command to create the .pem file as follows: openssl req -x509 -nodes -days 3650 -newkey rsa:4096 -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 4096 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. Like with the self-signed certificate, 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, 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. Like with the self-signed certificate, 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'll need to edit the network.conf file which 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 network.conf file is saved, restart the Plastic SCM server to apply the change.

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

[
    {
        "Port" : 8087,
        "Type" : "Tcp",
        "Security" : "None",
        "ReuseAddress" : true
    },
    {
        "Port" : 8088,
        "Type" : "Tcp",
        "Security" : "Ssl",
        "SslPfxFile" : "Tardis.pfx",
        "SslPfxFilePassword" : "|SoC|2ogBDa8GmifTjC7UKp4KuoF0/jWYlXy2",
        "ReceiveTimeoutMsec" : 5000,
        "SendTimeoutMsec" : 5000,
        "ReceiveBufferSizeBytes" : -1,
        "SendBufferSizeBytes" : -1,
        "ReuseAddress" : true
    }

]

Accepting and installing SSL certificates for Plastic SCM

There are several methods that you can use to install the Plastic SCM certificate:

Plastic SCM GUI

The first time 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

Click Yes to add the key to the Plastic SCM key store.

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

Click Yes to add the key to the Plastic SCM key store.

Manual installation

The certificate will need to be accepted and installed in certain situations without using the Plastic SCM client. For example, 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.

Note: The certificate installed 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 you'll need to run the Plastic SCM server/daemon as "Administrator" or "root" user.

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 Action > All tasks > Import:

    Certificate import wizard

  3. Specify the location of the certificate file by(.cer) clicking Browse:

    Certificate import wizard - specify location

  4. Click Next to place the certificate file (.cer) in the "Plastic Client" store.

    Certificate import wizard - store certificate

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

MacOS

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

  • For MacOS use this directory path:

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

Note: Only the system user <Your_User> will have the certificate installed. If you need to install certificates for other users, repeat the process for each of those users.

Chapter 13: Support alternative connections to the same server

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 any given time.


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 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
Note: The file can jump to a different URL and a different protocol (in this case from regular TCP to SSL).

Chapter 14: Choose a compression method

You can 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 you select the compression type by using patterns.

The compression.conf file is located in the:
  • plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
  • Root directory of the workspace.

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 the file path. For example:

none .jpg
zip .txt

This example means that any .jpg file won't 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 be 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 matches with a path rule, that rule will be the chosen compression type. If not, it will try to match with a file name rule.

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

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

...if you perform a checkin on the main-test.png, user1-test.png and test-result.png files, 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

You can configure your server to use the license auto-renewal option.

Configure it from the License section in the webadmin - Plastic SCM Server Administration console.


Chapter 16: Configuration files

Plastic SCM works with several configuration files. These files allow you 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 in 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 in your Plastic SCM server installation directory.

Learn how the encryption works both in Plastic Cloud extension or in Plastic Cloud Edition.

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. These settings are related to the following backends: Firebird, SQLite, SQL Server CE, PosrgreSQL, SQL Server and MySQL.

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

Learn how to manage the db.conf file to configure Plastic SCM with:

eolconversion.conf

Define the EOL conversion based on the file extension.

This config file must be 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 to configure the EOL conversion.

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.

externaltools.conf

Allows users to define external applications and how they'll receive the selected object properties.

This config file can be included in your Plastic SCM client installation directory, 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 at /externaltools/externaltools.conf so that all clients have the same settings by default.

Learn how to configure the external tools.

filetypes.conf

This file is used to check if a file is binary or text before running diffs or merges.

This is really useful when you are working with Plastic Cloud, since changing revision types is not allowed there.

For example, lets suppose the the scene.config file was wrongly added as binary. You can configure filetypes.conf to consider scene.config as text, so the right text-based diff and merge tool will be selected instead of considering the "bin type" tracked for the file in the repo.

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.

gitserver.conf

This 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

This file allows the user to 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 in 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 don't 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.

jet.conf

Stores the settings when configuring Plastic to work with Jet (Plastic's repository storage).

This config file must be located in your Plastic SCM server installation directory.

Learn how to configure Plastic with Jet.

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.

mergerules.conf

Stores the merge rules used to restrict merges to happen only if certain rules are met.

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

Learn how to configure your Merge Rules system.

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.

network.conf

Stores the listening ports configuration values.

This config file is placed in 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 in 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.

users.conf

Stores the Plastic users configured from the User management tool.

This config file is placed in 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

You can 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 and 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.

Note: This is the same behaviour as when 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 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:

You must 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 first load 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 already (it was previously created to set up the global extension configuration):

Create the plastic-global-config repository

The repository must have the correct structure as seen previouslys. 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 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 to create a branchexplorer.conf global configuration file

  1. Navigate to your Plastic SCM GUI and set your Branch Explorer configuration preferences.
  2. Find the generated configuration file in:
    • 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, 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 does it work?

A global branchexplorer.conf file looks like this:

[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
Note: Rules start from rule0 (first rule).

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. This means workspace items can be moved to different locations or even not loaded.

Reasons for using 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 large 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 also be 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 errors).

Note: There cannot be pending changes in the workspace when editing the rules file.
  1. Imagine the following workspace. It'll be transformed by executing the following actions:
    • Move the irix folder to the root (requirement for a correct build).
    • Remove the armory.afdesign big file.

    Transformable rules - Workspace before transformer rules

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

    Verified that there's no pending changes.

  3. Now to Update workspace, and the transformer rules are applied:

    Transformable rules - Workspace after transformer rules

    The moved directory now has the Directory / Transformed type.

Transformer rules - Current status

Note: 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 avoided 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 (not recommended) 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 transformed 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: The Plastic SCM server read-only mode

You can switch the Plastic SCM server between normal mode and read-only mode by executing:

cm admin readonly action
Note: 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 you 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

Chapter 19: The Merge Rules system

The Merge Rules system allows you to restrict merges to happen only if specific rules are met.

This system is available both for Plastic SCM Enterprise Edition and Plastic SCM Cloud Edition.

It is very easy to set rules like "don't allow to merge branches if they are not reviewed" and "only allow merges from child branches".

Previously, you'd have to write a trigger to enforce this behavior. But now, it is just a matter of setting a few merge rules.


Types of merge rules

With the Merge Rules system, you can restrict merges to certain branches, so that:


How the Merge Rules system works

  1. You must first specify one or more merge rules.

    A merge rule defines:

    • If the merge rule is enabled or not
    • The affected repositories
    • A restriction:
      • The restriction includes the source and destination branches involved in the merge.
      • These branches must match a pattern.
      • The branch matching works by specifying one or more of the following filters:
        • Branch name patterns (with '*' to represent any substring)
        • Branch attribute names and, optionally, attribute values

        You can see in the how filtering workssection.

      A merge rule example to clarify these concepts:

    How the Merge Rules system works
  2. When you're about to merge a branch, the server will check whether there are any rules that apply to the involved source/destination branches pair.

'only_allow_merges_if_reviewed' rule

Definition

Only allows merging branches if they have an approved code review. It is an equivalent to the popular "pull request restrictions" that mandate reviewing branches before a merge.

Example:

[{
   "enabled": true,
   "repositories": "*",
   "rule": "only_allow_merges_if_reviewed",
   "to":
   {
      "branchNames": ["main"]
   },
   "from":
   {
      "branchNames": ["QUAK-*"],
   }
}]

This (enabled) rule applies to all repositories and forces all branches named QUAK-* to be reviewed prior to be merged to main.

In the diagram below, only branch QUAK-001 will merge to the main branch:

Example: 'only_allow_merges_if_reviewed' rule

If a merge can't happen, you'll receive an error like this:

Cannot perform the merge. Review the branch '/main/QUAK-002' to merge it to '/main'.


'restrict_merges_to_branch' rule

Definition

Restricts merges to a given branch. This way, the merges to that branch can only come from a given set of branches.

You can specify rules that apply to groups of branches too.

Example:

[{
   "enabled": true,
   "repositories": "codice",
   "rule": "restrict_merges_to_branch",
   "to":
   {
     "branchNames": ["/fix3.0"],
   },
   "from":
   {
     "branchNames": ["fixes-*"],
   }
}]

In repository codice, merges to branch /fix3.0 are only allowed from branches named fixes-*. (you can use wildcards).

In the diagram below, branches /fix-3.0/fixes-089 and /fix-3.0/fixes-090 will merge to fix-3.0:

Example: 'restrict_merges_to_branch' rule

'only_allow_merges_from_parent' rule

Definition

Only allows merges to a given branch that come from its parent.

This is very useful to enforce that certain branches only allow to be rebased from the parent, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.

Example

[{
   "enabled": true,
   "repositories": "game*",
   "rule": "only_allow_merges_from_parent",
   "to":
   {
     "branchNames": ["task*"],
   }
}]

In repositories named like game*, branches with name task* can only receive merges from their parent branch. This way you can prevent merges across different task branches.

In the diagram below, branch task001 will receive merges from main, and branch task003 will receive merges from dev-002:

Example: 'only_allow_merges_from_parent' rule

'only_allow_merges_from_children' rule

Definition

Only allows merges to a given branch that come from its child branches.

This is very useful to enforce that certain branches only allow merges from the children, and won't accept changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams implement something very similar to restrict the flow of changes among streams.

Example:

[{
   "enabled": true,
   "repositories": "game*",
   "rule": "only_allow_merges_from_children",
   "to":
   {
     "branchNames": ["iteration*"],
   }
}]

In the repositories with the name game*, branches with the name iteration* can only receive merges from their child branches.

In the diagram below, /main/iteration-32/task23 can be merged into /main/iteration-32, but it cannot be merged into /main/iteration-15, as it is not a child of that branch:

Example: 'only_allow_merges_from_children' rule

Filtering

To filter the branches involved in a rule, you can use the branch name, the branch attribute, or both:

  • Filtering by name: Use the branchNames key to specify the branch names. For example:
    [{
        "enabled": true,
        "repositories": "game*",
    
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {
            "branchNames": ["main"]
        },
        "from":
        {
            "branchNames": ["scm*"],
        }
    }]
    
  • Filtering by attribute: Use the branchesWithAttribute key to filter by attribute by specifying the attribute name and/or a value. For example:
    [{
        "enabled": true,
        "repositories": "*",
    
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {   
            "branchesWithAttribute": [
                {
                    "attribute": "merge_only_reviewed",
                    "value": "enabled"
                }
            ]
        },
        "from": 
        {
            "branchesWithAttribute": [
                {
                    "attribute": "task",
                }
            ]
        }
    }]
    
  • Filtering by name and attribute: Combine the above filters to filter by branch name and attribute. For example:
    [{
       "enabled": true,
       "repositories": "game*",
       "rule": "only_allow_merges_from_parent",
       "to":
       {
           "branchNames": ["scm*"],
           "branchesWithAttribute": [
               {
                   "attribute": "restricted_rebases",
                   "value": "yes"
               }
           ]
       }
    }]
    

    or:

    [{
        "enabled": true,
        "repositories": "game*",
        "rule": "only_allow_merges_if_reviewed",
        "to":
        {
            "branchesWithAttribute":
            [
                 {
                    "attribute": "merge_only_reviewed"
                 }
            ]
        },
        "from":
        {
            "branchNames": ["scm*"],
        }
    }]
    

Managing the Merge Rules

The merge rules are stored in the mergerules.conf file in the server directory (where plasticd.exe is located). This is a JSON file that contains your configured merge rules.

The merge rules in this file must be placed inside an array [].

The following is an example of a mergerules.conf file with two merge rules:

[{
    "enabled": true,
    "repositories": "code*",

    "rule": "only_allow_merges_if_reviewed",
    "to":
    {   
        "branchNames": ["main"],
        "branchesWithAttribute": [
            {
                "attribute": "merge_only_reviewed",
                "value": "enabled"
            }
        ]
    },
    "from": 
    {
        "branchNames": ["scm*"],
        "branchesWithAttribute": [
            {
                "attribute": "task",
            }
        ]
    }
},
{
   "enabled": true,
   "repositories": "game*",

   "rule": "only_allow_merges_from_parent",
   "to":
   {
       "branchNames": ["scm*"],
       "branchesWithAttribute": [
           {
               "attribute": "restricted_rebases",
               "value": "yes"
           }
       ]
   }
}]

You will find a mergerules.conf file with some examples in your server directory, inside config_samples, alongside the binaries for clean setups (on Windows using the installer, and GNU/Linux using the official packages) so you can directly modify it.


  • mergerules.conf:

    To configure your merge rules, you can directly edit the mergerules.conf file in your server directory.

    Tip: You don't need to restart the server for changes to take effect!
  • Merge Rules section in the WebAdmin:

    You can manage your Merge Rules from the WebAdmin. You can select and configure the ones that fit your needs best.

    Merge Rules section in the WebAdmin
    Tip: You don't need to restart the server for changes to take effect!
  • Merge Rules for your cloud organization repositories:

    To configure the Merge Rules for your cloud organization repositories, navigate to your cloud dashboard and click Edit Merge Rules:

    Merge Rules for your cloud organization repositories

    In the dialog, you can manage your Merge Rules for your selected cloud repository:

    Merge Rules for your selected cloud repository

Chapter 20: Plastic .NET Core server

The Plastic SCM server runs .NET Core, the cross-platform, rock-solid, super-fast and officially supported framework.

Note:The Plastic .NET Core Server is available for Linux, macOS, and Windows beginning with version 8.0.16.4017.
The WebAdmin, WebUI, and mergebots features for Plastic .NET Core Server are available since version 8.0.16.4024.

The benefits of the Plastic .NET Core server:

  • Much faster on Linux and macOS.
  • Much faster SSL on Linux and macOS.
  • Linux integration with systemd.

Configuring the network with network.conf

If you've been using Plastic for a while, you'll definitely be familiar with remoting.conf, the configuration file to define the ports to listen, the SSL certificate, and a few others settings.

This configuration has been redesigned. This way, the .NET Core server uses a configuration file named network.conf.

Important! The network.conf configuration file applies to the Plastic .NET Core Server and replaces the remoting.conf one.
Note: The Plastic .NET Core server converts remoting.conf into network.conf on the fly if it finds one.

This is what a simple network.conf looks like for a server listening on 8084, and then on 8088 and 8787 using SSL:

[
    {
        "Port" : 8084,
        "Type" : "Tcp",
        "Security" : "None"
        "RejectRemoteRequests" : true,
    },
    {
        "Port" : 8088,
        "Type" : "Tcp",
        "Security" : "Ssl",
        "SslPfxFile" : "plasticscm.com.pfx",
        "SslPfxFilePassword" : "xxxxxxxxxxxxxxxxxxxxxx",
        "ReceiveTimeoutMsec" : 2000,
        "SendTimeoutMsec" : 2000,
        "ReceiveBufferSizeBytes" : -1,
        "SendBufferSizeBytes" : -1
        "BindTo" : "162.165.0.1"
    },
    {
        "Port" : 8787,
        "Type" : "Tcp",
        "Security" : "Ssl",
        "SslPfxFile" : "plasticscm.com.pfx",
        "SslPfxFilePassword" : "xxxxxxxxxxxxxxxxxxxxxx",
        "ReceiveTimeoutMsec" : 2000,
        "SendTimeoutMsec" : 2000,
        "ReceiveBufferSizeBytes" : -1,
        "SendBufferSizeBytes" : -1
    }
]

Most of the settings are optional. A network.conf like this is also valid:

[
    {
        "Port" : 8084,
    },
    {
        "Port" : 8088,
        "Security" : "Ssl",
    }
]

In the above example, this configuration will make the server listen on port 8084 without security, and then on 8088 with SSL, autogenerating a self-signed certificate the first time it runs.


Reloading network.conf on-the-fly

One interesting thing of the network.conf file is that it reloads on-the-fly. For example, if you add a new port, the server starts listening on the new port without restarting the existing ports. Only when it's mandatory, the server is restarted; for example, when you change an existing port.

Suppose you have the following network.conf file:

[
  {
      "Port" : 8085,
      "Type" : "Tcp",
      "Security" : "None",
      "RejectRemoteRequests" : false
  },
  {
      "Port" : 8088,
      "Type" : "Tcp",
      "Security" : "Ssl",
      "SslPfxFile" : "ssl-certificate.pfx",
      "SslPfxFilePassword" : "|SoC|2ogBDa8GmifTjC7UKp4KuoF0/jWYlXy2",
      "ReceiveTimeoutMsec" : 4000,
      "SendTimeoutMsec" : -1,
      "ReceiveBufferSizeBytes" : 30000,
      "SendBufferSizeBytes" : -1
  }
]

You can add a new port. The system will reload the file and listen on the new port, leaving the other two ports untouched. This means that the system doesn't restart the entire network.

The reload system actually calculates diffs, so it knows what to do:

  • If you only change the socket settings (ReceiveTimeoutMsec, SendTimeoutMsec, SendBufferSizeBytes, ReceiveBufferSizeBytes), the system simply sets the new properties and no restart of the "socket server" is needed.
  • If you only change the SSL settings change, the system simply sets the changes and no restart is required.
  • If you change a key property (like going from TCP to SSL, or changing the port), then the old port is stopped and the new one added.

    A key property is that kind of setting that require to "listen" again: RejectRemoteRequests, Type, Port, BindTo, and so on.


Last updated

March 17, 2022
  • The proxy is now part of the Plastic Server.
  • Read how to start the Plastic Proxy.
  • Learn how to manage the Plastic Proxy service on Windows .
  • Also learn how to configure the Proxy server and configure the Plastic SCM clients to use the proxy.
  • March 7, 2022
  • You can now use the plasticgui command to launch or configure the new Plastic GUI on macOS instead of using the old macplastic command. This new Plastic GUI is now the default GUI for macOS. It is cross-platform, includes a dark theme, and provides better syntax highlighting. Read more about the new Plastic GUI .
  • March 3, 2022
  • You can now use the plasticgui command to launch or configure the new Plastic GUI on Linux instead of using the old gtkplastic command. This new Plastic GUI is now the default GUI for Linux. It is cross-platform, includes a dark theme, and provides better syntax highlighting. Read more about the new Plastic GUI .
  • February 16, 2022
  • Updated the Minimun requirements section because Windows Vista is no longer supported.
  • November 4, 2021
  • You can now configure how often the Plastic server reloads the users and groups information from the authentication provider.
  • October 19, 2020
  • Learn how to configure the network.conf configuration file to start working with the Plastic .NET Core Server.
  • September 14, 2020
  • You can configure the server by running plasticd configure. (The clconfigureserver command is now deprecated.)
  • September 11, 2020
  • The webadmin supports HTTPS now!
  • Updated the reference to admin the password of the webadmin. The old way of setting the webadmin password was to run the adminconsolepwd utility. This tool has been deprecated and you should now use plasticd adminpwd.
  • September 10, 2020
  • Learn how to apply global rules to all repositories both by using the webadmin or the lock.conf file.
  • September 9, 2020
  • Included how to access the webadmin from Linux.
  • August 12, 2020
  • Fixed some examples about configuring lock rules.
  • June 19, 2020
  • Fixed the LdapTimeoutSeconds key name in the LDAP authentication configuration chapter. Before it was wrongly named as LdapTimeout.
  • June 18, 2020
  • We added two new settings to configure the LDAP authentication: LDAP token expiration time and Override for LDAP user filter.
  • May 25, 2020
  • You can configure the maxcachessizeingb and maxcachessizefreepercent parameters in the jet.conf file to specify the maximum amount of memory used by caches .
  • March 19, 2020
  • We added a new setting blobspath to jet.conf to allow storing blobs and metadata in different paths .
  • December 23, 2019
  • The Plastic Proxy now includes some features about monitoring space and cleaning cache up on disk:
  • October 31, 2019
  • filetypes.conf is now used for diffs and merges to check if a file is binary or text.
  • October 24, 2019
  • We included documentation about the mergerules.conf configuration file and about how to configure your Merge Rules system.
  • October 24, 2019
    October 2, 2019
  • Fixed a wrong text used when creating a self-Signed certificated on Linux and macOS systems.
  • March 22, 2019
  • We replaced the references to deprecated repository administration commands like cm mkrep for their new counterparts.
  • July 24, 2018
  • Learn how to configure the license auto-renewal option from the webadmin - Plastic SCM Server Administration console.
  • May 8, 2018
  • We highlighted some remarks about the Repository storage configuration, such as:
    • Plastic SCM needs to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
    • What configuration values have to be changed by the user and what values cannot be changed.
  • February 16, 2018
  • The lock.conf specification now indicates that the lockserver parameter is optional.
  • January 29, 2018
  • Please check the .Net framework required version.
  • November 21, 2017
  • You can now configure the externaltools.conf file to run external tools on Plastic SCM objects.
  • Learn how the eolconversion.conf configuration file works.
  • 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 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
  • Learn how to create a SQL Server database using the db.conf file
  • March 20, 2015
  • Included compression.conf file to choose a storage compression type
  • March 18, 2015
  • Updated lock.conf documentation. Added sample patterns
  • March 18, 2015
  • 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