Plastic SCM Administrator's guide

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

Plastic SCM provides high-end SCM capabilities without imposing restrictions associated with high-end systems like complex installation, operation, and administration.

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

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

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

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

• Windows:
  • All Windows
  • Windows XP, Windows 2000, and Window Vista no supported due to .NET restrictions
• Linux: The following distros are supported (more info here)
  • Debian
  • Ubuntu
  • Fedora
  • Red Hat Enterprise
  • CentOS
  • OpenSUSE
• Mac OS:
  • Mac OS Mountain Lion (10.8) and above

Disk usage largely depends on your repository size.

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

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

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

Windows

Choose the installation directory for the Plastic SCM components.
Select the components. By default, the CLI and GUI clients are always installed. Optionally, the Plastic SCM server and integrations with 3rd party tools can be installed. Below is a description of each component.
The available components are: Client components: Command-line tool or command-line client (the cm command) - Installed by default. Graphical user interface client (plastic.exe) - Installed by default. Mergetool - Installed by default. Plastic Gluon - Installs the tool designed for users who typically work on a single branch with files that can't be merged. The typical users of the tool are artists involved with game development teams. See the Plastic Gluon guide for more info. Installed by default. Windows Explorer shell extension - Installs the Plastic SCM Shell Extension that integrates Plastic SCM with the Explorer. The integration lets the user do most of the operations available on the Plastic SCM GUI client directly from the Explorer. Server components - The Plastic SCM server. IDE integrations: Visual Studio integration package (2010 or higher) - This option installs a Source Code Control Package for Visual Studio to perform Plastic SCM operations and view Plastic SCM elements from the VS IDE. Also compatible with Atmel Studio 6.0. For more details, see the Plastic SCM IDE integrations guide. Eclipse plugin - The Plastic SCM integration with the Eclipse platform. Learn more about it in the Plastic SCM IDE integrations guide. Mylyn-Eclipse plugin - This option installs a plugin to integrate Mylyn for Eclipse with Plastic SCM. Requieres Eclipse plugin. IntelliJ IDEA 12/13/14, 11, and 8.1 plugins - The Plastic SCM integration with different releases of the IntelliJ IDEA platform. SCC plugin - This is a Plastic SCM implementation of the MS-SCCI interface. It provides checkin/checkout/add and basic file-level operations. The SCC plugin is used by many tools, especially in the Windows world, to interface with the version control backend. Check the documentation of your tool for compatibility with the MS-SCCI specification (also known as SCC). It used to be primarily used by Visual Studio but has deprecated since Visual Studio 2005. Plastic SCM offers a richer integration in the Visual Studio integration package. Office plugins - The Plastic SCM integration with different versions of Microsoft Office. Learn how this plugin works in the Plastic SCM Office guide.
Application to be started. Select which application will be started after the installation is finished: Plastic or Gluon.
Ready to install. At this point the installer has all the needed information.
File copy progress.
The Plastic SCM server installation has finished.
Note: If the Windows Explorer Shell Extension has been installed, a reboot of the machine might be needed.

Linux

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

Mac OS

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

Mac OS - Plastic SCM Server

Welcome to the Plastic SCM server installation.
Accept the license agreement and continue with the installation.
Choose the installation disk for the MacPlastic SCM components.
Ready to install.
Plastic SCM server installation process.
The Plastic SCM server installation has finished.

Mac OS - Plastic SCM client

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

Welcome to the MacPlastic SCM GUI client installation
Accept the license agreement and continue with the installation.
Choose the installation disk for the MacPlastic SCM components.
Ready to install.
MacPlastic installation process.
The MacPlastic installation has finished.

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

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

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

• Launch the webadmin - Plastic SCM Server Administration Console - the cross-platform admin tool.
or
• Open a command line:
  1. Run the command line admin tool as an administrator:
     • On Windows: plasticd configure
     • On Linux: /opt/plasticscm5/server/plasticd configure
     • On Mac OS: /Applications/PlasticSCMServer.app/Contents/MacOS/plasticd configure
  2. Configure the required settings:
     • Language: Type the number related to the language you want to use to configure the Plastic SCM server.
     • Users authentication mode: Choose between the different authentication mechanisms available:
       • TCP port - By default, Plastic SCM will use 8087 as its TCP port number. If the default listening port is changed, Plastic SCM clients must be set up to this new port.
       • SSL port - By default, the SSL secured port is 8088.
     • Users authentication mode - Choose between the different authentication mechanisms available:
       • If the LDAP option is selected, you must setup the LDAP authentication parameters:
         • LDAP server name and port (by default, 389);
         • The domain from which data must be retrieved;
         • A user name and a password to be used to access the LDAP server;
         • Choose whether the LDAP server is an Active Directory or a conventional LDAP server.
         
         Note: The LDAP and Active Directory authentication modes are only included with the Enterprise Edition.
       • If you select the User and password option, you need to create/configure the Plastic SCM users and groups.

       Learn how to configure the Authentication modes.

     • Database backend - Configure the database backend that you want to use. The available database backends list depends on the platforms.
     • License - You can configure the auto-renewal option for subscription licenses. You only need your license token. To get it, complete these steps:
       1. Navigate to your Plastic SCM dashboard.
       2. Sign-in into the Plastic SCM dashboard, where you can see your licenses. To get the license token available with your license, click the create license token link:
       3. Copy the license token:
       4. Paste it into the Server configuration tool:
       5. The license will be autorenewed and the token will download the new one.

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

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

Windows

Using the Client configuration wizard you can configure:

• Plastic SCM server:

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

    You can find servers in your network if you don't know the server hostname by launching the discovery service and clicking on the Scan network... button. The client sends a UDP packet using the broadcast IP (255.255.255.255). The server implements a little UDP server that listens for this message, which will contain the server's address, port, and version. The client listens for answers and filters servers that are not compatible with it; You can select a server from the list:

    

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

    <EnableDiscoveryService>no</EnableDiscoveryService>

  • Use encryption: Choose whether or not to use SSL when connecting to the server.
• User credentials: The Plastic SCM client automatically detects the authentication mode configured on the connected server. Enter the data required (as needed) and, optionally, click on the Check button to check the connection with the configured user's credentials.
• Proxy server: Optionally, you can use a proxy server. Read more about how to install and configure the Plastic SCM proxy server.

Linux

Using the Client configuration wizard the user can configure:

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

Mac OS

Using the Client configuration wizard the user can configure:

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

Command line

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

Merge and Differences Tools configuration

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

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

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

The default rules for the merge tool are:

FileType:

Indicates the types of files the rule will apply to. For example, they can be TextFile for files identified as text by Plastic SCM or BinaryFile for files identified as binary by Plastic SCM.

FileExtensions:

Indicates file extensions or types of files on which the rule is applied; if there is more than one extension for the same rule, they would be separated by ";." If the rule is used for every extension, "*" would be used.

Tools:

Different merge tools to be used on a specific file. If there is more than one tool, they are executed in order until one of them gives a result; only the first tool is used in the differences. These tools must have every mandatory parameter using the variables given, replaced by the system value during execution. For the system to use a specific value for a rule instead of a variable, that value would need to be set. The given variables are the following:

@basefile

path containing the merge common ancestor.

@basesymbolic

name shown on the tool to refer to the base file. Usually the spec revision or the disc file if loaded.

@basehash

common ancestor content hash.

@sourcefile

path containing the merge source file.

@sourcesymbolic

name shown on the tool to refer to the merge source file. Usually the spec revision or the disc file if loaded.

@sourcehash

merge source content hash.

@destinationfile

path containing the merge destination file, the location of the element in the workspace.

@destinationhash

merge destination content hash.

@output

file containing the merge result.

@filetype

type of file used for the syntax highlight.

@comparationmethod

comparison method used.

@fileencoding

file encoding.

@mergetype

type of merge used.

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

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

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

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

In the case of the different tools, rules are built similarly, but there are fewer variables. For example, to add a rule to calculate differences on a binary file (.scs) as a text file with the Unicode format, you'd write the following:

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

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

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

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

Windows

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

Choose one of the two following options:

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

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

Linux

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

Choose one of the two following options:

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

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

Mac OS

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

Choose one of the two following options:

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

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

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

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

Windows

Use one of the following methods:

1. To open the Windows Service Manager, navigate to Control Panel > Administrative Tools > Services or or run the services.msc command. Once the Services window is opened, you'll find the Plastic SCM service in the list. Use the start and stop actions available to normal services from the Services console.
   

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

Linux

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

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

This script has the following options:

For example:

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

Check whether the server is up and running by running one of the previous commands with the status option:

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

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

Mac OS

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

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

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

Windows

• Open the Plastic SCM application from the startup menu:
  

  Or:

• Type plastic in a command line interface window.

Linux

• Open the Plastic SCM application from the Applications window:
  

  Or:

• Type plasticgui in a command line interface window.

Mac OS

• Open the Plastic SCM application from the Applications window:
  

  Or:

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

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

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

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

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

Benefits of using a Proxy with Plastic SCM:

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

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

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

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

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

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

These are the operations available with the plasticd proxy subcommand:

• Install the Plastic Proxy service:

  plasticd proxy --installservice

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

• Start the Plastic Proxy service:

  plasticd proxy --start

• Stop the Plastic Proxy service:

  plasticd proxy --stop

• Restart the Plastic Proxy service:

  plasticd proxy --restart

• Print the status of the Plastic Proxy service:

  plasticd proxy --status

• Stop and uninstall the Plastic Proxy service:

  plasticd proxy --uninstallservice

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

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

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

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

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

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

You can click Connect to verify the connection is ready.

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

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

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

How to configure

Use the MaxCacheSizeInGb in the plasticcached.conf file.

For example:

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

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

A value of 0 means that the clean is disabled.

How it works

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

Some logs

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

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

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

Then, every 3 minutes, and during shutdown:

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

And during a clean up:

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

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

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

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

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

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

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

The log is as follows:

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

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

An empty repository named default is created on the first server startup if no other repository exists yet. You're all set!

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

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.

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

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

Output:

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

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

To archive a repository, the removerepository command is used, providing a repository specification.

First, list all repositories:

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

Next is removing the repository:

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.

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

rep_xx.plastic

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

rep_3.plastic

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

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

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

To reconnect, add the repository to the list of available repositories using the cm addrepository command:

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

Once the Plastic SCM server is installed for the first time, it is configured with the default values. The server is ready, and the Plastic clients can connect and run!

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

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

1. Open your favorite web browser and connect to your server address like this:
   • Use http://ipserver:7178 if you don't have any SSL ports defined in your server network configuration. The webadmin HTTP endpoint listens on port 7178 by default and it's bound to localhost only.
   • Use https://ipserver:7179 if you do have any SSL ports defined in your server network configuration. You can configure that port using the WebAdminToolSslPort setting in server.conf file. This endpoint will listen on any network interface.
   The web server automatically uses the first certificate you configured in your network settings. This means that the web interface will automatically use the same certificate for your Plastic SCM SSL connections without any further configuration. If you don't have any SSL ports defined in your server network configuration, only the HTTP endpoint will start.
   If you change the certificate you use for the SSL port at any point, make sure you restart the server to refresh the certificate information in the webadmin.
   • Or, directly run the webadmin tool:
     • From Windows: Launch the Server Admin Console tool from the Windows start menu.
     • From Mac OS and Linux: Run the Plastic SCM Server application.
2. Enter the required credentials.
   • If the server is just installed (no repositories created yet, except the default repository), you must set a password to access the administration console.
   • If the server is already setup but the administration console password is not set, then you must configure a password by using the plasticd adminpwd utility:
     Complete these steps:
     1. Open the command line as an administrator.
     2. Run the following command:
        • Windows: Plastic SCM installation directory\server\plasticd adminpwd --pwd=yourpassword
        • Linux: /opt/plasticscm5/server/plasticd adminpwd --pwd=yourpassword
        • Mac OS: /Applications/PlasticSCMServer.app/Contents/MacOS/plasticd adminpwd --pwd=yourpassword
     3. Navigate back to the Administration console and Refresh.
     4. Enter the configured password and Log in.
   • If an administration console password exists, just enter it!

Now, you can configure the required settings:

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

You can also access other relevant information:

• License - Configure everything about the Plastic SCM license: buy a Plastic license, enter the plasticd.lic license file, or configure the auto-renewal option.
• Support - Find solutions to your issues, contact the Plastic support team or send us your suggestions.
• Monitor - Monitor the Plastic Server activity live.

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

Configure the required values:

• TCP ports - By default, Plastic SCM uses 8087 as its TCP port number. If this default listening port changes, the Plastic SCM clients must be set up to this new port.
• SSL ports - SSL requires a certificate to encrypt communication. A self-signed certificate is generated the first time the Plastic SCM server starts, bound to the current hostname.
  To use your own certificate, enter the name of the certificate file and the required password to open the certificate file. If the password is wrong, the changes are not applied to the file.
  This certificate file must be located in the Plastic SCM server directory.
  Click Recreate self-signed cert to create a new self-signed certificate.
• UDT ports (Windows only) - Configure the UDT ports if you're working with high-speed networks.
• UDP discovery service - Let the Plastic SCM server be reacheable by the clients in the LAN.
• Override host name - Set an IP address if you need to override the Plastic server host name.

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

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

The Plastic client communicates security information to the server to be validated. The basic token sent from client to server is called SEID, short for SEcurity IDentifier. The mechanisms to be described are based on different ways to build the SEID plus different ways to obtain users.

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

• Local name
• Name + ID
• LDAP
• Active Directory
• User and password

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

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

Local name

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

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

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

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

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

How does the server obtain the user list?

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

How is the SEID built?

With the user name.

Name + ID

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

It is a straightforward way to prevent or complicate identity hijacking.

• Under Windows systems, the ID will be the SID of the user.
• Under-Unix based systems it will be the user id.

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

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

How does the server obtain the user list?

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

How is the SEID built?

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

LDAP

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

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

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

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

• Timeout for the LDAP requests
  The Plastic server can set a timeout for the LDAP requests (time in seconds). Use the LdapTimeoutSeconds setting. For example:

  <LdapTimeoutSeconds>10</LdapTimeoutSeconds>

• LDAP token expiration time
  You can also configure the LDAP token expiration time. Use the LdapTokenExpirationTimeSpan setting. You can set any expiration time using the format [d.]hh:mm:ss:

  <LdapTokenExpirationTimeSpan>05:00:00</LdapTokenExpirationTimeSpan>

  By default, the expiration time is 1 hour.
• Override for LDAP user filter
  
  Warning!
  This is considered an advanced-level feature to be used ideally after consultation with our Support team.
  To support LDAP setups that are not compatible with our default LDAP user search filters, you can use the limited ability to override the filter with a user-specified filter. Use the MemberNameFilterOverride setting.

  Enter the following to specify the filter override:

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

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

How does the server obtain the user list?

From the LDAP Server using a given user and password.

How is the SEID built?

The ID used by the concrete LDAP mechanism.

Active Directory

Using this configuration mechanism, the user list will be retrieved from the current Active Directory server. This authentication method requires the server to be running on Windows-based operating systems.

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

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

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

When user MADRID/ahernandez opens the GUI client and tries to create a child branch from main, they'll receive an access denied error.

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

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

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

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

How does the server obtain the user list?

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

How is the SEID built?

A Windows SID.

User and password

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

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

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

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

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

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

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

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

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

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

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

  

  To configure the login and password, use the Plastic SCM client configuration wizard as shown here:

  

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

  

• The User management tool from the command line:

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

  Replace %serverinstalldir% with your directory path.

  Learn how to use each command, by typing:

  %serverinstalldir%/plasticd umtool help <command_name>

  The umtool implements several commands:

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

  Here are some examples:

  Create a new user:	%serverinstalldir%/plasticd umtool cu maria
  Create a new group:	%serverinstalldir%/plasticd umtool cg developers
  Add a user to a group:	%serverinstalldir%/plasticd umtool addusertogroup maria developers

User/Password mode common questions

How does the server obtain the user list?

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

What does the authentication contain?

It contains the username and the encoded password.

Change the authentication mode

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

There are several backend technologies that Plastic supports: Jet, SQL Server, Firebird and others.

The Repository storage section lets the administrator:

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

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

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

Request processing

• Force client build number - Related to the ForceBuildNumberMatch parameter in the server.conf file.
  Use this parameter to mandate all clients upgrading to the same build number of the server. Optionally, you can set a minimum build number instead of mandating the same as the server.
  Read more about how this setting works.
• Abort request if socket closes - Related to the AbortRequestIfSocketCloses parameter in the server.conf file.
  When a client requests and closes the connection before the server finishes processing, the server will kill the request thread. This avoids long-running canceled requests to grow.
  Enabled by default on Windows, disabled on Linux due to instability issues.
• Transaction timeout - Related to the TransactionTimeout parameter in the server.conf file.
  This is the time (in seconds) before a long running transaction is automatically cancelled by the server.

Global security settings

• FIPS compliance - Related to the FIPSCompliant parameter in the server.conf file.
  Enable this parameter to mandate the use of FIPS compliant algorithms only.
  Requires that the Plastic clients to enable FIPS in their client.conf file. Otherwise, they won't be able to connect to this server.
• Enforce secured paths - Related to the SecuredPaths parameter in the server.conf file.
  If you use secured paths (permissions set to paths) and want to restrict users to access file revisions by item id if they don't have access to (using cm cat), then enable this setting.
  Suitable for high-security environments.
  Read more about how to use the Secured paths.

Worker Thread Pool

This is the thread pool that attends client requests. Each thread is reused for better performance. Only advanced users should tweak this value.

• Min threads - Related to the MinWorkerThreads parameter in the server.conf file.
• Max threads - Related to the MaxWorkerThreads parameter in the server.conf file.
  By default, the max number of threads matches the number of cores of the server.

Buffer pools

The buffer pools help reducing memory allocations by reusing pre-allocated buffers. Reducing allocations greatly increases performance under heavy load.

• Number of Tree buffers - Related to the TreeBufferPoolCount parameter in the server.conf file.
  Use this parameter to serialize directory trees. Under heavy load, this value should match the number of worker threads to avoid contention.
• Number of Blob buffers - Related to the BlobBufferPoolCount parameter in the server.conf file.
  Configure this value to read and write file data to the storage. These buffers reduce allocating 4MB blocks on every data transfer.
• Tree buffers size - Related to the TreeBufferSizeInMB parameter in the server.conf file.
  Set this size (in MB) to serialize directory trees. With large trees (+50k files and directories), increasing this number greatly helps reducing memory allocations.

Trigger variables

Use this section to add the custom global variables that are used in triggers.
Learn how triggers work and how to define them.

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

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

There are 5 auditing levels:

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

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

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

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

This is an example of an audit log file:

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

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

This section lets you configure the following settings:

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

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

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

License autorenewal configuration

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

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

Change license

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

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

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

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

• Performance:
• Performance - Counters:
• Performance - Active method calls:

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

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

The system performs the following operations:

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

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

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

• Manage your locking rules from the Plastic SCM Server Administration Console.
• Create or edit the lock.conf file.

Using the Plastic SCM Server Administration Console

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

Using the lock.conf file

1. Create or edit the lock.conf file on the server's directory with the following format:

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

   Where:

   • repname is one of the following:
     • The name of the repository where you want to perform exclusive checkouts by applying repository-specific rules.
     • The character * meaning "all repositories" to apply global rules to all the repositories.
   • server is the IP or the name of the lock server.
   • port is the port where the lock server is configured.
2. Configure the paths that will be exclusive checkouts. You can specify complete paths or patterns. Specify each rule in a new line. For example,

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

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

   Or, for example:

   rep:battlegame lockserver:
   *.png
   /assets/textures/model*.*
   

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

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

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

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

rep: * lockserver: 
# Audio and video formats
*.mkv
*.mp3
*.mp4
*.ogg
*.wav
*.wave

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

rep: doom3src lockserver: 
**/sys/*.xlib
*.def

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

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

/prj/Assets/Standard Assets/Toon Shading

/prj/Assets/Standard Assets/Tree Creator/Trees/Big*.meta

!/prj/Assets/Standard Assets/Tree Creator/Trees/BigTree_textures.meta

**/Library/*.prefs

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.

Plastic SCM supports several backend languages and technologies to store the repository data:

• Jet
• Firebird (Embedded)
• SQLite (Embedded)
• SQL Server Compact Edition (Embedded)
• PostgreSQL
• SQL Server (and SQL Server Express)
• MySQL

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

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

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

Plastic has a new storage for repositories:

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

There is support for 2 different workloads in Jet:

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

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

In terms of performance, Jet is about 10 to 40 times faster than SQLite and SQL Server in metadata reads and writes, which makes the server up to 3-5 times faster in operations like big checkins.

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

• Manage the Repository storage settings from the Plastic SCM Server Administration Console.
• Create or edit the jet.conf file.

Using the Plastic SCM Server Administration Console

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

Using the jet.conf file

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

1. basepath: Specify where the repositories data files will be stored.
   Warning! Changing this path won't perform any actions on disk. This means that you'll need to manually move the repository data files unless you'd like to discard the repositories.
2. Optionally, you can also configure the following parameters:
   • blobspath - Specify the path where Jet will store blobs. This way, Jet stores blobs and metadata in different paths. This is useful because it makes it possible to put metadata in faster and more expensive storage and blobs in slightly slower and cheaper ones (blobs will need much more storage than metadata).
   • prefix - Create prefixes for your database name.
   • suffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
   • datafilesize - Each repository contains one or more blob files to store versioned file contents. Once the maximum size (in GB) for a file is reached, a new file is created. This way, files don't grow too large for the underlying file system.
   • maxcachedtrees - Use this parameter to specify the maximum number of changesets whose directory trees are cached to reduce disk access. This value enables you to balance performance and memory usage.
   • maxcachessizeingb and maxcachessizefreepercent - Use these parameters to configure the maximum amount of memory used by caches. When the process reaches the memory limit, it starts to clean the caches of the least recently used repositories. The server will clean the configured percentage of the total number of caches.
     By default, there is no memory size limit. You need to configure it to enable this functionality. In that case, the default percentage to free will be 25% (not used unless a size limit is set).
     Bear in mind that the memory will not be released until the garbage collector (GC) runs the next full collection.

These are valid jet.conf files:

1. basepath=/mnt/metadata
   blobspath=/mnt/blobs
   maxcachedtrees=50
   datafilesize=4
   

2. basepath=c:\Users\maria\plasticdb
   prefix=zero
   suffix=
   

3. basepath=/mnt/data
   maxcachessizeingb=2
   maxcachessizefreepercent=30
   

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

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

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

• Manage the Repository storage settings from the Plastic SCM Server Administration Console.
• Create or edit the db.conf file.

Using the Plastic SCM Server Administration Console

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

Using the db.conf file

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

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

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

   <DbConfig>
     <ProviderName>firebird</ProviderName>
     <ConnectionString>ServerType=1;User=SYSDBA;Password=masterkey;Database={0};Pooling=true;connection lifetime=60;Charset=UNICODE_FSS;</ConnectionString>
     <DatabasePath>d:\plasticrep</DatabasePath>
   </DbConfig>
   

   You can use this db.conf file if you want to work with a Firebird Server installation instead of the embedded one. In this case, you only have to change the value of the ServerType parameter to assign a 0 and the DatabasePath.

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

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

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

   <DbConfig>
     <ProviderName>sqlserverce</ProviderName>
       <ConnectionString>DataSource={0};Persist Security Info=False;Max Database Size=4090;Max Buffer Size = 4096;Password=;</ConnectionString>
     <DatabasePath>d:\plasticrep</DatabasePath>
   </DbConfig>
   

4. You can also configure the following parameters:
   • DatabasePrefix - You can create prefixes for your database.
     Here is a SQLite db.conf example using this option:

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

     Or you can use the Plastic command line as follows: plasticd --console --dbprefix=production_databases_
   • DatabaseSuffix - The database suffix is a string appended to the name of every database created by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same database backend, so they don't interfere with each other.
   • CommandTimeout - Set the time (in seconds) available for each database command.
   • MaxCachedTrees - Use this parameter to specify the maximun number of changesets whose directory trees are cached to reduce disk access. This value allows you to balance performance and memory usage.
   • FullTreeRevisionsLoad - Use this value to specify what is the maximum number of revisions to read when loading the changeset trees. This setting sets the limit to decide when reading the full table is faster, instead of doing individual queries.
   • CommentLimit - You can also set the maximum lenght for the comment strings in the database.
   • IsolationLevel - Override the ACID isolation level setting for the configured embedded database backend.
     Important! Plastic SCM server already sets the ACID level for the underlying database backend that best performs for each database. It is recommended not to touch this setting on your own. For further info, ask Plastic SCM support at support@plasticscm.com.
     These are the possible values: Chaos, ReadCommitted, ReadUncommitted, RepeatableRead, Serializable or Snapshot.

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

• Manage the Repository storage settings from the Plastic SCM Server Administration Console.
• Create or edit the db.conf file.

Using the Plastic SCM Server Administration Console

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

Using the db.conf file

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

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

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

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

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

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

• Manage the Repository storage settings from the Plastic SCM Server Administration Console.
• Create or edit the db.conf file.

Using the Plastic SCM Server Administration Console

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

Using the db.conf file

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

1. Enter the sqlserver value for the ProviderName key.
2. Specify the ConnectionString - In general, you only need to fill in the database Server name, the User ID and the Pwd values to connect to SQL Server. But, don't change the DATABASE={0}; key.
   Note:Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

   This is a valid db.conf file configured with SQL Server Express where the connection string use built-in SQL Server authentication which is telling Plastic to use a given user and password:

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

   To use built-in Windows authentication, you need to replace the user and password values with the trusted_connection=yes key:

   <DbConfig>
     <ProviderName>sqlserver</ProviderName>
     <ConnectionString>
         SERVER=beardtongue\SQLEXPRESS;trusted_connection=yes;DATABASE={0};
     </ConnectionString>
   </DbConfig>
   

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

Database creation command

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

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

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:

• Multiple commands. Must be separated with ";" and specified in a single line. You can't use the "GO" clause:

  <DatabaseCreationCommands>
    CREATE DATABASE @PlasticDatabase ON PRIMARY
    (NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100) 
    LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100) 
    COLLATE @PlasticDefaultCollation;ALTER DATABASE @PlasticDatabase SET PAGE_VERIFY CHECKSUM;ALTER DATABASE @PlasticDatabase SET ANSI_WARNINGS OFF
  </DatabaseCreationCommands>
  

• Change database file location and log names and paths:

  <DatabaseCreationCommands>
    CREATE DATABASE @PlasticDatabase ON PRIMARY
    (NAME=@PlasticDatabase, FILENAME='C:/databases/dbs/@PlasticDatabase.db', SIZE=10, FILEGROWTH=100) 
    LOG ON (NAME=PlasticLog_@PlasticDatabase, FILENAME='C:/databases/logs/@PlasticDatabase.log', SIZE=10, FILEGROWTH=100) 
    COLLATE @PlasticDefaultCollation 
  </DatabaseCreationCommands>
  

• Change size parameters or collation:

  <DatabaseCreationCommands>
    CREATE DATABASE @PlasticDatabase ON PRIMARY
    (NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=100, FILEGROWTH=50) 
    LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=100, FILEGROWTH=50) 
    COLLATE SQL_Latin1_General_CP1_CS_AS
  </DatabaseCreationCommands>
  

Troubleshooting the new connection

Setting up a SQL Server backend should be really easy, but if problems show up, remember to check the loader.log.txt file under the server folder in the Plastic SCM installation directory. This file contains the Plastic server log. The most common connection problems to check are:

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

Configure SQL Server memory usage

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

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

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

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

This limits it to 300Mb.

Check out the following links for more information:

• Effects of min and max server memory
• Server Memory Options
• Configuring SQL Server memory settings
• sp_configure: Limit SQL Server memory usage

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

• Manage the Repository storage settings from the Plastic SCM Server Administration Console.
• Create or edit the db.conf file.

Using the Plastic SCM Server Administration Console

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

Using the db.conf file

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

1. Enter the mysql value for the ProviderName key.
2. Specify the ConnectionString - In general, you only need to fill in the database Server name, the User ID and the Password values to connect to MySQL. But, don't change the Database={0}; key.
   Note:Plastic SCM will need to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.

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

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

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

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

How to fine tune MySQL for Plastic SCM

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

Hardware remark

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

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

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

• The innodb_buffer_pool_size should be around half of the memory of your server machine. This is the most important value. Note that due to a limitation in MySQL, this value should be maximum 4GB (more details here):

  innodb_buffer_pool_size = 2G

• innodb_additional_mem_pool_size should be a 5% of the innodb_buffer_pool_size:

  innodb_additional_mem_pool_size = 100M

• Set innodb_log_file_size to 25% of buffer pool size:

  innodb_log_file_size = 500M

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

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

  innodb_log_buffer_size = 40M

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

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

max_allowed_packet = 10M

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

How to backup the embedded databases

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

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

Steps to backup:

1. Stop the Plastic server.
2. Backup the database files. You can find them in the server installation directory or in the database path specified during the database setup. The database files are repositories.plastic.* and rep_**.plastic.*.
3. Start the Plastic server again.
See how to stop / start the Plastic SCM server on your Windows, Linux or Mac OS system.

Restore embedded databases

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

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

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

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

Cold copy

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

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

Backup

1. Stop the Plastic server.
2. Backup the Jet content. You can find it in the basepath parameter specified during the database setup (check the jet.conf file).
3. Start the Plastic server again.

Restore

1. Stop the Plastic server.
2. Restore all the backup files to the path you configured (remember to set the right setting for the path in the jet.conf file).
3. Start the Plastic server again.

Hot copy

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

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

Backup

1. Set the Plastic server to read-only mode ( cm admin readonly enter ).
2. Backup the Jet content. You can find it in the basepath parameter specified during the database setup (check the jet.conf file).
3. Set the Plastic server to normal mode.

Restore

1. Set the Plastic server to read-only mode.
2. Restore all the backup files to the path you configured (remember to set the right setting for the path in the jet.conf file).
3. Set the Plastic server to normal mode.

Tools

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

Rdiff-backup - Cold copy example

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

1. Install rdiff-backup 1.2.8 in the server.
2. Configure autofs to auto-mount backup NFS folder in the /cifs/backup folder.
3. Add a cron job which is executed everyday at 3.30AM local time. This is the script job:

   #!/bin/bash
   export weekNumber='date +%V'
   export year='date +%Y'
   export today='date +%Y%m%d'
   export lastActinLogFile="/root/backup_jet.log"
   
   export dirName="week_$weekNumber"
   export baseBackupDstLocation="/cifs/backup/backups/myserver_jet"
   export backupFinalDstLocation="$baseBackupDstLocation/$year/$dirName"
   export weekIncrementsTarGzDstFile=$backupFinalDstLocation/myserver_ddbb_jetfs.rdiff-backup_$year_week_$weekNumber.tar.gz
   
   #rdiff-backup source and destination params
   export srcJetFolder="/home/mydata/jet"
   #export rdiffBackupWeekIncrementsAuxDir="/home/mydata/local_jet_backup_rsync"
   export rdiffBackupWeekIncrementsAuxDir="$baseBackupDstLocation/tmp"
   
   echo "starting daily backup $today on dst dir: $backupFinalDstLocation" > $lastActionLogFile
   
   #if we're starting a new week, reset the increments dst dir so rdiff-backup will start a fresh backup from scratch
   if [ ! -d "$backupFinalDstLocation" ]; then
     mkdir -p $backupFinalDstLocation
     #reset weekly backup local folder
     rm -rf $rdiffBackupWeekIncrementsAuxDir
   fi
   
   echo "about to stop and targz $today" > $lastActionLogFile
   /usr/sbin/plasticsd stop
   sleep 20
   rdiff-backup $srcJetFolder $rdiffBackupWeekIncrementsAuxDir
   rm $weekIncrementsTarGzDstFile
   tar cvzf $weekIncrementsTarGzDstFile  $rdiffBackupWeekIncrementsAuxDir
   sleep 20
   /usr/sbin/plasticsd start
   echo "done! $today" > $lastActionLogFile
   

How it works:

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

These are the commands used to:

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

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

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

Rdiff-backup - Hot copy example

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

The script will be something like this:

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

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

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

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

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

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

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

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

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

A breakdown of the archive example above:

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

You can archive several revisions by specifying them one after the other in the same command. To get further information about this command, type on a command line cm help archive.

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

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

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

This file can be placed in two locations:

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

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

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

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

It is possible to save archived revisions back into the database, so they archives can be safely deleted. From there, the database will be used to get the data.

Example:

A break down of the example above:

• This command will restore the revision 0 of the main branch of the file mybigfile.tar into the database, and the archives of that revision will no longer be used.
• The external storage location must be available at the moment of the revision restoration, and an externaldata.conf file must be available.

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

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

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

• true - Exact build number matching is required. It means that any client or server connecting to this server must run exactly the same version.
• false - No version match required. This is the default.
• number - The server will reject any connections from callers running a version with a build number smaller than number.

  For example:

  <ForceBuildNumberMatch>800</ForceBuildNumberMatch>
  

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

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

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

Windows

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

1. makecert (Makecert.exe) is a command-line CryptoAPI tool that creates an X.509 certificate signed by a system test root key or another specified key. The certificate binds a certificate name to the public part of the key pair. The certificate is saved to a file, a system certificate store, or both.
   Read more about MakeCert.
2. pvk2pfx (Pvk2Pfx.exe) is a command-line tool that transfers public key and private key information contained in .spc, .cer, and .pvk files to a Personal Information Exchange (.pfx) file.
   Read more about Pvk2Pfx.

Linux and Mac

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

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

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

Windows

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

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

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

   Note: Name the .pvk, .cer and .pfx files with the machine hostname where the Plastic SCM server is installed. If you do not use the machine hostname, you will continuously receive warnings saying that the certificate doesn't match the Plastic SCM server hostname. In the example above, the server is called Tardis, so the resulting output files are labeled as Tardis.pvk, Tardis.cer and Tardis.pfx.

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

Linux and Mac

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

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

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

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

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

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

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

Windows

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

Linux and Mac

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

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

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

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

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

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

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

]

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

• Using the Plastic SCM GUI.
• Using the CLI that will add a key to the certificate store.
• Installing it manually without using the Plastic SCM client.

Plastic SCM GUI

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

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

Plastic SCM Command Line Interface (CLI)

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

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

Manual installation

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

Manually install the certificate on a Windows, Linux or Mac OS based server:

Windows

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

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

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

5. Click Finish to install the certificate:
   

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

MacOS

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

• For MacOS use this directory path:

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

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

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

alias1 alias2

With this file, the client will know what connection use at any given time.

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

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

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

The content of the serveralias.conf file will be:

localserver.office-network.com:8084 ssl://plastic.external-network.com:8090

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

• Checkin
• Fast-Import
• Sync replication

A new configuration file called compression.conf on the Plastic SCM client lets you 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".

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

none .jpg
zip .txt

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

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

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

If both files exist, their rules will be combined.

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

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

For instance:

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

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

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

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

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

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

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

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

You can set a global file configuration in the server. This way, all the Plastic clients have the same settings by default. This means that the configuration files will consult the global configuration and the local (workspace relative) and main (client relative) files.

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

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

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

• Global configuration for a specific repository: /repname/configuration_file.conf.
  For example, /doomsrc/ignore.conf.
• Global configuration for all the repositories: /allrepos/configuration_file.conf.
  For example, /allrepos/filetypes.conf.

How the global configuration is loaded

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

How to set up the global configuration

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

The repository must have the correct structure as seen previouslys. In the following example, the repository corefx will have a cloaked.conf configuration file and the rest of the repositories will be have a hidden_changes.conf:

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

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

How to create a branchexplorer.conf global configuration file

1. Navigate to your Plastic SCM GUI and set your Branch Explorer configuration preferences.
2. Find the generated configuration file in:
   • Windows: C:\Users\user\AppData\Local\plastic4\branchexplorer.cfg
   • Linux and Mac OS: $HOME/.plastic4/branchexplorer.conf
3. Copy the resulting file to the global configuration repository under the allrepos folder.

What can be globally configured?

• Only the filters and conditional format rules can be globally configured.
• The user-specific configuration, such as displaying full branch names, merge links, the start, and end date, will always prevail from the local configuration file. If these settings are set globally, they will be ignored during the "merge" of global and local rules.

How does it work?

A global branchexplorer.conf file looks like this:

[Default]
filters.conditional.numrules=1
filters.conditional.rule0.branches_query=attribute = 'status' and attrvalue = 'RESOLVED'
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=exclusion_rule

A local branchexplorer.conf contains user-specific information too:

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

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

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

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

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

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

Reasons for using the transformable workspaces:

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

A transformable workspace is configured through the transformer rules.

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

Two kind of rules are currently supported:

Move rules

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

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

Examples:

mv /Game /TnT/Game
mv /src/libs/nh3 /nh3

Remove rules

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

Examples:

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

Transformer rules - How to use them

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

1. Imagine the following workspace. It'll be transformed by executing the following actions:
   • Move the irix folder to the root (requirement for a correct build).
   • Remove the armory.afdesign big file.
   

2. Create the plastic.transformerrules file inside the workspace directory .plastic with the following rules:

   mv /lcc/mips/irix /irix
   rm /art/armory.afdesign
   

   Verified that there's no pending changes.

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

   The moved directory now has the Directory / Transformed type.

Transformer rules - Current status

Not supported scenarios with transformer rules

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

Known issues

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

Restrictions

• The xlinks cannot be moved by transformer rules.

  Example:

  mv /src/xlink /xlink
  

• The tranformer rules cannot modify an already applied rule.

  Example:

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

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

  Example:

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

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

  Example:

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

• The transformed moved nodes cannot be moved again.

  Example:

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

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

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

The cm admin readonly command allows you to:

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

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

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

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

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

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

• They only allow to merge some branches if they are reviewed.
• They only allow merges from certain branches.
• They only allow merges from parent or child branches.

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

   A merge rule defines:

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

       You can see in the how filtering workssection.

     A merge rule example to clarify these concepts:

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

Definition

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

Example:

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

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

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

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

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

Definition

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

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

Example:

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

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

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

Definition

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

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

Example

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

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

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

Definition

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

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

Example:

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

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

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

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

• Filtering by name: Use the branchNames key to specify the branch names. For example:

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

• Filtering by attribute: Use the branchesWithAttribute key to filter by attribute by specifying the attribute name and/or a value. For example:

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

• Filtering by name and attribute: Combine the above filters to filter by branch name and attribute. For example:

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

  or:

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

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

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

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

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

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

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

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

• mergerules.conf:

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

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

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

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

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

  

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

  

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

The benefits of the Plastic .NET Core server:

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

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

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

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

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

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

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

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

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

Suppose you have the following network.conf file:

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

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

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

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

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

March 17, 2022

March 7, 2022

March 3, 2022

February 16, 2022

November 4, 2021

October 19, 2020

September 14, 2020

September 11, 2020

September 10, 2020

September 9, 2020

August 12, 2020

June 19, 2020

June 18, 2020

May 25, 2020

March 19, 2020

December 23, 2019

October 31, 2019

October 24, 2019

October 24, 2019

• We edited the documentation of the db.conf configuration file to specify that this file is related to the following database backends or repository storages: Firebird, SQLite, SQL Server CE, PosrgreSQL, SQL Server and MySQL.
• We also added documentation about the jet.conf configuration file related to the Jet repository storage .

October 2, 2019

March 22, 2019

July 24, 2018

May 8, 2018

February 16, 2018

January 29, 2018

November 21, 2017

October 24, 2017

September 26, 2017

September 13, 2017

July 4, 2017

June 09, 2017

June 01, 2017

May 19, 2017

May 12, 2017

February 24, 2017

February 21, 2017

Jan 24, 2017

December 17, 2016

July 4, 2016

June 27, 2016

May 10, 2016

November 5, 2015

September 7, 2015

August 7, 2015

July 22, 2015

May 27, 2015

March 27, 2015

March 20, 2015

March 18, 2015

March 18, 2015

February 25, 2015