Plastic SCM Administrator's guide
Chapter 1: Introduction
Plastic SCM
Plastic SCM is a Software Configuration Management system designed to handle software development teams of all sizes.
Plastic SCM provides high-end SCM capabilities without imposing restrictions associated with high-end
systems like complex installation, operation, and administration.
This guide assumes that the reader is familiar with the basic SCM concepts, with basic operating system usage
through the command line and basic system administration.
The guide will show both system administrators and SCM managers how to install the SCM system, create
repositories, workspaces and make backups.
Components
Plastic SCM uses a client/server architecture, divided into the following components:
-
The Server: responsible for storing project information and managing client access.
-
The Clients: run on the developers' machines and are responsible for communicating user operations to
the server. The supported clients are:
-
Command Line Interface (CLI): Provides access to Plastic SCM operations on the operating system
shell. Very useful for task automation.
-
Graphical User Interface (GUI): provides access to Plastic SCM operations using a graphics-oriented
interface. It gives visual diagrams not available in the command line.
-
Integrations with Integrated Development Environments such as:
-
Visual Studio integration: provides access to commonly used operations like checkout/checkin
inside Visual Studio, and full access to GUI views like Branch Explorer, labels
and checkouts.
-
Eclipse integration: provides access to commonly used operations like checkout/checkin from
within the Eclipse development environment.
-
IntelliJ integration: provides access to the commonly used operations from the IDEA IDE.
-
JDeveloper.
-
Build Management tools integrations for the following products:
- Cruise Control
- Final Builder
-
Integrations with task and issue management tools like:
- Atlassian JIRA
- TechExcel DevTrack
- RallyDev
- Axosoft (formerly OnTime)
- Version One
- Fog Creek's FogBugz
- Trac
- Bugzilla
- Mantis
Chapter 2: Minimum requirements
- Windows - The .NET Framework 4.6 is required.
- Windows:
- All Windows
- Windows XP, Windows 2000, and Window Vista no supported due to .NET restrictions
- Linux: The following distros are supported (more info here)
- Debian
- Ubuntu
- Fedora
- Red Hat Enterprise
- CentOS
- OpenSUSE
- Mac OS:
- Mac OS Mountain Lion (10.8) and above
Disk usage largely depends on your repository size.
RAM and CPU depend on the concurrent load that the server needs to handle. Get further information about how the Plastic SCM server is capable of handling high loads.
Chapter 3: Plastic SCM installation
Prerequisites
The Plastic SCM server is installed as a Windows service or as a daemon in Linux / Mac. Administrative privileges
are required for this step to succeed during the installation of the server component.
Server and Client installation
Install Plastic SCM on your Windows, Linux or Mac OS
system.
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.
|
The Plastic SCM Server is now configured with the default values. Some of them are the following:
- Plastic SCM Edition - Team.
- User authentication mode - Local name.
- Database backend - Jet.
If you need to change this configuration, launch the
webadmin.
To install Plastic SCM on Linux, complete the instructions for
your Linux distro.
Important: Remember to run the commands as sudo.
The Plastic SCM Server is now configured with the default values. Some of them are the following:
- Plastic SCM Edition - Team.
- User authentication mode - Local name.
- Database backend - Jet.
If you need to change this configuration, launch the
webadmin.
If you're installing Plastic for the first time, you must complete the
client configuration before using Plastic.
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.
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. |
 |
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. |
 |
The Plastic SCM Server is now configured with the default values. Some of them are the following:
- Plastic SCM Edition - Team.
- User authentication mode - Local name.
- Database backend - Jet.
If you need to change this configuration, launch the
webadmin.
If you're installing Plastic for the first time, you must complete the
client configuration before using Plastic.
Server configuration
After installing the Plastic SCM server for the first time, the server is configured with the default values.
The Plastic Administrator can configure the server applying the new settings or configurations required
(network, license, authentication, and so on).
Complete one of these steps to configure the Plastic SCM server.
-
Launch the webadmin - Plastic SCM Server
Administration Console - the cross-platform admin tool.
or
-
Open a command line:
-
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
-
Configure the required settings:
Client configuration
Each time a new client is installed on a developer's machine, it must be configured to connect to a Plastic SCM
server. This can be quickly done using the Client configuration wizard.
Read how to configure the Plastic SCM client in your Windows, Linux, or Mac OS system.
To run the
Client configuration wizard from the command line, use the following commands:
- cm configure - Configure the Plastic SCM client through the command line. Read the command line section to learn how this configuration
works.
- plastic --configure - Open the Plastic SCM client configuration GUI.
The
Client configuration wizard GUI can also be run from the Plastic SCM startup menu entry.
Using the Client configuration wizard you can configure:
- 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.
To run the
Client configuration wizard from the command line, use the following command:
- cm configure - Configure the Plastic SCM client. Read the command line section to learn how this configuration works.
- plasticgui --configure - Open the Plastic SCM client configuration GUI.
The
Client configuration wizard GUI can also be run by right-clicking the
Plastic
SCM application and selecting
Configure Plastic SCM.
Using the Client configuration wizard the user can configure:
-
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.
To run the
Client configuration wizard from the command line, use the following command:
- cm configure - Configure the Plastic SCM client through the command line. Read the command line section to learn how this configuration
works.
- plasticgui --configure - Open the Plastic SCM client configuration GUI. See the steps below.
The
Client configuration wizard GUI can also be run by double-clicking the
macplastic application.
Using the Client configuration wizard the user can configure:
-
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.
- 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.
This section describes how to configure the Plastic SCM client to use a specific merge or diff tool for specific
types of files.
Note: Plastic SCM includes its own 3-way merge and diff tool, so this step is not required in
the default setup.
The configuration of the merge and differences tools are defined in the client.conf
file.
It allows specifying what tools have to be used for different types of files through a set of rules.
A rule contains information about the type of file (binary or text) or the file extension to which
this rule applies.
The default rules for the merge tool are:
- FileType:
- Indicates the types of files the rule will apply to. For example, they can be TextFile for files identified as
text by
Plastic SCM or BinaryFile for files identified as binary by Plastic SCM.
- FileExtensions:
- Indicates file extensions or types of files on which the rule is applied; if there is more than one extension
for
the same rule, they would be separated by ";." If the rule is used for every extension, "*" would be used.
- Tools:
-
Different merge tools to be used on a specific file. If there is more than one tool, they are executed in order
until one of them gives a result; only the first tool is used in the differences. These tools must
have every mandatory parameter using the variables given, replaced by the system value during execution.
For the system to use a specific value for a rule instead of a variable, that value would need to be set. The
given
variables are the following:
- @basefile
- path containing the merge common ancestor.
- @basesymbolic
- name shown on the tool to refer to the base file. Usually the spec revision or the disc file if
loaded.
- @basehash
- common ancestor content hash.
- @sourcefile
- path containing the merge source file.
- @sourcesymbolic
- name shown on the tool to refer to the merge source file. Usually the spec revision or the disc file
if loaded.
- @sourcehash
- merge source content hash.
- @destinationfile
- path containing the merge destination file, the location of the element in the workspace.
- @destinationhash
- merge destination content hash.
- @output
- file containing the merge result.
- @filetype
- type of file used for the syntax highlight.
- @comparationmethod
- comparison method used.
- @fileencoding
- file encoding.
- @mergetype
- type of merge used.
Important! The rules are executed in order, so the less restrictive ones must be at the bottom of
the list. A catch-all rule for the file extension "*" is normally the latest.
The example below shows using an additional rule for a single type of file considered binary (.scs). For the file
to be considered as text and given fixed parameters, the type of merge should be automatic (if one of the contributors
has submitted changes and the file codification is Unicode):
<MergeTools>
<MergeToolData>
<FileType>enTextFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>mergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype"</string>
</Tools>
</MergeToolData>
<MergeToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>.scs</FileExtensions>
<Tools>
<string>"mergetool.exe" -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="unicode" -m="onlyone"</string>
</Tools>
</MergeToolData>
<MergeToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>binmergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -m="@mergetype"</string>
</Tools>
</MergeToolData>
</MergeTools>
In the case of the different tools, rules are built similarly, but there are fewer variables. For example, to add a
rule to calculate differences on a binary file (.scs) as a text file with the Unicode format, you'd write the
following:
<DiffTools>
<DiffToolData>
<FileType>enTextFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>mergetool -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod" -e="@fileencoding"</string>
</Tools>
</DiffToolData>
<DiffToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>.scs</FileExtensions>
<Tools>
<string>"mergetool.exe" -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod" -e="unicode" </string>
</Tools>
</DiffToolData>
<DiffToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>binmergetool -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod" -e="@fileencoding"</string>
</Tools>
</DiffToolData>
</DiffTools>
Start working with Plastic SCM
Read how to start working with Plastic SCM in your Windows,
Linux or Mac OS
system.
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.
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.
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.
Server startup
Plastic SCM server starts automatically on server boot, and after the installation process is finished. But it can be
stopped, started, or restarted manually.
Read how to start/stop/restart the Plastic SCM server in your Windows, Linux, or Mac OS system.
Use one of the following methods:
- 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.
- Run the command line and type the following:
plasticd {--start |--stop | --restart}
To start and stop the Plastic SCM service on Linux systems, use the plasticsd script as
sudo. This script is located in the following locations:
- In the
/etc/init.d
directory to help with automatic start on system boot.
- In the server installation directory,
/opt/plasticscm5/server
, by default.
- Or you can also use it through the service command.
This script has the following options:
plasticsd {start | stop | restart | status}
For example:
/etc/init.d/plasticsd start
/opt/plasticscm5/server/plasticsd stop
service plasticsd restart
Once the Plastic SCM server has started, a default repository is created to ease the initial
system usage.
Check whether the server is up and running by running one of the previous commands with the status
option:
/etc/init.d/plasticsd status
The command will return the running process ID of the server.
Another way to check the server status is by looking at the repository list: open a console
and type cm lrep servername:port. It will list all the repositories on server
servername:port
.
To start/stop the Plastic server daemon, you will need to use the launchctl Mac command as sudo:
- To start the Plastic server, run the following command:
sudo launchctl load /Library/LaunchDaemons/com.codicesoftware.plasticscm.server.plist
- Use this command to stop the Plastic server:
sudo launchctl unload /Library/LaunchDaemons/com.codicesoftware.plasticscm.server.plist
Run Plastic SCM
Select one of the following methods to run the Plastic SCM client in Windows, Linux or Mac OS.
-
Open the Plastic SCM application from the startup menu:
Or:
- Type plastic in a command line interface window.
-
Open the Plastic SCM application from the Applications window:
Or:
- Type plasticgui in a command line interface window.
-
Open the Plastic SCM application from the Applications window:
Or:
- Type open /Applications/plasticscm.app in a command line interface window.
Chapter 4: Using a proxy server
Plastic SCM supports the idea of having a Proxy server to support balancing the traffic between the two machines:
For example, a remote server and the local proxy machine. This proxy can be installed with minimum
operating resources. No database backend is needed to run it, making it pretty easy to set up. It can be configured
as a daemon, Windows service, or started manually from the command line.
The cached data will always be read-only, meaning that only checked-in revision data is cached on the proxies. Since
checked-in revisions never change, it's safe and simple to cache them.
The Proxy server will start caching files from the repository server as data is requested from clients. Once cached
revision data stays on the proxy, so that future requests to the same revisions will be downloaded from the proxy
machine instead of the remote repository server.
The proxy server will also keep the most used revisions in memory for improved performance. The administrator
can configure the maximum amount of memory to be used.
Benefits of using a Proxy with Plastic SCM:
- The server will act as a data cache. No other data or metadata besides revision information will be stored.
- All cached data will be stored on a configurable disk directory for simplified administration.
- Data transmission between the proxy server, repository server, and client will use the same data exchange
protocol used by Plastic SCM, exchanging data chunks of 4Mb max size.
The following is an example of a configuration using a proxy server:
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.
Starting the Plastic Proxy
The Plastic Proxy is bundled as a subcommand of Plastic SCM Server executable file.
You can start the Plastic Proxy by running plasticd proxy.
(No arguments required.)
Managing the Plastic Proxy service on Windows
These operations are available for Windows systems only.
These are the operations available with the plasticd proxy subcommand:
-
Install the Plastic Proxy service:
plasticd proxy --installservice
This command install the service but it doesn't start it up.
-
Start the Plastic Proxy service:
plasticd proxy --start
-
Stop the Plastic Proxy service:
plasticd proxy --stop
-
Restart the Plastic Proxy service:
plasticd proxy --restart
-
Print the status of the Plastic Proxy service:
plasticd proxy --status
-
Stop and uninstall the Plastic Proxy service:
plasticd proxy --uninstallservice
Configuring the Proxy server
For the proper way of working of the proxy server, remember creating a
plasticcached.network.conf
configuration file in
the Plastic SCM Server installation directory.
This is an example of a plasticcached.network.conf
file:
[
{
"port": 8085,
"type": "tcp",
"security": "none"
}
]
You can find a copy of this example configuration file in the
config_samples
folder in the Plastic SCM Server
installation directory.
Configuring the clients
The Plastic SCM clients now need to configure a proxy server. To do this,
open the Preferences dialog.
Check the Use a Proxy server box and enter
the proxy server name in server:port format. By default, the
port is 8085.
You can click Connect to verify the connection is
ready.
That's it! When revisions are downloaded from the server, the client will
ask the proxy and download them from there instead of the server (if the data
is cached).
Support to cache data from Plastic Cloud
To cache data from the cloud, install a Proxy (and your client too if you use encrypted data in the Cloud) and start
caching data.
Disk cache limit
The proxy can limit the size of its on-disk cache.
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.
-
The Proxy maintains an LRU (Least Recently Used list) and updates it on every data access.
-
Every 10 minutes, it checks if the total cache size is bigger than the value configured. If the maximum size is
exceeded, the Proxy retrieves the least recently used entries and removes them from the disk.
-
Every 3 minutes, the Proxy saves the LRU info to the disk, to
proxy-data-path/proxy-lru.dat
.
The Proxy also writes data on shutdown.
-
On startup and every 8 hours, the Proxy checks if it needs to walk the entire cache directory to rebuild the
LRU and recover from possible inconsistencies. While the check runs every 8 hours, a rebuild only happens once
every 3 days. The Proxy stores the date of the last rebuild under
proxy-data-path/proxy-last-cache-walk.dat
.
proxy-data-path
is the directory where the proxy is configured to store the cache. For
existing Proxy installations, the new version will rebuild the cache on the fly.
During the startup of the Proxy, you'll see:
INFO LRU - Walking the disk to build the LRU (least recently used). c:\plastic\proxydata
INFO LRU - Last LRU rebuild from disk happened less than 3 days ago. Skipping. 11/04/2019 16:50:00
INFO Daemon - Load LRU info from c:\plastic\proxydata\proxy-lru.dat
INFO Daemon - LRU info loaded in 656 ms. 107299 entries. 5.89 Gb total in cache
You can see how the Proxy skips the rebuild and how it loaded 107k entries to the LRU.
Then, every 3 minutes, and during shutdown:
INFO Daemon - Save LRU to c:\plastic\proxydata\proxy-lru.dat
INFO Daemon - LRU info saved in 312 ms. 107299 entries. 5.89 Gb total in cache
And during a clean up:
INFO Daemon - Cleaning up 0.69 Gb (17564 entries) of cached data to enforce the 5.20 Gb limit
INFO Daemon - Cleaned up 0.69 (17564 entries) Gb in 5110 ms
INFO Daemon - Save LRU to c:\plastic\proxydata\proxy-lru.dat
INFO Daemon - LRU info saved in 265 ms. 89735 entries. 5.20 Gb total in cache
Monitor free space
The Plastic Proxy can monitor free space on the disk and clean up the cache to avoid running out of space.
You'll see something as follows in the log when it runs out of space:
INFO Daemon - Disk is running out of space. 5.78 Gb available. Will delete 1.15 Gb from cache
INFO Daemon - Cleaning up 1.15 Gb (9576 entries)
INFO Daemon - Cleaned up 1.15 Gb (9576 entries) in 2578 ms
And, if there is enough room (twice the size of the cache) then something as follows:
INFO Daemon - Disk still has enough space: 19.53 Gb available.
More info in the log file
The log shows the caller's IP and the user name. This information appears in the log line after the
GetObjectsData
call.
The log is as follows:
Proxy - Request: 39. Type: downl. Files requested: 10. Cache misses: 10. Total time: 16 ms. Downloaded: 3.78 Mb from default@localhost:8084. Total returned: 3.78 Mb. IP: 127.0.0.1. User: 'pablo'.
Chapter 5: Creating and managing repositories
Repositories are the central data storage in the Plastic SCM system. They store the information for all the objects
in the system.
Creating a new repository
An empty repository named default is created on the first server startup if no other repository exists
yet. You're all set!
From the administrator's point of view, it can be fun to create repositories using the command line interface. This
is achieved in with the cm repository create or cm repo mk commands:
cm repo mk PlasticServer:8087 NewRepository
Where:
- PlasticServer is the hostname or IP address of the Plastic SCM server.
- 8087 is the TCP port where the server is listening.
- NewRepository is the name of the new repository to be created.
Repositories can also be created on the Plastic SCM GUI client by opening the repositories view and clicking on Create new repository button.
In the new repository dialog, you can enter the repository name and the Plastic SCM server where it will be
created.
Listing available repositories
To view available repositories, open the command line or GUI client. Use
cm listrepositories or cm lrep:
cm lrep backyard:8087
Output:
default@backyard:8087
doom3scr@backyard:8087
The figure below shows the repositories view on the GUI tool, accessible from the Repositories view menu.
Archiving repositories
Repositories that are no longer used can be disconnected from the server and archived on offline storage like DVD or
tapes, leaving free space for active repositories. These repositories can be later reconnected if they need to be
used.
To archive a repository, the removerepository command is used, providing a repository
specification.
First, list all repositories:
C:\scm3>cm lrep localhost:8087 --format=TABLE
1 default localhost:8087
3 myproject localhost:8087
5 nasa localhost:8087
Get the number in the first column for your repository: "the repository index." In the example above,
archive repository 3 will be removed (myproject). This number will be used later to identify the file to backup.
Next is removing the repository:
cm removerepository myproject@localhost:8087
This command has two internal effects (important to note for later reconnection).
- It removes the repository from the list of registered repositories available to be used in workspaces.
- It removes the repository from the list of available repositories.
Note: the removerepository command does not delete the database in the
database backend.
The repository database in the physical database backend name follows this pattern:
rep_xx.plastic
The file for myproject repository, in the previous sample, will be
rep_3.plastic
You can locate the database with the name in your database backend and back it up using the tool of your choice.
After you have backed it up, you can delete the database from your backend if desired.
Reconnecting archived repositories
To reconnect an archived repository, first, get a list of the current repositories (this might be different from the
list
of reps found when it was archived):
C:\scm3>cm lrep localhost:8087 --format=TABLE
1 default localhost:8087
3 excel localhost:8087
4 word localhost:8087
5 PW point localhost:8087
6 access localhost:8087
7 outlook localhost:8087
Several repositories have appeared/created in the example above since myproject was archived, which was
previously
number 3. Choose a free repository number not used in the list (next one is 8, but you can
choose any other). Rename your database rep_3.plastic to rep_8.plastic. For instance, for
an embedded Firebird database this means just renaming the database file on disk:
move rep_3.plastic.fdb rep_8.plastic.fdb
To reconnect, add the repository to the list of available repositories using the cm
addrepository command:
cm addrepository rep_8 myproject localhost:8084
- The first argument is the database name (rep_8), without the .plastic.fdb extension.
- The second argument is the name of the repository (myproject). This must be unique
in the list of available repositories and the name that Plastic SCM users will see.
- The last argument is the repository server IP:TCP PORT (localhost:8084), where the
repository will be connected.
Chapter 6: webadmin - Server configuration and administration
Accessing the webadmin
Once the Plastic SCM server is installed for the first time, it is configured with the default values. The
server is ready, and the Plastic clients can connect and run!
The Plastic SCM Server administration console is a cross-platform server configuration tool UI that lets the Plastic
administrator configure those server settings to suit the organization's needs.
To launch the server administration console, follow one of these methods:
-
Open your favorite web browser and connect to your server address like this:
-
Use
http://ipserver:7178
if you don't have any SSL ports defined in
your server network configuration. The webadmin HTTP endpoint listens on port 7178 by default
and it's bound to localhost only.
-
Use
https://ipserver:7179
if you do have any SSL ports defined in
your
server network configuration. You can configure that port using the WebAdminToolSslPort
setting in server.conf
file. This endpoint will listen on any network interface.
The web server automatically uses the first certificate you configured in your network settings. This
means that the web interface will automatically use the same certificate for your Plastic SCM SSL connections
without any further configuration. If you don't have any SSL ports defined in your server
network configuration, only the HTTP endpoint will start.
If you change the certificate you use for the SSL port at any point, make sure you restart the server to
refresh the certificate information in the webadmin.
-
Or, directly run the webadmin tool:
- From Windows: Launch the Server Admin Console tool from the Windows start menu.
- From Mac OS and Linux: Run the Plastic SCM Server application.
-
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:
- Open the command line as an administrator.
-
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
- Navigate back to the Administration console and Refresh.
- 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 server.conf
, network.conf
, db.conf
, and lock.conf
files are now reloaded.
This means that you can edit any of those files, and the Plastic SCM server will reload the config
immediately.
Network configuration
Authentication configuration
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:
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.
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.
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.
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.
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.
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 |
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.
-
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.
-
Apply the new selected mode.
-
Configure the new authentication mode:
- Local name, Name + ID, and Active Directory authentication
modes don't need any particular configuration.
-
LDAP - Configure the required data to establish the connection and advanced connection and
security settings. You can also configure some advanced features and if you want to use Plastic SCM groups.
Don't forget to click Apply for changes to take effect.
- User and password - Manage the users and groups that will be identified by the Plastic SCM
server. Both users and groups can be members of a group.
Repository storage
There are several backend technologies that Plastic supports: Jet, SQL Server, Firebird and others.
The Repository storage section lets the administrator:
-
Configure the data where the repositories information will be saved.
-
Change the storage to use a different backend technology.
Please see the Repository storage configuration chapter to
learn how to configure the repository storage that you want to use.
Advanced
The Advanced configuration section lets the administrator customize other server features.
- Request processing
-
-
Force client build number - Related to the
ForceBuildNumberMatch
parameter in
the server.conf
file.
Use this parameter to mandate all clients upgrading to the same build number of the server. Optionally, you
can set a minimum build number instead of mandating the same as the server.
Read more about how this setting works.
-
Abort request if socket closes - Related to the
AbortRequestIfSocketCloses
parameter in the server.conf
file.
When a client requests and closes the connection before the server finishes processing, the server will
kill the request thread. This avoids long-running canceled requests to grow.
Enabled by default on Windows, disabled on Linux due to instability issues.
-
Transaction timeout - Related to the
TransactionTimeout
parameter in the server.conf
file.
This is the time (in seconds) before a long running transaction is automatically cancelled by the server.
- Global security settings
-
-
FIPS compliance - Related to the
FIPSCompliant
parameter in the server.conf
file.
Enable this parameter to mandate the use of FIPS compliant algorithms only.
Requires that the Plastic clients to enable FIPS in their client.conf
file.
Otherwise, they won't be able to connect to this server.
-
Enforce secured paths - Related to the
SecuredPaths
parameter in the server.conf
file.
If you use secured paths (permissions set to paths) and want to restrict users to access file revisions by
item id if they don't have access to (using cm cat), then enable this setting.
Suitable for high-security environments.
Read more about how to use the Secured paths.
- Worker Thread Pool
-
This is the thread pool that attends client requests. Each thread is reused for better performance. Only advanced users
should tweak this value.
-
Min threads - Related to the
MinWorkerThreads
parameter in the server.conf
file.
-
Max threads - Related to the
MaxWorkerThreads
parameter in the server.conf
file.
By default, the max number of threads matches the number of cores of the server.
- Buffer pools
-
The buffer pools help reducing memory allocations by reusing pre-allocated buffers. Reducing allocations greatly
increases performance under heavy load.
-
Number of Tree buffers - Related to the
TreeBufferPoolCount
parameter in the
server.conf
file.
Use this parameter to serialize directory trees. Under heavy load, this value should match the number of
worker threads to avoid contention.
-
Number of Blob buffers - Related to the
BlobBufferPoolCount
parameter in the
server.conf
file.
Configure this value to read and write file data to the storage. These buffers reduce allocating 4MB blocks on
every data transfer.
-
Tree buffers size - Related to the
TreeBufferSizeInMB
parameter in the server.conf
file.
Set this size (in MB) to serialize directory trees. With large trees (+50k files and directories), increasing
this number greatly helps reducing memory allocations.
- Trigger variables
-
Use this section to add the custom global variables that are used in triggers.
Learn how triggers work and how to define
them.
Audit configuration
The Plastic SCM administrator can set up the auditing level as well as the auditing log file name.
Note: Don't forget to click Apply for changes to take effect.
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:
An audit log file includes a line for any logged operation with the following structure:
<HASH> <user> (<machine>) <timestamp> [<repository>]: <operation>
HASH
- Unique identifier of the logged operation.
user
- The user/developer who performed the operation.
machine
- The machine from which operation is performed from.
timestamp
- When the operation was performed.
repository
- The repository that was affected by the operation.
operation
- The description of the performed operation.
This is an example of an audit log file:
MHXET08/RpZQaJWXLlU/v7ovDPugjEOBSG9/74HFgD8= maria (HERMES) 6/23/2017 5:11:31 PM [doom3src]: Branch deleted: scm15478 (7991)
ZDSSKBGFy6SRg/O38WiyJzHbhqmUCq7SMoMp3Eqfiuc= maria (HERMES) 6/23/2017 5:44:06 PM [doom3src]: Deleted '/README.txt' (changeset 8375)
dhZG9IWM10FoHTGF+amMEeErFmHkZ2KIIL1t/uwxtYI= sue (HERMES) 6/23/2017 5:49:46 PM [doom3src]: Access denied to object 'rep:10', operation 'view'
q23jnDUDPZAicF2bYWZOWihMbXRn3/JLYSJDqOW1xJ4= maria (HERMES) 6/23/2017 5:56:14 PM [doom3src]: New label: BL064 (8408) applied to changeset 8398
k2L9HjEMqktYo7tDZQuo9PghlHgs+BMH+q3oFspRm/8= maria (HERMES) 6/23/2017 5:58:04 PM [doom3src]: Comment changed on '8408' from '' to 'Label audit test'
u84wRigufEZTKUcQrwJSjcLIxyV9b3LjwyyuX8pLUII= maria (HERMES) 6/23/2017 5:58:25 PM [doom3src]: New attribute: 'review' (8409)
AJSY/4c4QeuHU8GKIYzIdI92k6JiZoa5/ye73YIzolI= maria (HERMES) 6/23/2017 6:04:49 PM [rep03]: New branch: /main (3)
e7Mb3A49LcohQWzOCk9pAnT6Pvz5JgWNIuqthgh69BA= maria (HERMES) 6/23/2017 6:04:49 PM [rep03]: New repository: rep03 (577)
3B4jcQwNsgpi7NueKwV6rFU7vgfH1rAAQ6t+hQyXZ6U= maria (HERMES) 6/23/2017 6:17:45 PM [doom3src]: Attribute 'review' renamed to 'reviewed' (8409)
/BKLej1sb66/FlqJ/9Hr/8oiV/R50nP/oR5UEwCmbO4= maria (HERMES) 6/23/2017 6:19:58 PM [doom3src]: Comment changed on '8425' from 'Renamed' to 'File renamed'
jvck2dfnGSosVXSeLYkSzNOaFZZY1Z8AcEJtWoSx59w= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 2276
2YqWTWGEw+UbuZRYfo2ZiDEKYRMBZyGc+Tc+myQqtPc= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 7343
WrA0T9Pq276DqFxDLhoVI1gnfdWzKNEo69refw8q640= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 8016
FxFNosrb4XuAOyzwsOsiOsISgdy5S7kY5wXxPKyP/5E= maria (HERMES) 6/23/2017 6:31:10 PM [doom3src]: Downloaded revision 8320
It is possible to collect hashes regularly by scheduling the tail command, for example tail -n 1
audit.log |mail admin@myorg.com.
Security
This section lets you configure the following settings:
- Change the Administration console password - This is the password you must enter to access
the Plastic SCM Server Administration Console to apply the required changes to the server settings.
- Reset the Plastic SCM Server administrator - The server administrator is the owner of the
repository server. You can reset the server administrator from here.
Lock rules
Locking is useful to handle files that cannot be merged. Learn how to manage the required lock rules.
License
Support
Monitor
Chapter 7: Configuring exclusive check-out (Lock)
There are many kinds of files that present a challenge for merging content changes:
- Unity scenes.
- 3D models.
- Images and texture maps.
- Sound files.
- Excel spreadsheets.
- Etc…
The main goal of exclusive check-outs is to avoid the need of merging different revisions of those files. It achieves it by:
- Preventing multiple developers from making changes to the same file in parallel.
- Enforcing that developers always build from the last revision of the file.
Whenever an item is checked out, the current lock rules are checked to see if it is subject to them.
If so, the item is locked and is now regarded as "exclusively checked out".
Users and tools can check out files they intend to edit for guaranteeing exclusive access to them
while they are making changes. As soon as they are done with changes and they are checked in
— or instead, unchecked out —, the item gets unlocked again.
To start working on an file (checking it out and creating a new lock), the lock must be created from the "last"
revision of the file. This revision is the one loaded in the "destination branch", our source of truth.
Once the check-out is completed, the item is locked. However, the operation will fail if the check-out is not
done from the revision loaded in the destination branch. Checking the file directly in the destination branch
will always remove the lock.
However, if the item were exclusively checked out
in a different branch, checking the file in won't make the lock disappear. Instead,
the lock will transtion from "locked" to "retained" status as the changes must still get
integrated back into the destination branch, and only then the lock will be removed.
While in this status, the system tracks which is the last revision in the "holder branch"
and allows to keep checking out the file and iterating on it to either the original developer
or any other one. This way, developers can work in turns as if they where "passing the torch"
among themselves to know who is holding an asset and enforcing the single line of development.
In other words: the lock will be retained by the task branch all the way through,
protecting the item from parallel changes, but allowing multiple users to collaborate.
Exclusive check-out is also referred as "locking", and it is controlled by the lock rules,
set up either globaly or by repository.
How does the exclusive check-out work?
Each time Plastic SCM performs a check-out, the client asks the server whether the file needs to be
exclusively checked out or not.
The system performs the following operations:
- Is the file locked? If so, it can't be checked out.
- If it isn't locked, the file is potentially "lockable". Plastic SCM will check whether the file name matches any
of the rules defined on
lock.conf
. If the
file name matches the rules, the file will be locked.
Checking the files for a lock is performed at the client-side. This is so that files that are
not potentially lockable are never checked, and overall performance is not affected.
Locks can be found in two different states:
- Locked – when a workspace has an item exclusively checked out while making changes.
- Retained – where an item is modified in a branch pending to be integrated.
Developers can lock it and keep adding changes.
Configuring the exclusive check-out: creating the lock rules
Configuring exclusive checkout is as simple as adding or editing locking rules to the required repositories.
Complete one of these methods:
-
Launch the webadmin - Plastic SCM Server Administration console.
-
Navigate to Configuration > Lock rules.
-
You can specify lock rules for all your repositories (global rules) and for specific
repositories (repository-specific rules).
-
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.
-
Click
Generate common rules (you can edit these rules) to specify your own global rules or
load the suggested common lock rules.
-
If you leave the global rules empty, no rules will apply.
-
The repository-specific rules apply to a single repository. These rules overwrite the global
lock rules.
-
Click Add to specify the rules related to a particular repository.
-
Enter the name of the repository (the auto-complete feature will help you here) where the rules will apply.
-
Click
Generate common rules (you can edit these rules) to specify your own global rules or
load the suggested common lock rules.
-
Repeat the steps above as many repositories need lock rules.
-
Delete the rules for a repository if they aren't needed.
-
Click Apply to save the changes.
-
Create or edit the
lock.conf
file on the server's directory with the following format:
rep:<repname> [br:[<destination_branch>]] [excluded_branches:<exclusion_pattern>…]
Where:
-
repname
is one of the following:
-
The name of the repository where you want to perform exclusive checkouts by applying
repository-specific rules.
-
The character
*
meaning "all repositories" to apply
global rules to all the repositories.
destination_branch
is the source of truth when creating a new lock: the revision loaded here is considered the last revision. Locks created in other branches are not released until they get integrated back to the destination branch. It is /main by default.
excluded_branches
are branches where lock rules are ignored. Branches are matched by name, and therefore, renames are not taken into account.
exclusion_pattern
might be a full branch name (e.g.: /main/experiment), start or end by a wildcard (e.g: /main/experiments/* /main/experiment-* */art-concepts/*).
-
Configure the paths that will be exclusive checkouts. You can specify complete paths or patterns. Specify
each rule in a new line. For example,
rep:default br:/main
*.doc
*.xls
*.jpg
document.vcs
This means that the *.doc, *.xls, *.jpg and document.vcs
files are going to be locked on checkout on the default repository in the repository server
mainsvr:8084.
Or, for example:
rep:battlegame br:/main
*.png
/assets/textures/model*.*
Where the *.png pictures and all files under the /assets/textures folder that begin
with model will be locked on checkout on the battlegame repository.
See more examples about paths and patterns in the next section.
-
Repeat the steps above to create exclusive checkouts for the required repositories.
-
Save the
lock.conf
file.
This is an example of a valid lock.conf file
with global rules and repository-specific
rules:
rep: * br:/main
# Audio and video formats
*.mkv
*.mp3
*.mp4
*.ogg
*.wav
*.wave
# Image formats
*.bmp
*.jpg
*.jpeg
*.png
*.gif
*.eps
*.exif
*.icns
*.ico
*.psd
*.ai
*.svg
*.pcx
rep: doom3src br:/main excluded_branches: /main/experiment /main/experiments/* */art-concept */art-concepts/*
**/sys/*.xlib
*.def
Locks and paths
Occasionally, you'll need to
lock a directory or files under a specific folder.
Look at the below exzamples to see how to use these locks:
Rule |
Description |
/prj/Assets/Standard Assets/Toon Shading
|
Lock everything under the /prj/Assets/Standard Assets/Toon Shading folder |
/prj/Assets/Standard Assets/Tree Creator/Trees/Big*.meta
|
Lock everything under the /prj/Assets/Standard Assets/Tree Creator/Trees folder that begins with
Big and ends with .meta |
!/prj/Assets/Standard Assets/Tree Creator/Trees/BigTree_textures.meta
|
Never lock the BigTree_textures.meta file under the /prj/Assets/Standard Assets/Tree
Creator/Trees folder. This rule overwrites the previous one |
**/Library/*.prefs
|
Lock every file that ends with .prefs and is under any folder called Library |
Each time you checkout on a path that meets any of the filtered rules, this path will be in exclusive checkout so
that no one else can perform a checkout on it at the same time.
Chapter 8: Repository storage configuration
Plastic SCM supports several backend languages and technologies to store the repository data:
After the first installation, the Plastic SCM server is configured, by default, with the Jet backend.
In this chapter, you'll be able to configure Plastic SCM to work with certain backends assuming you're
starting from a clean state. You can also migrate your current repositories into another backend.
Plastic SCM uses both standard databases and structures and its own backend:
- Import the data using a standard migration tool (a quick search on google will help, see
also DbNetCopy or the built-in SQL Server
migration tool, in case you want to migrate to MS SQL Server).
- Or, read this chapter to learn how to migrate your data using the Plastic SCM Server Administration
console.
Configure Plastic SCM with Jet
Plastic has a new storage for repositories:
- Jet is super-fast and scalable.
- Jet has been designed specifically to deal with the way in which Plastic handles data and
metadata read and writes. As a special purpose storage, it is hard to beat in terms of efficiency.
There is support for 2 different workloads in Jet:
- Small server workload support - Perfect to handle local repository replicas on laptops and
workstations and even small team servers. It focuses on performance and not scalability.
- High-scalability workload support - A more complex alternative focused on scalability
workloads.
Plastic still supports SQL databases (MySQL, SQL Server, SQLite, Firebird and a few others), but Jet is enabled as the
default backend during evaluations. For Enterprise, the high-scalability engine is enabled.
In terms of performance, Jet is about 10 to 40 times
faster than SQLite and SQL Server in metadata reads and writes, which makes the server up to 3-5
times faster in operations like big checkins.
Complete one of these methods to configure the Plastic SCM Server to work with Jet:
- Launch the webadmin - Plastic SCM Server Administration console.
- Navigate to Configuration > Repository storage
- If the server is configured to work with another backend different from Jet, you'll need to change to the Jet
repository storage:
- Click Change storage.
- Select Jet as your new repository storage.
- 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.
- Choose whether you want to Migrate existing repositories or start with new empty
repositories.
-
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.
-
Configure the values for the following parameters:
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:
-
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.
-
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:
-
basepath=/mnt/metadata
blobspath=/mnt/blobs
maxcachedtrees=50
datafilesize=4
-
basepath=c:\Users\maria\plasticdb
prefix=zero
suffix=
-
basepath=/mnt/data
maxcachessizeingb=2
maxcachessizefreepercent=30
Configure Plastic SCM with Firebird, SQLite or SQL Server CE (Embedded)
Plastic SCM is flexible and it supports a great number of database engines. Some of them are embedded systems which
means that you don't need anything external to start working with them.
Firebird, SQLite and SQL Server Compact Edition belong to this group.
Complete one of these methods to configure the Plastic SCM Server to work with one of those embedded backends:
- Launch the webadmin - Plastic SCM Server Administration console.
- Navvigate to Configuration > Repository storage
- If you don't want to change your repository storage to use another embedded backend, then jump to step 4.
Otherwise:
- Click Change storage.
- Select Firebird, SQLite or SQL Server
Compact Edition as your new embedded repository storage.
- 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.
- Choose whether you want to Migrate existing repositories or start with new empty
repositories.
-
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.
-
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.
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:
- Enter the required value for the
ProviderName
key: firebird
, sqlite
or
sqlserverce
.
-
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.
-
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>
-
You can also configure the following parameters:
-
DatabasePrefix
- You can create prefixes for your database.
Here is a SQLite db.conf
example using this option:
<DbConfig>
<ProviderName>sqlite</ProviderName>
<ConnectionString>Data Source={0};Pooling=true</ConnectionString>
<DatabasePrefix>production_databases_</DatabasePrefix>
</DbConfig>
Or you can use the Plastic command line as follows: plasticd --console
--dbprefix=production_databases_
-
DatabaseSuffix
- The database suffix is a string appended to the name of every database created
by Plastic SCM on the backend. This is useful if you plan to have several Plastic SCM servers using the same
database backend, so they don't interfere with each other.
CommandTimeout
- Set the time (in seconds) available for each database command.
MaxCachedTrees
- Use this parameter to specify the maximun number of changesets whose directory
trees are cached to reduce disk access. This value allows you to balance performance and memory usage.
FullTreeRevisionsLoad
- Use this value to specify what is the maximum number of revisions to
read when loading the changeset trees. This setting sets the limit to decide when reading the full table is
faster, instead of doing individual queries.
CommentLimit
- You can also set the maximum lenght for the comment strings in the database.
-
IsolationLevel
- Override the ACID isolation level setting for the configured embedded database
backend.
Important! Plastic SCM server already sets the ACID level for the underlying
database backend that best performs for each database. It is recommended not to touch this setting on your own.
For further info, ask Plastic SCM support at devops-vcs-support@unity3d.com.
These are the possible values: Chaos
, ReadCommitted
, ReadUncommitted
,
RepeatableRead
, Serializable
or Snapshot
.
Configure Plastic SCM with PostgreSQL
Complete one of these methods to configure the Plastic SCM Server to work with PostgreSQL:
- Launch the webadmin - Plastic SCM Server Administration console.
- Navigate to Configuration > Repository storage
- If the server is configured to work with another backend different from PostgreSQL, then you need to change to
the PostgreSQL repository storage:
- Click Change storage.
- Select PostgreSQL as your new repository storage.
-
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.
- Choose whether you want to Migrate existing repositories or start with new empty
repositories.
-
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.
-
To edit settings, configure the values for the following parameters:
Edit/Create the db.conf
file under the server
folder in the
Plastic SCM installation directory to work with PostgreSQL:
- Enter the
postgresql
value for the ProviderName
key.
-
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>
-
You can also configure the following parameters:
Configure Plastic SCM with SQL Server
Supported SQL Server versions
Plastic SCM supports SQL Server 2005 or higher, due to
new transaction isolation levels introduced with 2005. It can be configured to work with
SQL Server and
SQL Server Express editions but remember the latter has some size constraints. For instance,
if you prefer SQL Server Express edition over Firebird, you can use it on your laptop (Plastic supports
distributed development and replication) to work with Plastic SCM while you're disconnected.
Complete one of these methods to configure the Plastic SCM Server to work with SQL Server:
- Launch the webadmin - Plastic SCM Server Administration console.
- Navigate to Configuration > Repository storage
- 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:
- Click Change storage.
- Select SQL Server as your new repository storage.
-
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.
- 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.
- Choose whether you want to Migrate existing repositories or start with new empty
repositories.
-
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.
-
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.
Edit/Create the db.conf
file under the server
folder in the
Plastic SCM installation directory to work with SQL Server:
- Enter the
sqlserver
value for the ProviderName
key.
-
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.
-
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.
-
And, you can also configure the following parameters:
The SQL Server database creation command can be customized with your own settings.
Remember that the command must be written in a single line. The following is an example written in
several lines to improve the readability.
<DbConfig>
<ProviderName>sqlserver</ProviderName>
<ConnectionString>SERVER=beardtongue\SQLEXPRESS;trusted_connection=yes;DATABASE={0};</ConnectionString>
<DatabaseCreationCommands>
CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase_custom, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100)
LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100)
COLLATE @PlasticDefaultCollation
</DatabaseCreationCommands>
<DatabasePath></DatabasePath>
</DbConfig>
You can use the following variables to build your own database creation command:
Variable |
Description |
@PlasticDatabase |
The database name. It's mandatory that the database creation command begins with
CREATE DATABASE @PlasticDatabase .
|
@PlasticDefaultDatabaseFile |
The default database file. Can be overwritten with a path that includes @PlasticDatabase as a
part of the database file name.
|
@PlasticDatabase_log |
The default log file name. Can be overwritten.
|
@PlasticDefaultLogFile |
The default log file path. Can be overwritten using @PlasticDatabase as a part of the file name
or appending a suffix to the variable @PlasticDefaultDatabaseFile , for example,
@PlasticDefaultDatabaseFile.log.
|
@PlasticDefaultCollation |
It's the collation defined in the db.conf with the key
DatabaseCollation . If it doesn't exist then the collation mode will be the default one used by
Plastic: Latin1_General_CI_AI. You can override it in the custom command. The collation in the custom command
has priority over the DatabaseCollation value in the db.conf
file.
Important: you must specify a valid collation in the custom creation command
if your SQL Server default collation is not case insensitive or accent insensitive. Valid collations are "Case
Insenstive" and "Accent Insensitive" collations (CI_AI or KI_KS collation suffixes). Otherwise, this could
generate some strange behaviors.
|
This is the default command Plastic uses to create databases when the <DatabaseCreationCommands>
key is not in your db.conf
file:
CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100)
LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100)
COLLATE @PlasticDefaultCollation
Here are some custom database creation command examples:
The commands here are split into several lines for readability purposes.
- Multiple commands. Must be separated with ";" and specified in a single line. You can't use the "GO" clause:
<DatabaseCreationCommands>
CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=10, FILEGROWTH=100)
LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=10, FILEGROWTH=100)
COLLATE @PlasticDefaultCollation;ALTER DATABASE @PlasticDatabase SET PAGE_VERIFY CHECKSUM;ALTER DATABASE @PlasticDatabase SET ANSI_WARNINGS OFF
</DatabaseCreationCommands>
- Change database file location and log names and paths:
<DatabaseCreationCommands>
CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase, FILENAME='C:/databases/dbs/@PlasticDatabase.db', SIZE=10, FILEGROWTH=100)
LOG ON (NAME=PlasticLog_@PlasticDatabase, FILENAME='C:/databases/logs/@PlasticDatabase.log', SIZE=10, FILEGROWTH=100)
COLLATE @PlasticDefaultCollation
</DatabaseCreationCommands>
- Change size parameters or collation:
<DatabaseCreationCommands>
CREATE DATABASE @PlasticDatabase ON PRIMARY
(NAME=@PlasticDatabase, FILENAME='@PlasticDefaultDatabaseFile', SIZE=100, FILEGROWTH=50)
LOG ON (NAME=@PlasticDatabase_log, FILENAME='@PlasticDefaultLogFile', SIZE=100, FILEGROWTH=50)
COLLATE SQL_Latin1_General_CP1_CS_AS
</DatabaseCreationCommands>
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).
Memory is an important feature to configure in your SQL Server installation particularly if you don't have a
dedicated server for it. The system will perfom better if you limit your SQL Server memory than if you let it grow
as much as it can.
If you're using SQL Server Express you'll have to do it with the
sp_configure stored procedure. If you use a regular SQL Server, you'll be able to configure it from the admin
application. Running the stored procedure is simple:
USE master
EXEC sp_configure 'show advanced options', 1
RECONFIGURE WITH OVERRIDE
USE master
EXEC sp_configure 'max server memory (MB)', 300
RECONFIGURE WITH OVERRIDE
This limits it to 300Mb.
Check out the following links for more information:
Configure Plastic SCM with MySQL
Complete one of these methods to configure the Plastic SCM Server to work with MySQL:
- Launch the webadmin - Plastic SCM Server Administration console.
- Navigate to Configuration > Repository storage
- If the server is configured to work with another backend different from MySQL, then you need to change to the
MySQL repository storage:
- Click Change storage.
- Select MySQL as your new repository storage.
-
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.
- Choose whether you want to Migrate existing repositories or start with new empty
repositories.
-
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.
-
If you need to edit some settings, then configure the needed values for the following parameters:
Edit/Create the db.conf
file under the server
folder in the
Plastic SCM installation directory to work with PostgreSQL:
- Enter the
mysql
value for the ProviderName
key.
-
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>
-
You can also configure the following parameters:
Finally, you must set the MySQL configuration parameter max_allowed_packet
to support up to 10MB. If you
require more information about how configure this parameter, you can take a look at this article.
Note: In some Linux distributions like Arch Linux, the MySQL server does not listen on the TCP port
3306 by default. To allow (remote) TCP connections, comment the following line in /etc/mysql/my.cnf
: skip-networking
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.
The performance of MySQL and the Plastic SCM server depend largely on the amount of memory and CPU available. As
usual with performance tuning, there is no one-size-fits-all answer, but these guidelines may be useful to squeeze
more out of your hardware.
For this article, it is assumed that you have a decent machine, dedicated to the Plastic SCM server and MySQL
exclusively, with 4GB of RAM.
Edit the my.cnf
file, normally located in /etc
or /etc/mysql
in Linux, or the c:\Program Files\MySQL\my.ini
file in
Windows. Add or edit the lines below:
-
The
innodb_buffer_pool_size
should be around half of the memory of your server machine. This is the
most important value. Note that due to a limitation in MySQL, this value should be maximum 4GB (more details here):
innodb_buffer_pool_size = 2G
-
innodb_additional_mem_pool_size
should be a 5% of the innodb_buffer_pool_size:
innodb_additional_mem_pool_size = 100M
-
Set
innodb_log_file_size
to 25% of buffer pool size:
innodb_log_file_size = 500M
Keep in mind that changing this value renders your ib_logfileX files unusable (they are located in the data
directory), and MySQL may refuse to start until the files are removed and MySQL can recreate them. Make sure
that MySQL was shut down correctly before removing these files.
-
innodb_log_buffer_size
can be around 2% of the buffer pool size or, at a minimum, 8MB:
innodb_log_buffer_size = 40M
Once these settings are in place, restart the MySQL service.
Don't forget to set the max_allowed_packet
to 10MB. This is mandatory for correct Plastic SCM
operation:
max_allowed_packet = 10M
Chapter 9: Backup and restore
The backup and restore procedures are closely related to the database backend used in Plastic SCM.
Important! The instructions in this chapter are for the
embedded and
Jet backends only.
If you configured a different database backend, please check with your database administrator to find out what are the best
backup procedures for it.
How to backup and restore the embedded databases
Backing up the embedded databases is just copying the database files from disk. Each database will be a single
file, so the operation is pretty simple. However, backing such a database file requires that the Plastic SCM server
be stopped.
Note: This is one of the drawbacks of the embedded backends that are usually better handled by the
other supported backends such as MySQL, MS SQL Server or PostgreSQL. This is one of the reasons why it is recommended
to use the embedded backends for evaluation purposes only.
Starting and stopping the Plastic SCM server on the command line has been described in the previous sections, so the
following procedure can be easily automated with scripts.
Steps to backup:
- Stop the Plastic server.
- 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.*
.
- Start the Plastic server again.
The restore procedure is very similar to backup in reverse order:
- Stop the Plastic server.
-
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.
- Start the Plastic server again.
How to backup and restore the Jet backend
The Jet backup operation is easy to achieve. You can follow one of these options to backup and restore your Jet
data:
- Cold copy - This procedure requires to
stop and start the Plastic SCM server.
- Hot copy - This method requires to switch the
Plastic SCM server between normal and read-only modes.
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.
- Stop the Plastic server.
- Backup the Jet content. You can find it in the
basepath
parameter specified during the database setup (check the jet.conf
file).
- Start the Plastic server again.
- Stop the Plastic server.
- Restore all the backup files to the path you configured (remember to set the right setting for the path in the
jet.conf
file).
- Start the Plastic server again.
This section explains how to perform the hot backup and restore operations.
Check an example explaining how
to perform a hot backup with Rdiff.
- Set the Plastic server to read-only mode ( cm admin readonly enter ).
- Backup the Jet content. You can find it in the
basepath
parameter specified during the database setup (check the jet.conf
file).
- Set the Plastic server to normal mode.
- Set the Plastic server to read-only mode.
- Restore all the backup files to the path you configured (remember to set the right setting for the path in the
jet.conf
file).
- Set the Plastic server to normal mode.
You can perform the backup and restore operations manually or using your backup tool. The following tools
are tested on Windows and Linux:
Tool |
Restore |
Incremental |
Comments |
Bvckup2 |
– |
✓ |
This tool doesn't provide a retore backup feature. You just need to re-copy the backup content to the
original path.
|
CrashPlan |
✓ |
✓ |
Cloud backup solution. |
Rsync |
✓ |
✓ |
Widely used for Unix platforms. You'll likely have this tool as part of your Unix OS.
This tool also allows remote machines copies through ssh:
rsync -a -e ssh source/
username@remotemachine.com:/path/to/destination/
|
Rdiff-backup |
✓ |
✓ |
Widely used for Unix platforms, it supports Windows too. Very easy to use and robust.
You can see below two examples using this tool to perform a cold backup and a hot backup.
|
Duplicati |
✓ |
✓ |
Easy to install and use, provides a web interface in order to setup and trigger incremental backups. |
Nticorp |
✓ |
✓ |
Local and Cloud backup/restore. |
This example shows the setup for a weekly and incremental backup using rdiff-backup on a Linux machine:
- Install rdiff-backup 1.2.8 in the server.
- Configure autofs to auto-mount backup NFS folder in the /cifs/backup folder.
-
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:
You can execute the same example above, but as it is a hot copy, you'll need to switch
the server between normal and read-only modes ( cm admin readonly ) instead of stop/start it.
The script will be something like this:
#!/bin/bash
export weekNumber='date +%V'
export year='date +%Y'
export today='date +%Y%m%d'
export lastActinLogFile="/root/backup_jet.log"
export dirName="week_$weekNumber"
export baseBackupDstLocation="/cifs/backup/backups/myserver_jet"
export backupFinalDstLocation="$baseBackupDstLocation/$year/$dirName"
export weekIncrementsTarGzDstFile=$backupFinalDstLocation/myserver_ddbb_jetfs.rdiff-backup_$year_week_$weekNumber.tar.gz
#rdiff-backup source and destination params
export srcJetFolder="/home/mydata/jet"
#export rdiffBackupWeekIncrementsAuxDir="/home/mydata/local_jet_backup_rsync"
export rdiffBackupWeekIncrementsAuxDir="$baseBackupDstLocation/tmp"
echo "starting daily backup $today on dst dir: $backupFinalDstLocation" > $lastActionLogFile
#if we're starting a new week, reset the increments dst dir so rdiff-backup will start a fresh backup from scratch
if [ ! -d "$backupFinalDstLocation" ]; then
mkdir -p $backupFinalDstLocation
#reset weekly backup local folder
rm -rf $rdiffBackupWeekIncrementsAuxDir
fi
echo "about to stop and targz $today" > $lastActionLogFile
cm admin readonly enter
sleep 20
rdiff-backup $srcJetFolder $rdiffBackupWeekIncrementsAuxDir
rm $weekIncrementsTarGzDstFile
tar cvzf $weekIncrementsTarGzDstFile $rdiffBackupWeekIncrementsAuxDir
sleep 20
cm admin readonly leave
echo "done! $today" > $lastActionLogFile
Chapter 10: Archiving revisions
Why archive revisions?
There are third party compiled tools, programs, binaries, big documents and
other kinds of big files that rarely change and/or are rarely accessed in a production environment. This can consume
disk space and time when
storing and retrieving those revisions from the database.
As an administrator, you can use the archive command, which allows you to set
up a separate disk device, such as a tape, a USB pen drive, an external disk, a CD-ROM or DVD, and store large
revisions there so that they do not take space in the database. Thus, every time a
user needs to access those revisions, Plastic SCM will search for them in the external storage area and
retrieve that information.
How to archive my revisions
To archive revisions, use the archive command (cm archive):
cm archive C:\mybigfile.tar#br:/main#0 -c="big file of libraries" -f="/home/plastic/bigfileTARrev0"
A breakdown of the archive example above:
-
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.
- The archive's comment
(-c parameter) is "big file of libraries", and the archive files will be created in
/home/plastic/bigfileTARrev0.
- The
-f parameter is a prefix for the archive files that can be used as a destination path for the
archives.
If the -f switch is omitted, the archive files will be created in the current directory.
You can archive several revisions by specifying them one after the other in the same command. To get further
information about this command, type on a command line cm help archive.
Once the archive files have been created, the administrator can move them to the external data location. The next
time a user tries to access that data, Plastic SCM will retrieve it from the external storage area.
Note: The user that executes the archive command must be
the repository owner. If not, the revision will not be archived correctly, and Plastic SCM will continue using
the database to access the data.
Warning! An archived revision cannot be archived again. Once a revision has been archived it is
taken out the database.
How are the archived revisions accessed
To access the data stored on an external location, a configuration file externaldata.conf
file must be manually
created. This file contains a path per line; those paths are the locations of the stored revisions. The following is
a sample of an externaldata.conf
file:
E:\archivesOfRepository1
D:\mybigfiles\revisionsOfBigFileTAR
F:\revisionsOfThe2_9Release
This file can be placed in two locations:
- On the server-side: placing the
externaldata.conf
file on the Plastic
SCM server location will allow every user to access those revisions automatically, as long as the
external storage area is available. This is the most useful option for system administrators.
- On the client-side: placing the
externaldata.conf
file on the Plastic
SCM client folder or on the user local directory (within Documents and Settings
in
Windows, Users
in Vista/Seven, or home
in UNIX based
systems).
If a user tries to access any stored revision from the GUI by, for example, executing an update, and there is no
externaldata.conf
, a dialog will appear, asking for the location of the data as
illustrated in the following picture:
Once the first chunk of the revision is introduced, Plastic SCM will be able to find the other chunks of the
revision. It will create an externaldata.conf
file in the local user directory, and from
that moment on, it will try to access the archived revisions from that location. If Plastic SCM cannot access the
data at a certain point in time, it will show the same dialog again. If a new location is introduced, this
location will be added to the existing externaldata.conf
file.
From the CLI (command-line interface) an externaldata.conf
must always be available.
If not, the command will ask the user for an externaldata.conf
to look for the
revisions.
How to restore archived revisions
It is possible to save archived revisions back into the database, so they archives can be safely deleted. From
there, the database will be used to get the data.
Example:
cm archive C:\mybigfile.tar#br:/main#0 --restore
A break down of the example above:
-
This command will restore the revision 0 of the main branch of the file mybigfile.tar
into
the database, and the archives of that revision will no longer be used.
-
The external storage location must be available at the moment of the revision restoration, and an
externaldata.conf
file must be available.
To get more information on this command, run cm help archive on a command line.
Chapter 11: Upgrade to a given version
How to force client upgrades
The Plastic SCM server can reject clients that are older than the current version. This is a great way for sysadmins
to
ensure the users upgrade their clients correctly.
To force a given build number, add the key ForceBuildNumberMatch
in the server.conf
file. This key admits the following values:
Chapter 12: Plastic SCM SSL certificates
For internal application development and testing, it is often preferable to use a self-signed SSL certificate to
avoid the cost of one signed by an external certificate authority. This lesson explains the process of
creating a self-signed certificate and root Certificate Authority (CA) certificate that can be used with
Plastic SCM.
Tools
Depending on your OS, you will need different tools to create a certificate. Use the required tools to create
a certificate for your Windows, Linux or Mac system.
For Windows, you will need to install the makecert and pvk2pfx tools, available on the Windows SDK.
-
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.
-
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.
For Linux and Mac OS, one of the most versatile SSL tools is openssl. This tool is an open-source
implementation of the SSL protocol.
openssl is commonly used to create the Certificate Signing Request (CSR) and private key for many different
platforms. This tool comes with almost every Linux distribution, so it is usually already installed and ready to use.
Creating the self-Signed certificate
Use the tools on your Windows, Linux or Mac system.
-
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.
-
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.
-
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
-
Run the following command to export the
.pem
certificate file into a .pfx
file:
openssl pkcs12 -export -out ssl-certificate.pfx -in key.pem -name "PlasticSCM Certificate"
The .pfx
file is now ready to be used with the Plastic SCM server.
Creating a CA-Signed Certificate
The Certificate Authority (CA) certificate will be used to generate additional SSL certificates for other sites or
services such as the Plastic SCM server.
Let's see how to do it on your Windows, Linux or Mac system.
-
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
-
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
-
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>
-
To create the root key, execute the following openssl command :
openssl genrsa -out rootCA.key 2048
-
Once the
rootCA.key
file is created, it can be used to generate the self-signed
certificates by executing the following command:
openssl req -x509 -new -nodes -days 3560 -key rootCA.key -out key.pem
-
Like with the self-signed certificate,
generate the
.pfx
file by exporting the recently created .pem
file. Run the following command to export the certificate into a .pfx
file:
openssl pkcs12 -export -out ssl-certificate.pfx -in key.pem -name "PlasticSCM Certificate"
Using the certificate for the Plastic SCM Secure channel
By default, the Plastic SCM server SSL channel is configured to listen on port 8088 using the default SSL Plastic
SCM SSL certificate.
To use your own self-signed certificate, you'll need to edit the network.conf
file which is located inside the Plastic SCM server directory. There, you
must modify the following two values:
sslPfxFile
- to use your .pfx
certificate .
sslPfxFilePassword
- to specify the certificate password. You can write it in plain text but it is
recommended that you encrypt it using the cm crypt command and use the cipher value instead.
Once the network.conf
file is saved, restart the Plastic SCM server to apply the change.
The following example shows you the server network.conf
file using the new
Tardis.pfx certificate and the ciphered password:
[
{
"Port" : 8087,
"Type" : "Tcp",
"Security" : "None",
"ReuseAddress" : true
},
{
"Port" : 8088,
"Type" : "Tcp",
"Security" : "Ssl",
"SslPfxFile" : "Tardis.pfx",
"SslPfxFilePassword" : "|SoC|2ogBDa8GmifTjC7UKp4KuoF0/jWYlXy2",
"ReceiveTimeoutMsec" : 5000,
"SendTimeoutMsec" : 5000,
"ReceiveBufferSizeBytes" : -1,
"SendBufferSizeBytes" : -1,
"ReuseAddress" : true
}
]
Accepting and installing SSL certificates for Plastic SCM
There are several methods that you can use to install the Plastic SCM certificate:
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.
The Plastic SCM command line tool is also known as the cm executable. When you use this method to install
the Plastic SCM certificate you will be prompted with a dialog to accept and install the Plastic SCM server
certificate:
>cm lrep ssl://TARDIS:8088
The server you are connecting to has sent a certificate that is not in the store. This is normal if it is the first
time that you connect to this server.
Certificate details:
- Issued to: CN=TARDIS
- Issued by: CN=TARDIS
- Expiration date: 01/01/2040 0:59:59
- Certificate hash: D104DDF745C50BCAF6A742280633A1D39C3D814E
If you trust this host, choose 'Yes' to add the key to Plastic SCM's key store (recommended if it is the first time
you connect to this server).
If you want to carry on connecting just once, without adding the key to the store, choose 'No'.
If you do not trust this host, choose 'Cancel' to abandon the connection.
Choose an option (Y)es, (N)o, (C)ancel (hitting Enter cancels): Y
default@ssl://TARDIS:8088
Cmd@ssl://TARDIS:8088
CmdRunner@ssl://TARDIS:8088
2dShooter@ssl://TARDIS:8088
Click Yes to add the key to the Plastic SCM key store.
The certificate will need to be accepted and installed in certain situations without using the Plastic SCM client.
For example, a Plastic SCM server has to connect with another Plastic SCM server using the SSL port during a
replication operation. Since the server itself is not able to accept a certificate, it is necessary to install the
certificate file (.cer
) manually.
Note: The certificate installed will only be valid for the system user who accepts the
certificate on the server. If you need to install a certificate that will be used by the Plastic SCM server, then
the system you'll need to run the Plastic SCM server/daemon as "Administrator" or "root" user.
Manually install the certificate on a Windows, Linux or
Mac OS based server:
Windows
-
The Microsoft Windows certmgr.msc tool is used to install the certificate files (
.cer
) that can be read by external applications.
-
The certificates are imported by clicking Action > All tasks >
Import:
-
Specify the location of the certificate file by(
.cer
) clicking Browse:
-
Click Next to place the certificate file (
.cer
) in the "Plastic Client" store.
-
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.
Installing the certificate on MacOS server is as simple as copying the certificate file (.cer
) to a directory:
Note: Only the system user <Your_User> will have the certificate installed. If
you need to install certificates for other users, repeat the process for each of those
users.
Chapter 13: Support alternative connections to the same server
Plastic SCM allows reaching the same server by different IPs and protocols.
The serveralias.conf
file enables this feature
on the Plastic SCM client. This file will contain a pair of connections that are aliases of each other:
alias1 alias2
With this file, the client will know what connection use at any given time.
Configuring the server aliases file
Suppose you connect to localserver.office-network.com:8084 from the office, but when you go home you
connect through the public SSL-protected IP: ssl://plastic.external-network.com:8090. Somehow the
client must know that server:8084 and ssl://externalserver:8085 are aliases of
each other.
Using the server aliases, the Plastic SCM client will switch from one server URL to the other
transparently.
To solve this situation a serveralias.conf
file must be created under the plastic4
directory (under $HOME/.plastic4
on Linux/Mac systems or
C:\Users\user\AppData\Local\plastic4
on Windows) or in the
plastic-global-config repository so that all clients have the same settings by default. Optionally, it can be under the client
folder in the Plastic SCM installation directory.
The content of the serveralias.conf
file will be:
localserver.office-network.com:8084 ssl://plastic.external-network.com:8090
Note: The file can jump to a different URL and a different protocol (in this case from regular TCP to
SSL).
Chapter 14: Choose a compression method
You can select what type of compression method will be used by Plastic to store a new
revision of a file in the database. The new revision will be created with one of the following Plastic SCM
operations:
A new configuration file called compression.conf
on the Plastic SCM client lets you select the compression type by using
patterns.
The
compression.conf
file is located in the:
-
plastic4
directory (under $HOME/.plastic4
on
Linux/Mac systems or C:\Users\user\AppData\Local\plastic4
on Windows).
- Root directory of the workspace.
The file supports two types of compression:
If the compression.conf
doesn't exist then the compression type of any file is "zip".
Configuring the compression file
Each line of the compression.conf
file will define a compression type followed by a
whitespace and a rule to match the file path. For example:
none .jpg
zip .txt
This example means that any .jpg file won't be compressed, and all the .txt files will be
compressed using the zip compression method.
The compression.conf
file can be defined in the following locations:
- Root of the workspace: the rules included in the file will be valid only for that workspace
- User config folder (usually
\Users\<username>\AppData\Local\plastic4
): the rules in the file will be applied for
all workspaces
If both files exist, their rules will be combined.
There are 4 types of rules that can be specified, and the order of application is the following:
- File path rule
- File name rule
- File extension rule
- Wildcard rule
For instance:
- /dir/foo.png
- foo.png
- .png
- /**/foo*.???
If a file path matches with a path rule, that rule will be the chosen compression type. If not, it will try to
match with a file name rule.
Having the following compression.conf
file under the wkstest workspace...
zip .png
none /test01/main-test.png
...if you perform a checkin on the main-test.png, user1-test.png and
test-result.png files, all the .png files but the /test01/main-test.png file will be
checked-in using the zip compression method.
Chapter 15: How to configure the license autorenewal
You can configure your server to use the license auto-renewal option.
Configure it from the License section in the webadmin - Plastic SCM Server
Administration console.
Chapter 16: Configuration files
Plastic SCM works with several configuration files. These files allow you to set up global parameters that will
be used for the Plastic server and client. Most of them will be configured through the Plastic GUI. But the user and
the administrator will be able to modify them directly.
File |
Description |
branchexplorer.cfg (Windows)
branchexplorer.conf (Linux and Mac OS)
|
Contains the configuration information related to the Branch Explorer.
This config file is located in:
- The
plastic4 directory containing user settings (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
- Or in the plastic-global-config repository so that all clients have the same settings by default.
Learn about how to
globally configure the Branch Explorer for all users.
|
client.conf |
Contains important client configuration settings, including the default server, user credentials, and merge
and diff tools.
This config file is located in the plastic4 directory containing user settings
(under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
|
cloaked.conf |
Contains the paths of the controlled files to cloak. Cloaked files and directories won't be downloaded
during the update (or not updated if they were already on the workspace before being cloaked).
This config file is located in the root directory of the workspace, or in the
plastic-global-config repository so that all clients have the same settings by default.
Learn about how to configure the cloaked list.
|
compression.conf |
Lets the user select the compression type by using patterns.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the root directory of
the workspace.
Learn about how to configure these patterns.
|
cryptedservers.conf |
Stores the information to set up encryption in Plastic Cloud.
This config file is placed in your Plastic SCM server installation directory.
Learn how the encryption works both in Plastic Cloud extension or in Plastic Cloud Edition.
|
customextensions.conf |
Stores the Plastic SCM custom extensions (your own issue tracker integration extensions).
This config file is placed at your Plastic SCM client installation directory.
Learn about how to create your custom extension.
|
db.conf |
Stores the database backend settings that Plastic will use. These settings are related to the following
backends: Firebird, SQLite, SQL Server CE, PosrgreSQL, SQL Server and MySQL.
This config file is placed at your Plastic SCM server installation directory.
Learn how to manage the db.conf file to configure Plastic SCM with:
|
eolconversion.conf |
Define the EOL conversion based on the file extension.
This config file must be located in your Plastic SCM client installation directory, or in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac
systems or C:\Users\user\AppData\Local\plastic4 on Windows).
Learn about how to
configure the EOL conversion.
|
externaldata.conf |
Contains the external locations (paths) of the stored revisions when archiving them.
This config file is located in your Plastic SCM server installation directory, or in your Plastic SCM client
installation directory, or in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows)
Learn about how to archive revisions and create this file.
|
externaltools.conf |
Allows users to define external applications and how they'll receive the selected object properties.
This config file can be included in your Plastic SCM client installation directory, in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac
systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the
plastic-global-config repository at /externaltools/externaltools.conf so that all clients have the same settings by default.
Learn how to
configure the external tools.
|
filetypes.conf |
This file is used to check if a file is binary or text before running diffs or merges.
This is really useful when you are working with Plastic Cloud, since changing revision types is not allowed
there.
For example, lets suppose the the scene.config file was wrongly added as binary. You can
configure filetypes.conf to consider scene.config as text, so the
right text-based diff and merge tool will be selected instead of considering the "bin type" tracked for the
file in the repo.
This config file is located in the plastic4 directory (under
$HOME/.plastic4 on Linux/Mac systems or
C:\Users\user\AppData\Local\plastic4 on Windows), in the root directory
of
the workspace, or in the plastic-global-config repository so that all clients have the
same settings by default.
|
gitserver.conf |
This is the file controlling the GitServer configuration.
This config file is placed at your Plastic SCM server installation directory.
Learn about how to create this file to configure GitServer.
|
gitsync.conf |
This file allows the user to include information that will be automatically used during the GitSync
operations.
This config file is located in your Plastic SCM client installation directory, or in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac
systems or C:\Users\user\AppData\Local\plastic4 on Windows).
Learn about how this file works.
|
groups.conf |
Stores the Plastic groups configured from the User management tool.
This config file is placed in your Plastic SCM server installation directory.
|
guiclient.conf |
Stores the Plastic GUI settings, like the Pending changes, Annotate, "Other options", Merge configurations,
Plastic Drive, and more.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
Learn about how to work with this file or how
to mount a changeset in Plastic Drive.
|
hidden_changes.conf |
Contains the paths of the controlled files to hide from the Pending changes view. The
hidden changes are controlled items that can be changed don't appear by default
on the Pending changes view.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), in the root directory of
the workspace, or in the plastic-global-config repository so that all clients have the same settings by default.
Learn about how to configure the hidden changes list.
|
ignore.conf |
Contains the paths of the private files to be ignored in the Pending changes view. The
ignored files are files that you have no intention of placing under source control.
This config file is placed at the root directory of the workspace, or in the
plastic-global-config repository so that all clients have the same settings by default.
Learn about how to
configure the ignored list.
|
jet.conf |
Stores the settings when configuring Plastic to work with Jet (Plastic's repository storage).
This config file must be located in your Plastic SCM server installation directory.
Learn how to configure Plastic with Jet.
|
languages.conf |
Lets the user customize the language extensions to syntax highlight the code when the files/revisions are
compared in the Side-by-side Diff tool.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
Learn about how to configure this file.
|
lock.conf |
Stores the rules to configure exclusive lockouts.
This config file is placed at your Plastic SCM server installation directory.
Learn about how to create these rules.
|
mergerules.conf |
Stores the merge rules used to restrict merges to happen only if certain rules are met.
This config file is placed in your Plastic SCM server installation directory.
Learn how to configure your Merge Rules system.
|
openwith.conf |
Stores the Open With context menu applications and shortcuts.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows).
Learn about how to customize the tools that will be displayed in the "Open with..." menu.
|
readonly.conf |
Contains the paths of the controlled items to keep as "readonly" after an update.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the
plastic-global-config repository so that all clients have the same settings by default.
Learn about how to
configure this attribute.
|
network.conf |
Stores the listening ports configuration values.
This config file is placed in your Plastic SCM server installation directory.
Learn about how this file works and how to edit it when using your own self-signed certificate.
|
server.conf |
Stores the authentication mode, the audit log level, and more server settings.
This config file is placed at your Plastic SCM server installation directory.
The server settings can be configured from the webadmin.
|
serveralias.conf |
Contains a pair of connections that are aliases of each other. This way you can reach the same server by
different IPs and protocols.
This config file is placed in your Plastic SCM client installation directory, or in the
plastic-global-config repository so that all clients have the same settings by default..
Learn about how to support alternative
connections to the same server.
|
users.conf |
Stores the Plastic users configured from the User
management tool.
This config file is placed in your Plastic SCM server installation directory.
|
writable.conf |
Contains the paths of the controlled items to keep "writable" after an update.
This config file is located in the plastic4 directory (under $HOME/.plastic4 on Linux/Mac systems or C:\Users\user\AppData\Local\plastic4 on Windows), or in the
plastic-global-config repository so that all clients have the same settings by default.
Learn about how to
configure this attribute.
|
Global file configuration
You can set a global file configuration in the server. This way, all the Plastic clients have the same
settings by default. This means that the configuration files will consult the global configuration and the
local (workspace relative) and main (client relative) files.
Once the global configuration is created at the server-side, the server configuration will be downloaded at the
client-side when the Plastic GUI starts.
To set up the global configuration in the server, create a repository named plastic-global-config
(or update it if you created it when setting the global extension configuration).
The plastic-global-config repository will have the following structure:
- Global configuration for a specific repository:
/repname/configuration_file.conf
.
For example, /doomsrc/ignore.conf.
- Global configuration for all the repositories:
/allrepos/configuration_file.conf
.
For example, /allrepos/filetypes.conf.
Note: For submodules, you should use the '-' char instead of '/': /myrepo-mysubrepo/configuration_file.conf
.
For example, /plugins-3dplugin/cloaked.conf, where plugins is the main repo and
3dplugin is the submodule.
Important! These are the files that can be globally configured:
You must restart the GUI for the changes to take effect.
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.
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:
- Navigate to your Plastic SCM GUI and set your Branch Explorer configuration preferences.
-
Find the generated configuration file in:
- Windows:
C:\Users\user\AppData\Local\plastic4\branchexplorer.cfg
- Linux and Mac OS:
$HOME/.plastic4/branchexplorer.conf
- Copy the resulting file to the global configuration repository under the
allrepos
folder.
- 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.
A global branchexplorer.conf
file looks like this:
[Default]
filters.conditional.numrules=1
filters.conditional.rule0.branches_query=attribute = 'status' and attrvalue = 'RESOLVED'
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=exclusion_rule
Note: Rules start from rule0
(first rule).
A local branchexplorer.conf
contains user-specific information too:
[Default]
display.attributes.visible=true
display.changestats.visible=true
display.extension.visible=true
display.navigator.visible=false
display.options.branch_level_filter=-1
display.options.changeset_color=1
display.options.dag_mergelinks=false
display.options.draw_branches=true
display.options.draw_crossbranch_changeset_links=true
display.options.draw_labels=true
display.options.draw_merge_links=true
display.options.draw_only_relevant_changesets=false
display.options.draw_taskinfo=true
display.options.end_date=0
display.options.end_date_enablement=false
display.options.full_branch_names=true
display.options.layout_mode=0
display.options.show_parent_to_child_arrows=false
display.options.start_date=636136983268496003
display.options.visible=false
display.properties.legend=false
display.properties.visible=true
display.properties.zoom=0,9999999
filters.conditional.numrules=1
filters.conditional.rule0.branches_query=
filters.conditional.rule0.color=0,128,192
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=non_integrated_branches
filters.conditional.visible=true
The GUIs will combine the global and local filters. The resulting configuration for filters will be as follows:
filters.conditional.numrules=2
filters.conditional.rule0.branches_query=attribute = 'status' and attrvalue = 'RESOLVED'
filters.conditional.rule0.description=Unresolved branches
filters.conditional.rule0.enabled=true
filters.conditional.rule0.related.branches=None
filters.conditional.rule0.type=exclusion_rule
filters.conditional.rule1.branches_query=
filters.conditional.rule1.color=0,128,192
filters.conditional.rule1.description=Unresolved branches
filters.conditional.rule1.enabled=true
filters.conditional.rule1.related.branches=None
filters.conditional.rule1.type=non_integrated_branches
As a result of the combined rules in the example above:
- Users will NOT see branches which the
status
attribute is set to RESOLVED
(because the
rule type is exclusion_rule
) -> Global config.
- Users will see the branches that are not merged (type
non_integrated_branches
) colored blue (RGB
0,128,192) -> Local config.
Chapter 17: Transformable workspaces
The workspace content can be locally transformed based on some rules. This means workspace items can be moved to
different locations or even not loaded.
Reasons for using the transformable workspaces:
- You need to configure your workspace by moving some folders to run a correct build.
- You're working with big repositories that store a large number of files and/or big files, and you don't want to
load some of them into your workspaces.
Transformer rules
A transformable workspace is configured through the transformer rules.
These rules are specified in a file named plastic.transformerrules
inside the workspace
.plastic
configuration directory. This file must be created manually first.
Two kind of rules are currently supported:
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
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
After editing the file to add, remove or change any rule, an update operation must be manually
executed to make the workspace changes effective (forgetting the update operation after editing the file can lead to
errors).
Note: There cannot be pending changes in the workspace when editing the rules file.
-
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.
-
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.
-
Now to Update workspace, and the transformer rules are applied:
The moved directory now has the Directory / Transformed type.
Note: This functionality is still under development although a standard working cycle can be
normally performed.
The most common operations are supported: add, rm, co, unco, ci, merge, status, ls, etc.
Current limitations
- Fast-update operation
- Update with controlled pending changes
- Cloaked functionality
- Merge inside rm rules
- 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).
-
The xlinks cannot be moved by transformer rules.
Example:
mv /src/xlink /xlink
-
The tranformer rules cannot modify an already applied rule.
Example:
mv /src/foo.c /src/bar.c
mv /src /source
-
The rm rules cannot be applied when they contain the source or destination of a mv rule.
Example:
mv /src/foo.c /doc/foo.c
rm /src or rm /doc
-
The rm operation cannot be applied when it contains the source or destination of a mv rule.
Example:
mv /src/foo.c /doc/foo.c
$cm rm src
-
The transformed moved nodes cannot be moved again.
Example:
mv /src/foo.c /doc/foo.c
$cm mv doc/foo.c foo.c
Chapter 18: The Plastic SCM server read-only mode
You can switch the Plastic SCM server between normal mode and read-only mode by executing:
cm admin readonly action
When the server is in read-only mode, only read operations are allowed, so no data will be changed. This is useful
using Jet backend because it allows backup operations to be
performed without stopping the server.
The cm admin readonly command allows you to:
-
Enter in read-only mode using cm admin readonly enter
Once it's executed, no more write operation will be allowed. The command will wait for all currently running write
operations to end before it finishes.
-
Leave read-only mode using cm admin readonly leave
This action brings the server back to normal mode; for example, write operations are allowed again.
-
Retrieve the read-only mode status using cm admin readonly status
Chapter 19: The Merge Rules system
The Merge Rules system allows you to restrict merges to happen only if specific rules are met.
This system is available both for Plastic SCM Enterprise Edition and Plastic SCM Cloud Edition.
It is very easy to set rules like "don't allow to merge branches if they are not reviewed" and "only allow merges
from child branches".
Previously, you'd have to write a trigger to enforce this behavior. But now, it is just a matter of setting a few
merge rules.
Types of merge rules
With the Merge Rules system, you can restrict merges to certain branches, so that:
How the Merge Rules system works
-
You must first specify one or more merge rules.
A merge rule defines:
-
When you're about to merge a branch, the server will check whether there are any rules that apply to the
involved source/destination branches pair.
'only_allow_merges_if_reviewed' rule
Definition
Only allows merging branches if they have an approved code review. It is an equivalent to the popular "pull
request restrictions" that mandate reviewing branches before a merge.
Example:
[{
"enabled": true,
"repositories": "*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchNames": ["main"]
},
"from":
{
"branchNames": ["QUAK-*"],
}
}]
This (enabled) rule applies to all repositories and forces all branches named QUAK-* to be
reviewed prior to be merged to main.
In the diagram below, only branch QUAK-001 will merge to the main branch:
If a merge can't happen, you'll receive an error like this:
Cannot perform the merge. Review the branch '/main/QUAK-002' to merge it to '/main'.
'restrict_merges_to_branch' rule
Definition
Restricts merges to a given branch. This way, the merges to that branch can only come from a given set of branches.
You can specify rules that apply to groups of branches too.
Example:
[{
"enabled": true,
"repositories": "codice",
"rule": "restrict_merges_to_branch",
"to":
{
"branchNames": ["/fix3.0"],
},
"from":
{
"branchNames": ["fixes-*"],
}
}]
In repository codice, merges to branch /fix3.0 are only allowed from branches named
fixes-*. (you can use wildcards).
In the diagram below, branches /fix-3.0/fixes-089 and /fix-3.0/fixes-090 will merge to
fix-3.0:
'only_allow_merges_from_parent' rule
Definition
Only allows merges to a given branch that come from its parent.
This is very useful to enforce that certain branches only allow to be rebased from the parent, and won't accept
changes from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4
streams implement something very similar to restrict the flow of changes among streams.
Example
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_parent",
"to":
{
"branchNames": ["task*"],
}
}]
In repositories named like game*, branches with name task* can only receive merges from
their parent branch. This way you can prevent merges across different task branches.
In the diagram below, branch task001 will receive merges from main, and branch
task003 will receive merges from dev-002:
'only_allow_merges_from_children' rule
Definition
Only allows merges to a given branch that come from its child branches.
This is very useful to enforce that certain branches only allow merges from the children, and won't accept changes
from any other branch. If you have a Perforce background, you will be familiar with the concept, since P4 streams
implement something very similar to restrict the flow of changes among streams.
Example:
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_children",
"to":
{
"branchNames": ["iteration*"],
}
}]
In the repositories with the name game*, branches with the name iteration* can only receive
merges from their child branches.
In the diagram below, /main/iteration-32/task23 can be merged into /main/iteration-32,
but it cannot be merged into /main/iteration-15, as it is not a child of that branch:
Filtering
To filter the branches involved in a rule, you can use the branch name, the branch attribute, or both:
-
Filtering by name: Use the
branchNames
key to specify the branch names. For
example:
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchNames": ["main"]
},
"from":
{
"branchNames": ["scm*"],
}
}]
-
Filtering by attribute: Use the
branchesWithAttribute
key to filter by
attribute by specifying the attribute name and/or a value. For example:
[{
"enabled": true,
"repositories": "*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchesWithAttribute": [
{
"attribute": "merge_only_reviewed",
"value": "enabled"
}
]
},
"from":
{
"branchesWithAttribute": [
{
"attribute": "task",
}
]
}
}]
-
Filtering by name and attribute: Combine the above filters to filter by branch name and
attribute. For example:
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_parent",
"to":
{
"branchNames": ["scm*"],
"branchesWithAttribute": [
{
"attribute": "restricted_rebases",
"value": "yes"
}
]
}
}]
or:
[{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchesWithAttribute":
[
{
"attribute": "merge_only_reviewed"
}
]
},
"from":
{
"branchNames": ["scm*"],
}
}]
Managing the Merge Rules
The merge rules are stored in the mergerules.conf
file in the server
directory (where plasticd.exe
is located). This is a JSON file that contains your
configured merge rules.
The merge rules in this file must be placed inside an array [].
The following is an example of a mergerules.conf
file with two merge rules:
[{
"enabled": true,
"repositories": "code*",
"rule": "only_allow_merges_if_reviewed",
"to":
{
"branchNames": ["main"],
"branchesWithAttribute": [
{
"attribute": "merge_only_reviewed",
"value": "enabled"
}
]
},
"from":
{
"branchNames": ["scm*"],
"branchesWithAttribute": [
{
"attribute": "task",
}
]
}
},
{
"enabled": true,
"repositories": "game*",
"rule": "only_allow_merges_from_parent",
"to":
{
"branchNames": ["scm*"],
"branchesWithAttribute": [
{
"attribute": "restricted_rebases",
"value": "yes"
}
]
}
}]
You will find a mergerules.conf
file with some examples in your server
directory, inside config_samples
, alongside the binaries for clean setups (on Windows
using the installer, and GNU/Linux using the official packages) so you can directly modify it.
-
mergerules.conf
:
To configure your merge rules, you can directly edit the mergerules.conf
file in your
server
directory.
Tip: You don't need to restart the server for changes to take effect!
-
Merge Rules section in the WebAdmin:
You can manage your Merge Rules from the WebAdmin. You can select and configure the ones that fit your needs
best.
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:
Chapter 20: Plastic .NET Core server
The Plastic SCM server runs .NET Core, the cross-platform, rock-solid, super-fast and officially
supported framework.
Note:The Plastic .NET Core Server is available for Linux, macOS, and Windows beginning with version
8.0.16.4017.
The WebAdmin, WebUI, and mergebots features for Plastic .NET Core Server are available since
version 8.0.16.4024.
The benefits of the Plastic .NET Core server:
-
Much faster on Linux and macOS.
-
Much faster SSL on Linux and macOS.
-
Linux integration with systemd.
Configuring the network with network.conf
If you've been using Plastic for a while, you'll definitely be familiar with
remoting.conf
, the configuration file to
define the ports to listen,
the SSL certificate,
and a few others settings.
This configuration has been redesigned. This way, the .NET Core server uses a configuration file named
network.conf
.
Important! The network.conf
configuration file
applies to the Plastic .NET Core Server and replaces the remoting.conf
one.
Note: The Plastic .NET Core server converts remoting.conf
into
network.conf
on the fly if it finds one.
This is what a simple network.conf
looks like for a server listening
on 8084, and then on 8088 and 8787 using SSL:
[
{
"Port" : 8084,
"Type" : "Tcp",
"Security" : "None"
"RejectRemoteRequests" : true,
},
{
"Port" : 8088,
"Type" : "Tcp",
"Security" : "Ssl",
"SslPfxFile" : "plasticscm.com.pfx",
"SslPfxFilePassword" : "xxxxxxxxxxxxxxxxxxxxxx",
"ReceiveTimeoutMsec" : 2000,
"SendTimeoutMsec" : 2000,
"ReceiveBufferSizeBytes" : -1,
"SendBufferSizeBytes" : -1
"BindTo" : "162.165.0.1"
},
{
"Port" : 8787,
"Type" : "Tcp",
"Security" : "Ssl",
"SslPfxFile" : "plasticscm.com.pfx",
"SslPfxFilePassword" : "xxxxxxxxxxxxxxxxxxxxxx",
"ReceiveTimeoutMsec" : 2000,
"SendTimeoutMsec" : 2000,
"ReceiveBufferSizeBytes" : -1,
"SendBufferSizeBytes" : -1
}
]
Most of the settings are optional. A network.conf
like this is
also valid:
[
{
"Port" : 8084,
},
{
"Port" : 8088,
"Security" : "Ssl",
}
]
In the above example, this configuration will make the server listen on port 8084 without
security, and then on 8088 with SSL, autogenerating a self-signed certificate the
first time it runs.
Reloading network.conf on-the-fly
One interesting thing of the network.conf
file is that it reloads
on-the-fly. For example, if you add a new port, the server starts listening on the new port
without restarting the existing ports. Only when it's mandatory, the server is restarted; for
example, when you change an existing port.
Suppose you have the following network.conf
file:
[
{
"Port" : 8085,
"Type" : "Tcp",
"Security" : "None",
"RejectRemoteRequests" : false
},
{
"Port" : 8088,
"Type" : "Tcp",
"Security" : "Ssl",
"SslPfxFile" : "ssl-certificate.pfx",
"SslPfxFilePassword" : "|SoC|2ogBDa8GmifTjC7UKp4KuoF0/jWYlXy2",
"ReceiveTimeoutMsec" : 4000,
"SendTimeoutMsec" : -1,
"ReceiveBufferSizeBytes" : 30000,
"SendBufferSizeBytes" : -1
}
]
You can add a new port. The system will reload the file and listen on the new port,
leaving the other two ports untouched. This means that the system doesn't restart the entire
network.
The reload system actually calculates diffs, so it knows what to do:
-
If you only change the socket settings (
ReceiveTimeoutMsec
,
SendTimeoutMsec
, SendBufferSizeBytes
,
ReceiveBufferSizeBytes
), the system simply sets the new properties and no
restart of the "socket server" is needed.
-
If you only change the SSL settings change, the system simply sets the
changes and no restart is required.
-
If you change a key property (like going from TCP to SSL, or changing the port), then the old
port is stopped and the new one added.
A key property is that kind of setting that require to "listen" again:
RejectRemoteRequests
, Type
, Port
, BindTo
,
and so on.
Last updated
March 17, 2022
The proxy is now part of the Plastic Server.
Read how to start the Plastic Proxy.
Learn how to
manage the Plastic Proxy service on Windows
.
Also learn how to
configure the Proxy server
and
configure the Plastic SCM clients
to use the proxy.
March 7, 2022
You can now use the plasticgui command to launch or configure the new Plastic GUI on macOS instead of
using the old macplastic command. This new Plastic GUI is now the default GUI for macOS. It is
cross-platform, includes a dark theme, and provides better syntax highlighting.
Read more about the new Plastic GUI
.
March 3, 2022
You can now use the plasticgui command to launch or configure the new Plastic GUI on Linux instead of
using the old gtkplastic command. This new Plastic GUI is now the default GUI for Linux. It is
cross-platform, includes a dark theme, and provides better syntax highlighting.
Read more about the new Plastic GUI
.
February 16, 2022
Updated the Minimun requirements section because Windows Vista is
no longer supported.
November 4, 2021
You can now configure
how often the Plastic server reloads the users and groups information
from the authentication provider.
October 19, 2020
Learn how to configure the network.conf
configuration file to start
working with the Plastic .NET Core Server.
September 14, 2020
You can configure the server by running
plasticd configure. (The clconfigureserver command is now deprecated.)
September 11, 2020
The webadmin supports HTTPS now!
Updated the reference to admin the password of the webadmin.
The old way of setting the webadmin password was to run the adminconsolepwd utility.
This tool has been deprecated and you should now use plasticd adminpwd.
September 10, 2020
Learn how to apply global rules to all repositories both by using the
webadmin or the
lock.conf file.
September 9, 2020
Included how to access the webadmin from Linux.
August 12, 2020
Fixed some examples about
configuring lock rules.
June 19, 2020
Fixed the LdapTimeoutSeconds
key name in the
LDAP authentication configuration
chapter. Before it was wrongly named as LdapTimeout
.
June 18, 2020
We added two new settings to configure the
LDAP authentication:
LDAP token expiration time and Override for LDAP user filter.
May 25, 2020
You can configure the maxcachessizeingb
and maxcachessizefreepercent
parameters in the
jet.conf file to specify the maximum amount of memory used by caches
.
March 19, 2020
We added a new setting blobspath
to
jet.conf to allow storing blobs and metadata in different paths
.
December 23, 2019
The Plastic Proxy now includes some features about monitoring space and cleaning cache up on disk:
October 31, 2019
filetypes.conf
is now used for diffs and merges to check if
a file is binary or text.
October 24, 2019
We included documentation about the mergerules.conf
configuration file and about how to configure your Merge Rules system.
October 24, 2019
October 2, 2019
Fixed a wrong text used when creating a self-Signed certificated on Linux and macOS systems.
March 22, 2019
We replaced the references to deprecated repository administration commands like cm mkrep for their new counterparts.
July 24, 2018
Learn how to configure the license auto-renewal option from the webadmin - Plastic SCM Server Administration console.
May 8, 2018
We highlighted some remarks about the Repository storage configuration, such as:
- Plastic SCM needs to create several databases on the database backend, so the credentials supplied need to be granted database creation permissions.
- What configuration values have to be changed by the user and what values cannot be changed.
February 16, 2018
The lock.conf
specification now indicates that the lockserver
parameter is optional.
January 29, 2018
Please check the .Net framework required version.
November 21, 2017
You can now configure the externaltools.conf
file to run external tools on Plastic SCM objects.
Learn how the eolconversion.conf
configuration file works.
October 24, 2017
Now, you can configure the Plastic SCM server from the webadmin - the new web based server administration console.
- The new web user interface will replace the old Windows-only admintool and configureserver and it is available on Linux and OS X. This way we close one long term request: cross-platform admin tool.
- webadmin also implements an interface to configure users and groups (users.conf and groups.conf) replacing the previous Windows-only umtoolgui.exe.
- webadmin provides not only a way to finely tune the server but also comprehensive documentation about what each parameter means and how to use it, and links to more information when needed.
September 26, 2017
The link required to download the Windows tools to create the Plastic SCM SSL Certificates is now updated.
September 13, 2017
We included the instructions to backup and restore the Jet backend.
Learn how to switch the Plastic SCM server between normal and read-only modes.
July 4, 2017
Learn how to configure Jet as your default storage backend.
June 09, 2017
Now, you can configure a timeout for LDAP requests.
June 01, 2017
Now, the Branch Explorer can be globally configured for all users.
May 19, 2017
Learn how to force clients to upgrade to a given version.
May 12, 2017
We updated some screenshots because we changed the repository-related dialogs replacing their server text boxes with a combo box containing a list of recently used servers.
February 24, 2017
Transformable workspaces, an advanced management feature for your workspaces.
February 21, 2017
Some commands related to the Plastic SCM server and client configuration are now updated.
Jan 24, 2017
The Server and Client installation, and Server and Client configuration processes have been improved. Some screenshots are updated.
Follow these steps to start working with Plastic SCM if it's the first time you install Plastic SCM in your machine.
December 17, 2016
The server aliases configuration file location has been fixed.
July 4, 2016
Find a list of the configuration files used by Plastic.
Read how to set up a global file configuration in the server so that all clients have the same settings by default.
June 27, 2016
The umtool commands have been updated.
May 10, 2016
The Plastic SCM installation chapter has been updated. Now includes the Plastic SCM installation and configuration in Linux and Mac OS systems.
The license autorenewal configuration chapter now includes the steps to follow when working in Linux or Mac OS systems.
November 5, 2015
The Plastic SCM Server and Client installation and configuration chapter has been updated.
September 7, 2015
Review the new minimum requirements in order to install and use Plastic SCM.
August 7, 2015
The auditing log documentation has been updated.
July 22, 2015
Updated documentation about the following commands to work with the Plastic SCM Server on Windows, Linux and Mac systems:
May 27, 2015
Follow the steps to configure your server to use the license autorenewal
March 27, 2015
Learn how to create a SQL Server database using the db.conf file
March 20, 2015
Included compression.conf file to choose a storage compression type
March 18, 2015
Updated lock.conf documentation. Added sample patterns
March 18, 2015
Learn how Plastic SCM supports alternative connections to the same server
February 25, 2015
How to create and use SSL certificates to be used with Plastic SCM