This guide describes the procedures associated with Plastic SCM installation and maintenance.
This guide is targeted to developers and system administrators, assuming familiarity with Plastic SCM and operating system concepts.
Online documentation
Besides this and the rest of the guides, Plastic SCM provides online reference throughout its different client frontends.
On the command line interface, both Windows and Linux, this reference can be obtained with the command:
cm help
For extended information on a specific command, type:
cm help command
The graphical interface provides online reference through the Help menu.
Documentation errors
If you find any problem in this guide or any other part of the online reference, please notify it using the following email address:
1. Introduction
Plastic SCM is a Software Configuration Management system designed to handle software development teams of any size.
Plastic SCM provides high-end SCM capabilities but doesn’t impose any of the restrictions associated to these high-end systems like complex installation, operation and administration.
This guide assumes that the reader is familiar with the basic SCM concepts, with basic operating system usage through the command line and basic system administration.
The guide will show to both system administrators and SCM managers how to install the SCM system, how to create repositories, workspaces and how to make backups.
Plastic SCM uses a client / server architecture, divided into the following components:
- The server, responsible for storing all the project information, managing client access to that store.
- Clients run on the developers’ machines, and are responsible for communicating user operations to the server. Basic supported clients follow:
- Command Line Interface (CLI): gives 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 window-oriented interface. It provides some graphical diagrams not available in the command line.
- Visual Studio integration: provides access to the most used operations like checkout / checkin from within the development environment.
- Eclipse integration: provides access to the most used operations like checkout / checkin from within the Eclipse development environment.
Figure 1: Structure and Plastic SCM's components
The following table shows the platforms supported for the system’s components:
|
Component |
MS Windows |
Linux |
Mac OS X |
Solaris 10 |
|
Server |
X |
X |
|
|
|
CLI client |
X |
X |
X |
X |
|
GUI client |
X |
|
|
|
|
Visual Studio client |
X |
|
|
|
|
Eclipse client |
X |
X |
|
|
2. Minimum requirements
Below you will find the minimum requirements, both hardware and software, needed to install and use Plastic SCM.
The minimum system requirements to run the Plastic server are:
- Windows 2000 Server, Windows 2000 Professional, Windows 2003 Server or Windows XP SP 2 Operating Systems. Server operating system strongly recommended.
- .NET Framework 1.1 or higher.
- 512 MB RAM.
- Enough free hard disk space. Hard disk space will vary depending on the size of project’s assets.
Client machine requirements will vary depending on the Plastic SCM client in use. The GUI or IDE integrations will have higher requirements than the command line one.
The supported operating systems are:
· Windows 2000 Professional or Windows 2000 Server.
· Windows 2003 Server.
· Windows XP SP2.
· Fedora
· Ubuntu
· RedHat
· Suse
· Debian
In all cases, the.NET Framework 1.1 or higher is required.
The needed RAM will vary depending on:
- Command line client: is the thinner one and needs few resources to work. Nevertheless, as general rule, a 512 Mb RAM machine is strongly recommended.
- GUI client: 512 MB RAM
- Visual Studio Plug-in: same requirements as the IDE.
- Eclipse Plug-in: same requirements as the IDE.
3. Plastic SCM installation
One of the development team’s main goals was creating a system which is easy to install, configure and use. Installation is a straightforward process.
Plastic SCM server works as a Windows service. The service is registered and started (if start option is selected) during the installation process. So having enough rights to register a new service is mandatory to make a successful installation.
Plastic SCM is distributed as a unique installation file. During installation it is possible to choose between server or client installation, or both, selecting the right options in the component list.
The installation steps are described in detail in Table 1.
|
Select the installation language |
Figure 2. Language selection |
|
Installer start screen |
Figure 3. Installer start up |
|
License agreement. Read the license carefully and click on accept if you agree to the terms. |
Figure 4. License agreement |
|
Choose the installation directory. Select the directory in which Plastic SCM will be installed. Two subdirectories will be created inside this directory: one for the server and one for the client. |
Figure 5. Installation directory |
|
Component selection. Plastic SCM is divided into several components. In this screen user can choose the ones he needs to install on the machine. |
Figure 6. Component selection |
|
Ready to install. At this point the installer has all the information it requires to run. As no file or directory has been created on your disk, this is a good opportunity to abort the installation, if necessary. |
Figure 7. Ready to install |
|
File copy progress.
|
Figure 8. Copying files |
|
System configuration. Once the installation has been completed, the installer will launch, if the user selects the options, the different configuration programs. |
Figure 9. Start system configuration |
Table 1. Installation steps
The server configuration wizard can be started at the last step of the installer, or from Plastic SCM start menu entry.
|
Server configuration start up screen. |
Figure 10. Server configuration welcome screen |
|
Select the server’s language. It will be used for the log messages or errors. Clients and server can have different languages. Clients will get messages localized in their own configured language. |
Figure 11. Server configuration language selection |
|
Authentication mechanism. This is the most important step in the server configuration wizard. Here you have to choose between the different authentications mechanisms available. By default local users is selected. A detailed explanation about security modes is done at 3.4. |
Figure 12. Server configuration authentication modes |
|
If you choose the LDAP user security mode, you will have to fill in some more parameters. You have to specify the LDAP server name, and the domain from which data must be retrieved. Also a username and a password to be used to access the LDAP server. Finally choose whether the LDAP server is a conventional LDAP one or an Active Directory. |
Figure 13. LDAP Authentication configuration |
|
The last step is configuring the server’s port number. A default port is proposed. Remember that if you change the server’s port, you will need to install the clients setting this new port. |
Figure 14. Port configuration |
Table 2. Server configuration
Four authentication mechanisms are available:
Local users
- Local users (Name + ID)
- Active Directory integrated security
- LDAP authentication
Each of them allows different authentication possibilities and will be detailed in the following sections.
3.4.1. Authentication basics
Client communicates certain security information to server in order to be validated. The basic token sent from client to server is called SEID, the short for SEcurity IDentifier.
The mechanisms to be described are basically based on different ways to build the SEID plus different ways to obtain users.
3.4.2. Local users
Local users means 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 clients must also be configured using the Local Users mechanism.
The client will take the name of its logged on user and send it to the server. This is the name that the server will use to first check whether it is a known user, and then make security calculations with.
This system heavily resides on correct network configuration. If a network is misconfigured it can have security flaws and it would be possible to cheat the server with identity hijacking.
It can be used on secured networks to easily configure a mixed Unix / Windows environment, relying, for instance on a NIS+ system.
It can also be used for easily configuring access from the Internet, provided that the server only allows trusted clients to connect.
|
How does the server obtain the user list? |
It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it’s not a local user. |
|
How is the SEID built? |
Just with the user name. |
3.4.3. Local users: name + ID
The mechanism is identical to local users but the SEID is built using both the user name plus the user ID.
It is a very simple way to prevent, or at least complicate a bit further, identity hijacking.
Under Windows systems the ID will be the SID of the user.
Under Unix based systems it will be the user id.
It works perfectly on non-cross-platform environments (Unix-Unix or Windows-Windows) but it will obviously break under Windows-Unix platforms unless a specific authentication mechanism is in place.
It can be used to work under NIS+ systems on Unix, or under any other configuration provided that both systems share the same user name and ID.
|
How does the server obtain the user list? |
It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it’s not a local user. |
|
How is the SEID built? |
User name + ID: user id on Linux and SID on Windows. |
3.4.4. Active Directory Integrated Security
Using this configuration mechanism user list will be retrieved from the current active directory server. This system needs the server to be running inside an operating system that can be part of an Active Directory. It is designed to be run on Windows based operating systems.
|
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. |
3.4.5. LDAP
The LDAP security configuration mechanism allows interoperability with an LDAP environment.
It can be used to authenticate users against any kind of LDAP server. A Sun One or iPlanet LDAP Server can be used, for instance, to authenticate Plastic SCM users.
It can also be needed on mixed Windows / Unix Active Directory environments. The server can be configured to work with Active Directory Integrated Security, and Unix clients can authenticate against Active Directory using LDAP.
|
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. |
3.4.6. User/Password
The user/password authentication system introduces an easier way to configure Plastic user and group based authentication in certain environments. When LDAP, Active Directory and local server users are not an option, the system administrator can select user/password authentication.
When using UP (short for user/password authentication) the Plastic security system works exactly as it would do with LDAP, Active Directory or any other mode, the only difference is how the users, groups, their relationships and the passwords are stored.
When working in UP mode the administrator will define users, groups and their relationships using a specific Plastic configuration tool, then the client will just have to specify the previously configured user and password to log in the Plastic server.
UP working 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 server on heterogeneous environments where the built-in operating system’s authentication mechanism doesn’t match.
To configure the login and password the user must run the Plastic configuration wizard as shown on the following figure.
Figure 15: User and password configuration screen
On Plastic GUI client start up if the user and password are not correctly set, the login screen will pop up.
Figure 17. Login dialog
The main difference between UP and the other authentication systems is that instead of relying on an external user and group provider, the UP authentication mode stores all its data into two files: users.conf and groups.conf.
- users.conf: stores information about all the users and their encrypted passwords.
- groups.conf: stores all the available groups and the users they contain.
Figure 18. Involved configuration files in UP mode
Configuring user/password authentication mode
In order to configure the UP mode you’ll use the following tools:
- The server’s configuration tools (configureserver or clconfigureserver) to set the authentication mode the server has to use.
- The client’s configuration tools (plastic --configure or the configuration wizard) to specify the authentication mode to communicate with the server.
- umtoolgui or umtool to configure the users, groups, and their relationships both graphically and from the command line.
Selecting the UP authentication mode
To select the UP authentication mode both the clients and the server must be configured accordingly.
Plastic users can run both the server’s configuration wizard (configureserver executable) and the client’s configuration (plastic --configure) to set the UP authentication mode as described on the figure below.
umtoolgui
umtoolgui is the GUI tool to configure the users, groups and their relationships and passwords. The tool is located on the server’s directory.
The following figure describes all the umtoolgui functionalities. It is a very simple and intuitive tool which solely purpose is to help users configure the users.conf and groups.conf files.
The tool is able to create users and groups, assign users and groups to a specific groups, change user’s password, rename users and groups and delete them.
Figure 19. umtoolgui functionality umtool
umtool is the command line tool used to configure the users, groups and their relationships and passwords from the operating system’s console.
umtool implements several commands detailed on the following table.
|
Command name |
Short name |
Description |
Syntax |
|
addgrouptogroup |
agtg |
Include a new group into a group |
umtool addgrouptogroup <grouptoadd> <groupname> |
|
addusertogroup |
autg |
Include a new user into a group |
umtool addusertogroup <username> <groupname> |
|
changeuserpassword |
cup |
Change a user’s password |
umtool changeuserpassword <username> <oldpassword> <newpassword> |
|
creategroup |
cg |
Create a new Plastic SCM group |
umtool creategroup <groupname> |
|
createuser |
cu |
Create a new Plastic SCM user |
umtool createuser <username> <password> |
|
deletegroup |
dg |
Delete a existing Plastic SCM group |
umtool deletegroup <groupname> |
|
deletegroupfromgroup |
dgfg |
Delete a group from a group |
umtool deletegroupfromgroup <grouptodelete> <groupname> |
|
deleteuser |
du |
Delete a existing Plastic SCM user |
umtool deleteuser <username> |
|
deleteuserfromgroup |
dufg |
Delete a user from a group |
umtool deleteuserfromgroups <username> <groupname> |
|
help |
hlp |
Show a command’s help |
umtool help <commandname> |
|
listgroupmembers |
lgm |
Show a list with members of a group |
umtool lgm <groupname> |
|
listgroups |
lg |
Show a list with current Plastic SCM groups |
umtool lg |
|
listusers |
lu |
Show a list with current Plastic SCM users |
umtool listusers |
|
renamegroup |
rg |
Rename a existing Plastic SCM group |
umtool renamegroup <oldgroupname> <newgroupname> |
|
renameuser |
ru |
Rename a existing Plastic SCM user |
umtool renameuser <oldusername> <newusername> |
users.conf file format
The users.conf file contains the definition of the users known to the system in UP authentication mode. The format of the users.conf file is very simple: it contains a list of the available users followed by their passwords as shown on the figure below.
Figure 20. users.conf file format
groups.conf file format
The groups.conf file contains all the groups known to the Plastic system in UP mode. The file is a list of the groups each one followed by the names of the users or groups it contains. Check the following figure for details.
Figure 21. groups.conf file format
Setting server’s UP working mode modifying server.conf
After the server’s working mode is set, it will be stored on the configuration file named server.conf.
The server.conf file can be manually modified to choose a different authentication mode. To set the UP working mode use the workingmode value specified in the figure below.
Figure 22. server.conf contains WorkingMode
UP mode common questions
|
How does the Server build the list of users?
|
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. |
Table 1. UP common questions
This is the traditional authentication method; it allows Plastic SCM users to define their own users and groups on the Plastic server. This way Plastic works with an autonomous security mechanism, which could be the best option for many organizations which don't rely on systems like LDAP or Active Directory.
The 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. Each client sets a user and a password in order to have access to the server, the user must exist on the server and the password must be the same one.
The list of