Plastic SCM Administrator's guide


Chapter 1: Introduction

Plastic SCM

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

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

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

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


Components

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

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

Visit our web page to get a full and up to date list of compatibilities.


Chapter 2: Minimum requirements

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

Disk usage largely depends on your repository size.

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


Chapter 3: Plastic SCM installation


Prerequisites

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


Server and Client installation

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

Windows

The table below details the Plastic SCM installation steps:

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

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

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

Windows - Application to be started
Ready to install.

At this point the installer has all the needed information.

File copy progress. Windows - Installing
Once the installation is completed, the installer asks if the server configuration wizard should be launched.

If it's the first time you install Plastic, then the server configuration needs to be finished before Plastic SCM can be used.

If this is an upgrade (because there was a previous version of Plastic and the installer just upgraded it), then this step can be skipped.

Windows - Setup finished
Note: If the Windows Explorer Shell Extension has been installed, a reboot of the machine might be needed.

Linux

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

Important: Remember to run the commands as sudo.

Once the Plastic SCM Server and Client components are installed, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

The Plastic SCM Server is now configured by default with the following values:

  • Plastic SCM Edition - Team.
  • User authentication mode - Local name.
  • Database backend - SQLite.

If you need to change this configuration, please run the Plastic SCM server configuration wizard.

Mac OS

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

Follow these steps to install the Plastic SCM server:

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

At this point the installer has all the needed information.

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

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

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

At this point the installer has all the needed information.

MacPlastic client - Installation
MacPlastic installation process. MacPlastic client - Installing MacPlastic
The MacPlastic installation has finished. MacPlastic client - Installation finished

Once the Plastic SCM Server and Client components are installed, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

The Plastic SCM Server is now configured by default with the following values:

  • Plastic SCM Edition - Team.
  • User authentication mode - Local name.
  • Database backend - SQLite.

If you need to change this configuration, please run the Plastic SCM server configuration wizard.


Server configuration

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

Windows

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

Remember to run the commands as an administrator user.

If it's your first installation, then you must select what Plastic SCM edition you're going to use. You can choose between a Team Edition or an Enterprise Edition. Here you can find all the information about the Plastic SCM Editions.

Server configuration wizard - Select Plastic SCM edition

Once the edition is selected, then you must continue with the Server configuration wizard to configure the following:

Server configuration wizard

  • Server port numbers:
    • TCP port: By default Plastic SCM will use 8087 as its TCP port number. If the default listening port is changed, Plastic SCM clients must be setup to this new port.
    • SSL port: It's possible to assign a port number to specify where the Plastic SCM server listens for the encrypted data. Get here further information.
  • Users authentication mode: Here you have to choose between the different authentication mechanisms available. By default the Local name option is selected.
    • If the User/password mode is selected then you'll be asked to create/configure the Plastic SCM users using the User management tool.
    • If the LDAP mode is selected, then the Configure button will be enabled and you'll be able to setup the LDAP authentication parameters:
      • LDAP server name and port (by default, 389);
      • the domain from which data must be retrieved;
      • a user name and a password to be used to access the LDAP server;
      • and, finally, choose whether the LDAP server is an Active Directory or a conventional LDAP server.

      LDAP Authentication configuration

      Remember: The LDAP and Active Directory authentication modes are only included with the Enterprise Edition.

    More details about the authentication modes can be found at this section.

  • Database backend: The user can configure the database backend that will be used by the Plastic SCM server. The default backend for the new Plastic SCM Server installations will be set to SQLite. Read more about how to configure it.
  • License: In this section the user can configure all about the Plastic SCM license: buy a Plastic license, enter the plasticd.lic license file, or configure the auto renewal option. Get more information in this chapter.
Once the Plastic SCM Server is configured, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

Linux

To run the Server configuration wizard from the command line, use the following command:
  • clconfigureserver - Configure the Plastic SCM server through the command line. Read this section to learn how this configuration works.

Remember to run the command as sudo.

Once the Plastic SCM Server is configured, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

Mac OS

To run the Server configuration wizard from the command line, use the following command: /Applications/PlasticSCMServer.app/Contents/Applications/clconfigureserver.app/Contents/MacOS/clconfigureserver

Configure the Plastic SCM server through the command line. Read this section to learn how this configuration works.

Remember to run the command as sudo.

Once the Plastic SCM Server is configured, if it's the first time you install Plastic, then the client configuration needs to be finished before Plastic SCM can be used.

Command line

Server configuration - Command line

  • Language: Type the number related to the language you want to use to configure the Plastic SCM server.
  • Users authentication mode: Here you have to choose between the different authentication mechanisms available:
    • If the LDAPWorkingMode option is selected then you must setup the LDAP authentication parameters:
      • LDAP server name and port (by default, 389);
      • the domain from which data must be retrieved;
      • a user name and a password to be used to access the LDAP server;
      • and, finally, choose whether the LDAP server is an Active Directory or a conventional LDAP server.

      LDAP Authentication configuration

      Remember: The LDAP and Active Directory authentication modes are only included with the Enterprise Edition.
    • If the UPWorkingMode (user/password) option is selected then you'll be asked to create/configure the Plastic SCM users using the User management tool.

    More details about the authentication modes can be found at this section.

  • Server port numbers:
    • TCP port: By default Plastic SCM will use 8087 as its TCP port number. If the default listening port is changed, Plastic SCM clients must be setup to this new port.
  • Plastic SCM edition: If it's your first installation, then you must select what Plastic SCM edition you're going to use. You can choose between a Team Edition or an Enterprise Edition. Here you can find all the information about the Plastic SCM Editions.
  • License: In this section the user can configure the auto renewal option. Get more information about it in this chapter.

Client configuration

Each time a new client is installed on a developer's machine, it must be configured to enable it to connect to a Plastic SCM server. This can be easily done using the Client configuration wizard.

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

Windows

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

Using the Client configuration wizard the user can configure:

Windows - Client configuration wizard

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

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

      Scan network - Find servers

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

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

Linux

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

Using the Client configuration wizard the user can configure:

Linux - Client configuration wizard

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

Mac OS

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

Using the Client configuration wizard the user can configure:

Mac OS - Client configuration wizard

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

Command line

Client configuration - Command line

  • Language: Type the number related to the language you want to use to configure the Plastic SCM client.
  • Authentication mode: Type the number related to the authentication mode you want to use. This should be the authentication mode selected in the Server configuration wizard. If you type the UPWorkingMode, then you must enter a username and a password.
  • Workspace connection: First type the Plastic SCM server address (name or ip), and then, the server port.

Merge and Differences Tools configuration

This section describes how to configure the Plastic SCM client to use a specific merge or diff tool for specific types of files.

Note that Plastic SCM includes its own 3-way merge and diff tool, so this step is not required in the default setup.

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

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

The default rules for the merge tool are listed here:

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

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

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

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

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

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

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

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

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

Start working with Plastic SCM

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

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

Windows

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

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

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

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

Linux

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

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

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

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

Mac OS

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

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

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

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


User authentication configuration

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

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

Authentication basics

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

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

Local users

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

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

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

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

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


How does the server obtain the user list?

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


How is the SEID built?

Just with the user name.

Local users: name + ID

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

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

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

Under Unix based systems it will be the user id.

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

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


How does the server obtain the user list?

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


How is the SEID built?

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

Active Directory Integrated Security

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

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

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

Changing repository permissions

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

Specifying MADRID\coordinators

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


How does the server obtain the user list?

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


How is the SEID built?

A Windows SID.

LDAP

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

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

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


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.

User/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/password (UP) authentication mode, is appropriate for mixed Linux/Windows environments where LDAP or Active Directory integration is not an option, or to manage access to the Plastic SCM server on heterogeneous environments where there is no common user login among operating systems.

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

The Plastic SCM server keeps a list of the users, and each user defines his password. It also keeps groups as well as the relation between users and groups.

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

Configuration files in user/password mode

  • users.conf - Stores information about all the users and their encrypted passwords. The users.conf file contains the definition of the users known to the system in user/password authentication mode. The format of the users.conf file is very simple: it contains a list of the available users followed by their passwords as shown on the figure below:

    users.conf file format

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

    groups.conf file format

To configure the UP mode you must use the following tools:

The User management tool

The Users and groups management tool is the GUI tool to configure the users, groups and their relationships and passwords.

Read how to use the User management tool in your Windows, Linux or Mac OS system.

Windows
To run the User management tool (umtool) from the command line, use the following commands:
  • umtool - Run the umtool through the command line; parameters are needed. Read this section to learn how to run the umtool command.
  • umtoolgui - Open the umtool GUI. See the steps below.
The tool is located on the server's installation directory and can also be run from the Plastic SCM startup menu entry.

Remember to run the commands as an administrator user.

The next figure illustrates all the options. It is a simple and intuitive tool whose solely purpose is to help users configure the users.conf and groups.conf files.

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

umtoolgui usage

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

User and password configuration screen

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

Login dialog

Linux
To run the User management tool (umtool) from the command line, use the following command:
  • umtool - Run the umtool through the command line; parameters are needed. Read this section to learn how to run the umtool command.
Remember to run the command as sudo.
Mac OS
To run the User management tool (umtool) from the command line, use the following command: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool Run the umtool through the command line; parameters are needed. Read this section to learn how to run the umtool command.

Remember to run the command as sudo.

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. The umtool implements several commands detailed on the following table:

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

To learn how to use each command, please type the following:

  • Windows or Linux system: umtool help <command_name>
  • Mac OS system: /Applications/PlasticSCMServer.app/Contents/Applications/umtool.app/Contents/MacOS/umtool help <command_name>

Here you can find some examples:

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

How does the server obtain the user list?

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


What does the authentication contain?

It contains the username and the encoded password.


Server startup

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

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

Windows

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

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

    Managing Plastic SCM server service

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

Linux

To start and stop the Plastic SCM service on Linux systems, use the plasticsd script. This script is located in the server installation directory (/opt/plasticscm5/server by default). It is also available in the /etc/init.d directory to help with automatic start on system boot. You can also use it through the command service plasticsd <options>. This script has the following options:

plasticsd {start | stop | restart | status}

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

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

/etc/init.d/plasticsd status PlasticSCM server is started (PID xxxx)

PID xxxx is the running process ID of the server.

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

Mac OS

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

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

Run Plastic SCM

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

Windows

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

  • Open the Plastic SCM application from the startup menu:

    Windows - Run Plastic SCM

  • Type plastic in a command line interface window.

Linux

  • Open the Plastic SCM application from the Applications window:

    Linux - Run Plastic SCM

  • Type gtkplastic in a command line interface window.

Mac OS

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

  • Open the macplastic application from the Applications window:

    Mac OS - Run Plastic SCM

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

Chapter 4: Using a proxy server

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

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

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

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

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

  • The server will act as a data cache. No other data or metadata besides revision information will be stored.
  • All cached data will be stored on a configurable disk directory for simplified administration.
  • Data transmission between the proxy server, repository server and client will use the same data exchange protocol used by Plastic SCM, exchanging data chunks of 4Mb max size.

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

Example of proxy deployment

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

Example of network

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

Same network, improved by using two proxies


Installing the Plastic SCM Proxy server

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

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

Installation directory selection.

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

Proxy installer binaries folder
Cache storage.

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

Cached data directory location
TCP Listening port.

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

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

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


Configuring the clients

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

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

Configuring a proxy server in the Plastic SCM client

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


Chapter 5: Creating and managing repositories

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


Creating a new repository

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

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

cm mkrep PlasticServer:8087 NewRepository

Where:

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

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

Creating a new repository in the Plastic SCM GUI client

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

New repository dialog

Listing available repositories

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

cm lrep backyard:8087

Will show the output:

default@backyard:8087 doom3scr@backyard:8087

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

Repositories view

Archiving repositories

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

In order to archive a repository, the removerepository command is used, providing a repository specification.

First, list all repositories:

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

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

Next is removing the repository:

cm removerepository myproject@localhost:8087

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

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

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

rep_xx.plastic

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

rep_3.plastic

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


Reconnecting archived repositories

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

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

In the sample above, several repositories have appeared/created since we archived myproject, which had number 3. Choose a free repository number not used in the list (next one is 8, but you can choose any other). Rename your database rep_3.plastic to rep_8.plastic. For instance, for an embedded Firebird database this means just renaming the database file on disk:

move rep_3.plastic.fdb rep_8.plastic.fdb

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

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

Chapter 6: Configuring Exclusive Checkout (Lock)

Files are the items that you work with in your repositories: text files, Word docs, Excel files, binary files, etc.


Exclusive checkout

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

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

How Does It Work?

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

The system performs the following operations:

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

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

The lock.conf File

Configuring exclusive checkout is as simple as creating a lock.conf file on the server's directory with the following format:

rep:<repname> lockserver:<server>:<port>

where:

  • repname is the name of the repository where you want to perform exclusive checkouts.
  • server is the ip or the name of the lock server.
  • port is the port where the lock server is configured.

The next thing to do is to configure the paths that will be exclusive checkouts. You can specify complete paths or patterns.

Specify each rule in a new line.

Once you've created the file lock.conf and restart your server, 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.

Example:

rep:default lockserver:mainsvr:8084
*.doc
*.xls
*.jpg
document.vcs

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

Locks and paths

Previously we've seen how to lock some types of files existing in a repository. But sometimes what you'll need is to lock a directory or some files under a specific folder. We're going to see how to use these locks using some examples.

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

Chapter 7: Admin Tool


Summary

In this section you will see the server version installed on your machine, information about your license and the database backend you're using.

Summary

Users and licenses

This section lets the user configure change the authentication provider used to list users in the Plastic SCM server.

Users and licenses

The Administration tool section features a migration wizard that guides the user in configuring the new authentication provider, test the connection if needed, and most important: it lets the user view all the existing users and maps them automatically to those with the same name in the new authentication provider. If an old user is not found in the new provider, a mapping editor lets the administrator search and set which user it corresponds to in the new provider.

Click on Change authentication mode. In the first step of the migration wizard you have to choose the new authentication provider.

Choose the new authentication provider

In the picture below you'll see the options for the configuration of the LDAP provider.

Configuration of the LDAP provider

User mapping from the old provider to the new one is required for other authentication providers.

User mapping

In the Mapping editor you can assign the user in the new provider that corresponds to old-provider user.

This picture shows the search box listing users that contain the string "da" from the new provider.

Edit user mapping

Database

To change the database backend, click on Database on the left panel and then click the Migrate database backend button on the right panel. This operation will change migrate your existing repository data from the current database backend to the new one of your choice.

Database
Note: please note that migrating your data requires stopping the Plastic SCM server and it can take some time if your repositories have lots of data. While the migration is running, your users will not be able to access the Plastic SCM server.

If you have just installed Plastic SCM and have no data in your repositories yet, the migration is very fast.

The next figure shows the migration wizard initial screen, with a Plastic SCM server currently configured to use the default Microsoft SQL Server CE backend and prompting the user to choose the new database backend.

Database migration wizard

Selecting a database backend and clicking Next will move the wizard to the second step.

Here you can see this step for Microsoft SQL Server migration:

Database migration: target database options for Microsoft SQL Server

And here for Firebird (Embedded) migration:

Database migration: target database options for Firebird (Embedded)

This is a list of the options common for all backends (please, see the Database setup chapter for further information):

Connection string
In general, you only need to fill in the database server name, the user and the password to connect to the database backend.

Note that Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

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

Database prefix
You are also permitted to create prefixes for your database as with the suffixes. You can do this using any of the three following possibilities:
  • using the configuration wizard
  • modifying the db.conf using the tag <DatabasePrefix>
  • Here is a MySQL db.conf example, using this option:

    <DbConfig>
      <ProviderName>mysql</ProviderName>
      <ConnectionString>Server=localhost;UserID=root;Password=xxcode;Database={0};Pooling=false</ConnectionString>
      <DatabasePath />
      <DatabasePrefix>production_databases_</DatabasePrefix>
    </DbConfig>
    
  • or using --dbprefix=whatever in the plasticd command line
  • This accomplishes the same thing, but using the command line:

    plasticd --console --dbprefix=production_databases_
Database path on the server
Optionally, you can set the directory where the Plastic SCM will ask the database backend to store the database physical files.

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.




Before proceeding to the next step, test that everything is fine by click the Test connection button.

If the test is completed successfully, the Start migration" button is enabled and you can start with the migration.

Before starting, the wizard displays a reminder about stopping the server before doing the actual migration.

Remember to stop the Plastic SCM server before migrating the database

After clicking Ok, the wizard will move to the migration status page, indicating the overall progress of the operation and the progress of each individual repository. If everything is completed correctly, you will see the "Migration succeeded" message at the end:

Migration finished

When the database migration is completed, the wizard creates a new db.conf file with the database backend options specified in step 2 and renames the old one to db.conf.old. The next time the Plastic SCM service is started, it will connect to the migrated databases.


Listening ports

The Administration tool features a section to configure the ports where the server listens for both encrypted and non-encrypted data.

Listening ports configuration

For the encrypted SSL port, certificate setup is also provided. If any value is changed, the Apply Changes and Cancel buttons are enabled.

It is possible to select a new certificate file by clicking on the ellipsis button . A password to open the certificate file is requested when the user clicks Apply Changes.

Password requested

If the password is wrong, the changes are not applied to the file.

All the configuration values in this section are read and written to the remoting.conf file in the server installation folder. The old settings are backed up to remoting.conf.backup when Apply Changes is clicked and the remoting.conf file is successfully saved.

A final window will pop up requesting a restart of the Plastic SCM server.

Request restart

Audit log

The Administration tool features a section to configure the Auditing log.

Audit log

It is possible to set up the auditing level as well as the auditing log file. If any of these values are changed then the Apply changes must be clicked on and the Plastic server has to be restarted.

The audit log is active by default and set to log level 1 on the file audit.log (which 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
It's the unique identifier of the logged operation. This section provides a button to validate the hashes in the log file in case someone modifies the file "manually". If an administrator clicks on the Validate log hashes and the file has been edited then an error message will be displayed.
user
The user/developer who performed the operation.
machine
The machine which operation is performed from.
timestamp
When the operation was performed.
repository
The repository that was affected by the operation.
operation
The description of the performed operation.

This is an example of an audit log file:

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

The Audit log section shows the last line in the log file, so an administrator can get it from there.

There is another way to collect hashes regularly by scheduling a command to tail -n 1 audit.log |mail admin@myorg.com.


Chapter 8: Database setup

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

  • Firebird (Embedded)
  • SQLite (Embedded)
  • PostgreSQL
  • MS SQL Server & MS SQL Server Express
  • MySQL
  • Oracle
  • SQL Server Compact Edition (Embedded)

After the first installation, the Plastic SCM server will use an embedded database backend: SQL Server Compact Edition if the server is running on Windows, or SQLite if is running on Linux.

The database backend can be changed using:

  • the Administration Tool, accessible from the startup menu in windows, under the Plastic SCM menu / Server tools. You can get further information in the previous chapter.
  • or, creating/editing a db.conf file as you'll see in this chapter.

There are two common operations you have to execute when configuring the database backend:

  • stop the Plastic SCM server before changing the database backend,
  • and later, restart the Plastic SCM server.

Stop the Plastic server

If you're on Windows, this is an easy step. Just go to services and stop Plastic SCM. If you're on Linux it's not hard either: su to root and go to the Plastic SCM server installation directory (typically /opt/PlasticSCM/server) and run:

# cd /opt/PlasticSCM/server # sudo ./plasticsd stop

See if the server can start with the new configuration parameters

While you can directly use the plasticsd script to restart your daemon on Linux, or go to Services on Windows and start the service again (it will work if you set everything up correctly), there is another thing you can do which is very useful for diagnostics. Just run plasticd --console

The server will start in console mode. Wait until you read a message saying the server is up and running and see if there are any errors.

In case you need detailed information, check the loader.log.txt file, which will contain the errors.

Note: Something very useful for diagnostics is modifying your logger configuration (loader.log.conf) to make plasticd output the log on the console, and then rapidly check if something is wrong. Remember to set it back to file logging once you're done!

Once you've checked this, you can start up the service/daemon and you can run it with the regular services or ./plasticsd method.


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

Plastic SCM is deployed with a MS SQL Server CE backend.

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 MS SQL Server CE belong to this group.

Stop the Plastic server

First of all you have to stop the Plastic SCM server.

Configuring the Plastic SCM server

You can use the db.conf file or configure the Administration tool.

Edit/create a db.conf file

In order to configure the db.conf file to use those embedded database backends, you have to apply some specific values to the lines <Provider>...</Provider> and <ConnectionString>...</ConnectionString>.

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

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

As you've seen above the relevant lines to be changed in order to correctly configure the db.conf file are <Provider>...</Provider> and <ConnectionString>...</ConnectionString>. Remember to write a value to the <DatabasePath>...</DatabasePath> line if you want to specify a particular location for the Plastic SCM repositories.

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>
Configuring the Administration Tool

You have to use the Administration tool and choose the correct option. It's not necessary to configure any other extra parameter unless you want to specify a database prefix or suffix , or a particular database path.

The following table covers these supported embedded backends:

Backend Arguments
Firebird By default, Firebird uses the embedded backend, which doesn't require any specific arguments. The default user and password are used to connect to the embedded server.
SQLite By default, SQLite uses the embedded backend, which doesn't require any specific arguments.
Microsoft SQL Server CE (Embedded) By default, SQL Server CE uses the embedded backend, which doesn't require any specific arguments.

Restart the Plastic server

Now that you've configure Plastic SCM to work with the selected embedded database backend you have to restart the Plastic SCM server.


Configure Plastic SCM with PostgreSQL

Stop the Plastic server

Stop the Plastic SCM server before doing any change.

How to configure Plastic SCM with PostgreSQL

You can use the db.conf file or configure the Administration tool.

Edit/create a db.conf file

In order to connect to a PostgreSQL instance, you need to create the db.conf file with the following content.

Note: In the following two examples of code, the lines <ConnectionString>....</ConnectionString> must be on one complete line. It has been split here for the sake of visual clarity.
<DbConfig>
  <ProviderName>postgresql</ProviderName>
  <ConnectionString>
      Server=_SERVER_;Port=_PORT_;Database={0};
      User ID=_USER_;Password=_PASSWORD_;Pooling=false;
  </ConnectionString>
  <DatabasePath></DatabasePath>
</DbConfig>
Note: Replace the parameters _SERVER_, _PORT, _USER_, and _PASSWORD_ with the appropriate ones according to the server configuration that you want to use.

Thus, a valid db.conf file in our development environment would be:

<DbConfig>
  <ProviderName>postgreSQL</ProviderName>
      <ConnectionString>
      Server=venus;Port=5432;Database={0};
      User ID=postgres;Password=mypwd;Pooling=false;
     </ConnectionString>
    <DatabasePath></DatabasePath>
  </DbConfig>

Now, when the Plastic SCM server starts, the new db.conf configuration will be read and the connection with the PostgreSQL will be established.

Configuring the Administration Tool

In this section you can see all the parameters to configure the database backend.

These are the required parameters to configure the PostgreSQL database backend:

Server
The database server machine.
User name
User account to connect to the backend.
Password
Password for the account.

Restart the Plastic server

Now that you've configure Plastic SCM to work with PostgreSQL you have to restart the Plastic SCM server.


Configure Plastic SCM with MS SQL Server

Supported SQL Server versions

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

Reasons to switch to SQL Server

There's not a rule of thumb here. If your company or your sysadmin is more used to SQL Server, then go to SQL Server. Some companies prefer to use a single corporate SQL Server and integrate all their data there, and that is perfectly possible with Plastic SCM. You can use standard SQL Server tools to query the databases, run back-ups, and so on. Maybe you and your team are more used to set up and back up SQL Server than Firebird or MySql, and you prefer to have your data there. Plastic SCM's performance with SQL Server is excellent, something to keep in mind when your team grows, or if you need Plastic SCM to go faster. Using a dedicated SQL Server machine for the database and another server for Plastic SCM will increase performance under heavy load scenarios. As you know, upon installation, our software comes with an embedded Firebird database set up, which is pretty good for an average number of users, but we recommend teams to switch to Firebird Server, SQL Server, or MySql as the team grows.

Stop the Plastic server

First of all you have to stop the Plastic SCM server.

Configuring the Plastic SCM server to work with SQL Server

You can use the db.conf file or configure the Administration tool.

1.- Edit/create a 'db.conf' file

Plastic SCM database backend configuration is set up on a file named db.conf, located in the server directory (where the plasticd server is installed). It's a pretty simple xml file which tells the database backend to use and how to connect to it. If you've installed the Plastic SCM server on Windows, the file won't exist and you'll have to create a new one. Linux users will always have a db.conf file.

Note: The line <ConnectionString>....</ConnectionString> must be on one complete line, it has been split here for the sake of visual clarity.

So, if you're on Windows, create a new file db.conf and write the following content:

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

In that example you can see it uses a SQL Server Express server (beardtongue\SQLEXPRESS instance in the connection).

If you want to connect to a regular SQL Server you can use the following configuration:

<DbConfig>
  <ProviderName>sqlserver</ProviderName>
  <ConnectionString>
      SERVER=_SERVER_;User Id=_USER_;Pwd=_PASSWORD_;
      DATABASE={0};
  </ConnectionString>
  <DatabasePath>d:\_PATH_</DatabasePath>
</DbConfig>
Note: Remember to replace the examples _SERVER_, _USER_, _PASSWORD_, and d:/_PATH_with your own server and authentication data!!
Note that the second sample uses the DatabasePath, which tells SQL Server the location to place the data and log files for Plastic SCM repositories.
  • DatabasePath is mandatory when the SQL Server is on a different machine than the Plastic SCM Server.
  • If it's on the same machine and if you don't specify that value, SQL Server will use its default location.
  • In the samples above the connection string use built-in SQL Server authentication which is basically telling Plastic to use a given user and password. If you want to use built-in Windows authentication you'll have to modify your db.conf in the following way:

    <DbConfig>
      <ProviderName>sqlserver</ProviderName>
      <ConnectionString>
          SERVER=beardtongue\SQLEXPRESS;
          trusted_connection=yes;DATABASE={0};
      </ConnectionString>
    </DbConfig>
    
    Note again that the lines <ConnectionString>...</ConnectionString> must both appear on one line in your actual code.

    Then, restart Plastic SCM. The key is replacing the user and password data by trusted_connection. There's an important tip to remember here -- since you'll normally be running the Plastic SCM server under the system account on Windows, you'll have to make sure that account has rights to access your SQL Server database under trusted connection. You can always change Plastic SCM's service configuration (using the services applet in your Administrative Tools on the Control Panel) to make it run under different credentials.

    Database creation inside the 'db.conf' file

    New in 5.4

    The SQL Server database creation command can be customized with your own settings. To do this you have to include a new key in the db.conf file called DatabaseCreationCommands.

    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.

    @PlasticDefaultLogFile

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

    @PlasticDefaultCollation

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

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

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

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

    Here are some custom database creation command examples:

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

    In this section you can see all the parameters to configure the database backend.

    These are the required parameters to configure the PostgreSQL database backend:

    Server
    The database server machine and instance.
    User name
    User account to connect to the backend, if using SQL Server authentication.
    Password
    Password for the account.
    Note that the Database path parameter in the Administration tool tells SQL Server the location to place the data and log files for Plastic SCM repositories. If you don't specify, SQL Server will use its default location.

    Starting up Plastic SCM

    Once the db.conf file has been correctly set up, you have to restart the Plastic server. On start-up it will connect to the new database and create the database's repositories, workspaces, and rep_1 (the default repository), if they're not there.

    Troubleshooting the new connection

    Setting up a SQL Server backend should be really easy, but you know problems can always show up! If this is the case, remember to check the loader.log.txt file at the server's install directory which contains the server's log. The most common connection problems to check are:

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

    Configure SQL Server memory usage

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

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

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

    This limits it to 300Mb.

    Check out the following links for more information:


    Configure Plastic SCM with MySQL

    Stop the Plastic server

    The first thing you have to do is stop the Plastic SCM server.

    How to configure Plastic SCM with MySQL

    You can use the db.conf file or configure the Administration tool.

    Edit/create a db.conf file

    It's very simple to set up, you only need to create (or edit) a file named db.conf on the Plastic SCM server installation directory. It must have the following content:

    Note: In the following two examples of code, the lines <ConnectionString>....</ConnectionString> must be on one complete line. It has been split here for the sake of visual clarity.
    <DbConfig>
      <ProviderName>mysql</ProviderName>
      <ConnectionString>
          Server=_SERVER_;User ID=_USER_;Password=_PASSWORD_;
          Database={0};Pooling=true
      </ConnectionString>
      <DatabasePath></DatabasePath>
    </DbConfig>
    
    Note: Replace the parameters _SERVER_, _USER_, and _PASSWORD_ with the appropriate ones according to the server configuration that you want to use.

    Thus, a valid db.conf file in our development environment would be:

    <DbConfig>
      <ProviderName>mysql</ProviderName>
        <ConnectionString>
        Server=venus;User ID=myuser;Password=mypwd;
        Database={0};Pooling=true
      </ConnectionString>
      <DatabasePath></DatabasePath>
    </DbConfig>
    

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

    Note: Some linux ditributions 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
    Configuring the Administration Tool

    In this section you can see all the parameters to configure the database backend.

    These are the required parameters to configure the MySQL database backend:

    Server
    The database server machine.
    User name
    User account to connect to the backend.
    Password
    Password for the account.

    How to fine tune MySQL for Plastic SCM

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

    Hardware

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

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

    Steps

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


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

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

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

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

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

    max_allowed_packet = 10M

    Start the Plastic server

    Once you've configured MySQL as the Plastic SCM database backend you have to start the Plastic SCM server.


    Configure Plastic SCM with Oracle

    Stop the Plastic server

    Remember to stop the Plastic SCM server before doing any change.

    How to configure Plastic SCM with Oracle

    You can use the db.conf file or configure the Administration tool.

    Edit/create a db.conf file

    If you're on Linux, you'll have a db.conf file at the server's directory (/opt/PlasticSCM/server/db.conf). You'll just have to edit it. In case you're on Windows, by default, the file won't be there, so just create a new one. Here's what you'll have to put in the file for the Oracle connection:

    Note: The lines <ConnectionString>....</ConnectionString>, <AdminConnectionString>....</AdminConnectionString>, and <DatabaseCreationCommands>....</DatabaseCreationCommands> must each go on one complete line. They have been split here for the sake of visual clarity.
    <DbConfig>
      <ProviderName>oracle</ProviderName>
      <ConnectionString>Direct=true;User={0};Password={0};
        Data Source=oracle.codicefactory.com;Port=1521;SID=orcl
      </ConnectionString>
    
      <AdminConnectionString>Direct=true;User Id=SYS;
        Password=oracle;Data Source=oracle.codicefactory.com;
        SID=orcl;Connect Mode=sysdba
      </AdminConnectionString>
    
      <DatabaseCreationCommands>
        create smallfile tablespace @PlasticDatabase datafile
        @PlasticDatabase.dbf' size 10M 
        reuse autoextend on next 10M;
        create user @PlasticDatabase 
        identified by @PlasticDatabase
        default tablespace @PlasticDatabase 
        temporary tablespace Temp account
        unlock quota unlimited on @PlasticDatabase;
        grant connect, resource, create session, create table, 
        create view, create any index to @PlasticDatabase;
      </DatabaseCreationCommands>
    </DbConfig>
    

    First of all, you have to specify the kind of backend you're going to use. That's the line ProviderName.

    Second, you have two connection strings: one for the regular operations and one for the administrative ones. What does that mean? Plastic SCM will always connect to Oracle using the first connection string except when it has to create new repositories (for instance, during the first start-up with the new backend). Then it will use the AdminConnectionString.

    This is because many companies prefer to have control on those applications running with high permissions continuously. So this way, we clearly separate the way in which connections are established

    The DatabaseCreationCommands lets you customize the way in which databases are created.

    By default, every Plastic SCM repository will be a tablespace, and it will create a user associated with it. You can find the create tablespace and create user sentences there. You can modify them to better fit what you really want to achieve.

    For instance, the tablespace is created as a small one, but you'll probably want to create it as a bigger file, adjust the initial size to something bigger than 10MB, and autoextend with a larger amount too.

    Configuring the Administration Tool

    The Oracle database provider in Plastic SCM works in a different way compared to the others, due to its special way of managing databases. In the Oracle backend, Plastic SCM doesn't create a database for each repository. Instead, each repository is a tablespace inside the database specified by the "Oracle SID" argument.

    Database migration: target database options for Oracle

    Server
    the server machine with the Oracle backend.
    Port
    the Oracle Net Listener port
    Oracle SID
    the SID of the oracle database to connect to.
    Admin User name
    user account to connect to the backend, with tablespace creation privilege.
    Admin Password
    password for the account.
    Admin connection mode
    normally "sysdba".

    In this section you can see the rest of the parameters to configure the database backend.

    Restart Plastic SCM server

    Once you've edited db.conf, the next step is to start up the Plastic SCM server again and check if everything is up and running.

    See if you can connect to the new database

    If you run a cm lrep command against your server, now you should see your new empty databases being created. You should be able to create new repositories too.

    Some important notes for database administrators: Plastic SCM does not create a new Oracle database to store the repositories' data. Instead of that, it creates a new tablespace inside the existing database instance. The reason for doing that is that an Oracle database is a very heavyweight object, which implies new processes and a lot of resource consumption.

    One of the most important consequences is the encoding that Plastic SCM will use. In Oracle, the encoding is established in the CREATE DATABASE sentence, and after that, it is very tricky to change it. The simplest case is that the new encoding that you want to set is a strict superset of the old encoding. In this case an ALTER DATABASE CHARACTER SET statement should work fine.

    Thus, Plastic SCM will use the encoding defined by the database instance in which the tablespaces are created. Take this into account in case you want to use Arabic, Asian, or other non-standard symbols in your version control system.

    In order to know which encoding is configured in your database, mount the target database instance and execute the following query in sqlplus:

    select value from nls_database_parameters 
    where parameter='NLS_CHARACTERSET';
    

    We recommend setting the encoding to utf8 for a better user experience.

    Further information here:

    Screencast

    The following screencast we uploaded to our YouTube channel shows how to set up an Oracle backend on a Linux Plastic SCM server.

    Check it out to see the steps I just have described in action.



    More information

    As you've seen, Plastic SCM can be configured to use different database backends to store data and metadata.

    Here you can get further information:

    Migrating from a different database backend

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

    Plastic SCM uses standard databases and database structures, so you'll just have to import the data using a standard migration tool (a quick search on google will help, see also DbNetCopy or the built-in SQL Server migration tool in case you want to migrate to MS SQL Server). Or just use the Plastic SCM internal migration tool.


    Chapter 9: Backup and restore

    The backup and restore procedures are closely related to the database backend used in Plastic SCM. Out of the box, the Plastic SCM server uses an embedded SQL Server CE or embedded SQLite when running under Windows and Linux/MacOSX respectively.

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

    How to backup the embedded databases

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

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

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

    Steps to backup:

    1. Stop Plastic server: plasticd --stop.
    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 Plastic server again: plasticd --start.

    Restore embedded databases

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

    1. Stop Plastic server: plasticd --stop.
    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 Plastic server again: plasticd --start.

    Chapter 10: Archiving revisions


    Why archiving revisions

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

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

    How archive command works


    How to archive my revisions

    To archive revisions use the archive command:

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

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

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

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

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

    How are the archived revisions accessed

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

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

    This file can be placed in two locations:

    • On the server side: placing the externaldata.conf file on the Plastic SCM server location will allow every user of that server to access those revisions automatically, as long as the external storage area is available. This is the most useful option for system administrators.
    • On the client side: placing the externaldata.conf file on the Plastic SCM client folder or on the user local directory (within Documents and Settings in Windows XP, Users in Vista/Seven, or home in UNIX based systems).

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

    Introduce the external data location path

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

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


    How to restore archived revisions

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

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

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

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

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


    Chapter 11: Upgrade system

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

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


    How to configure it

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

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


    Example

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

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

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

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

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


    How it works

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

    Dialog - New version available

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

    Dialog - Plastic SCM Upgrade

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

    Follow the installer wizard sequence by clicking the Next buttons.

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


    Chapter 12: Plastic SCM SSL certificates

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


    Tools

    Depending on the Operating System (OS) that is installed on your system, you will need different tools to create a certificate. In this article we will explain how to create a certificate for a Windows or Linux OS.

    Windows

    For Windows you will need to install the makecert and pvk2pfx tools that are included with the Visual Studio SDK that can be downloaded here.

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

    Linux

    For Linux and MacOS, one of the most versatile SSL tools is openssl which 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

    Windows

    In order to create the self-signed certificate you need to use the makecert command which will generate the .pvk and .cer files. The command line that you will enter is as follows:

    makecert -n "CN=TARDIS" -r -a sha1 -sky exchange -sv TARDIS.pvk TARDIS.cer

    During the creation process you will be asked for a password. Make a note of the password as it will be used later for the pvk2pfx command.

    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. The command line that you will enter is as follows:

    pvk2pfx -pvk "TARDIS.pvk" -spc "TARDIS.cer" -pfx "TARDIS.pfx" -pi <password>

    It is a good idea to name the .pvk, .cer and .pfx files with the machine hostname where the Plastic SCM server is installed. If you do not use the machine hostname you will continuously receive warnings that the certificate doesn't match the Plastic SCM server hostname. As you can see in the command line example above, we are issuing the certificate for a Plastic SCM server called TARDIS so the resulting output files are labeled 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

    In order to create the self-signed certificate you will use the openssl command for creating the .pem file. The command line that you will enter is as follows:

    openssl req -x509 -nodes -days 3650 -newkey rsa:4098 -keyout key.pem -out key.pem

    When you execute the command you will be prompted to answer a few questions that are required in order 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 will be using to connect with the server machine. In the following example the server name is TARDIS so that is the name that will be used for the Common Name field:

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

    The .pfx file is generated by exporting the recently created .pem file. The command line that you will use to export the certificate into a .pfx file is as follows:

    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.

    Windows

    To create a CA certificate you need to execute the following command:

    makecert -n "CN=Codice Software S.L" -r -a sha1 -sv CodiceCA.pvk CodiceCA.cer

    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

    Just as you did for the self-signed certificate you will execute the pvk2pfx command which will combine the .pvk and .cer files to generate the .pfx file as follows:

    pvk2pfx -pvk "PlasticServerTardis.pvk" -spc "PlasticServerTardis.cer" -pfx "PlasticServerTardis.pfx" -pi <password>

    Linux

    To create the root key you need to execute the following openssl command :

    openssl genrsa -out rootCA.key 2048

    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

    Just as you did with the self-signed certificate you will generate the .pfx file by exporting the recently created .pem file. The command line that you will use to export the certificate into a .pfx file is as follows:

    openssl pkcs12 -export -out ssl-certificate.pfx -in key.pem -name "PlasticSCM Certificate"

    Using the certificate for the Plastic SCM Secure channel

    The Plastic SCM server SSL channel is configured to listen by default on the 8088 port using the default SSL Plastic SCM SSL certificate. In order to use your own self-signed certificate you will need to edit the remoting.conf file that is located inside the Plastic SCM server directory. The two values that you will need to change are as follows:

    • Modify the sslPfxFile parameter to use your .pfx certificate
    • Modify the sslPfxFilePassword field 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.

    The following example will show you the server remoting.conf file using the new TARDIS.pfx certificate and the ciphered password:

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

    Once the remoting.conf file is saved you'll need to restart the service on the Plastic SCM server in order to apply the change.


    Accepting and installing SSL certificates for Plastic SCM

    There are several methods that you can use to install the Plastic SCM certificate. They include using the Plastic SCM GUI or CLI that will add a key to the certificate store or you can install it manually without using the Plastic SCM client at all. Let's take a look at how you would implement each of these methods.

    Plastic SCM GUI

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

    Install certificate using the Plastic SCM GUI

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

    Plastic SCM Command Line Interface (CLI)

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

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

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

    Manual installation

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

    Please keep in mind that the certificate you install will only be valid for the system user who accepts the certificate on the server. If you need to install a certificate that will be used by the Plastic SCM server then the system user on the server will need to run the Plastic SCM server/daemon as "Administrator" or "root" user. Let's take a look at how you could manually install the certificate on a Windows or Linux/MacOS based server.

    Windows

    The Microsoft Windows certmgr.msc tool is used to the install certificate files (.cer) that can be read by external applications. The certificates are imported by clicking in the Action menu and then selecting All tasks and then selecting Import:

    Certificate import wizard

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

    Certificate import wizard - specify location

    The next step is to place the certificate file (.cer) in the "Plastic Client" store then click Next to place the certificate in the store:

    Certificate import wizard - store certificate

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

    Certificate import wizard - completing

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

    Linux and MacOS

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

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

    For MacOS use this directory path:

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

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










    Chapter 13: Support alternative connections to the same server

    New in 5.4

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

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

    alias1 alias2
    

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


    Configuring the server aliases file

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

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


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

    The content of the serveralias.conf file will be:

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

    Chapter 14: Choose a compression method

    New in 5.4

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

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

    • none
    • zip

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


    Configuring the compression file

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

    none .jpg
    zip .txt
    

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

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

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

    If both files exist their rules will be combined.

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

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

    For instance:

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

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

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

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

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


    Chapter 15: How to configure the license autorenewal

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

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

    Windows

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

    Linux

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

    Mac Os

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

    Command line

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

    To do this follow these steps:

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

    Chapter 16: Configuration files

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


    File Description
    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 de cloaked list.

    compression.conf

    Lets the user select the compression type by using patterns.

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

    Learn about how to configure these patterns.

    cryptedservers.conf

    Stores the information to set up encryption in Plastic Cloud.

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

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

    customextensions.conf

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

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

    Learn about how to create your a custom extension.

    db.conf

    Stores the database backend settings that Plastic will use.

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

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

    externaldata.conf

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

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

    Learn about how to archive revisions and create this file.

    filetypes.conf

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

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

    Learn about how this file is created.

    gitserver.conf

    It is the file controlling the GitServer configuration.

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

    Learn about how to create this file to configure GitServer.

    gitsync.conf

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

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

    Learn about how this file works.

    groups.conf

    Stores the Plastic groups configured from the User management tool.

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

    guiclient.conf

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

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

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

    hidden_changes.conf

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

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

    Learn about how to configure the hidden changes list.

    ignore.conf

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

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

    Learn about how to configure the ignored list.

    languages.conf

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

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

    Learn about how to configure this file.

    lock.conf

    Stores the rules to configure exclusive lockouts.

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

    Learn about how to create these rules.

    openwith.conf

    Stores the Open With context menu applications and shortcuts.

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

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

    readonly.conf

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

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

    Learn about how to configure this attribute.

    remoting.conf

    Stores the listening ports configuration values.

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

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

    server.conf

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

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

    serveralias.conf

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

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

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

    upgradefiles.conf

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

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

    Learn about how to upgrade the system.

    users.conf

    Stores the Plastic users configured from the User management tool.

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

    writable.conf

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

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

    Learn about how to configure this attribute.


    Global file configuration

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

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

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

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

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

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

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

    How the global configuration is loaded

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

    How to set up the global configuration

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

    Create the plastic-global-config repository

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

    Example plastic-global-config

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

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

    plastic-global-config - Extensions and Configuration files


    Last 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.
  • Dec 17, 2016
  • The server aliases configuration file location has been fixed.
  • Jul 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.
  • Jun 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.
  • Nov 5, 2015
  • The Plastic SCM Server and Client installation and configuration chapter has been updated.
  • Sep 7, 2015
  • Review the new minimum requirements in order to install and use Plastic SCM.
  • Aug 7, 2015
  • The auditing log documentation has been updated.
  • Jul 22, 2015
  • Updated documentation about the following commands to work with the Plastic SCM Server on Windows, Linux and Mac systems:
  • May 27, 2015
  • Follow the steps to configure your server to use the license autorenewal
  • March 27, 2015
  • New in 5.4 Learn how to create a SQL Server database using the db.conf file
  • March 20, 2015
  • New in 5.4 Included compression.conf file to choose a storage compression type
  • March 18, 2015
  • Updated lock.conf documentation. Added sample patterns
  • March 18, 2015
  • New in 5.4 Learn how Plastic SCM supports alternative connections to the same server
  • February 25, 2015
  • How to create and use SSL certificates to be used with Plastic SCM