StarTeam SDK Connection Control

The StarTeam Server allows administrators to fine tune the set of client applications that can connect to the server by customizing a new app-control.xml file. This feature prevents unwanted SDK applications from connecting to the StarTeam Server and draining resources.

Note: This is strictly an administrative tool, not a security measure.

app-control.xml Configuration File

The StarTeam Server looks for a configuration file named app-control.xml located in the AppControl directory under the StarTeam repository root directory. When a new configuration is created, StarTeam Server creates this file from a template app-control.xml file located in AppControl directory under the StarTeam Server installation directory.

The configuration app-control.xml file, if present, contains a set of rules. Each rule asks the server to test the incoming client connections to satisfy one or more of the following conditions:

  • The StarTeam SDK is greater than or equal to a certain version.
  • The application name, connecting user name/client workstation, name must match a specified text pattern.

The StarTeam Server tests each incoming client connection against all the rules present in the app-control.xml file until a match is found or until the rule list is depleted. Once a match is found, no more checks are done and the connection handshake sequence is resumed. If no match is found, the connection is refused. If the app-control.xml file does not exist in the AppControl directory, the StarTeam Server allows all supported client applications to connect.

app-control.xml Structure and Rule Syntax

The root XML element must be named StarTeamApplications and have a version attribute with a value equal to 1.0. For example, <StarTeamApplications version="1.0">

The server recognizes the following elements directly under the root node:

AppDefault

AppDefault: This is an optional element that can be used to specify default values for one of the parameters listed under AllowedApp. The syntax of this element is similar to the AllowedApp syntax, except that the Name attribute cannot have a default value. Default values can be specified for MinimumSDKVersion, WorkStationID, and UserName.

AllowedApp

This is the main rule element. It must have a Name attribute that specifies the text pattern for the client application name (such as “client identification string”). The text pattern can have an asterisk character (‘*’) that is used as a wildcard. If an optional parameter is not set, the StarTeam Server does not test the corresponding connection attribute.

Besides the Name attribute, this node can optionally specify one or more of the following attributes:

MinimumSDKVersion
Specifies a minimum version of StarTeam SDK with which the client application is built. The format of this field is nn.nn.nn.nn, where nn is a non-negative number. Not all of the “dot” numbers have to be specified, for example MinimumSDKVersion=”10.4” will allow 10.4.x.y and above (10.5, 11.0, and so on).
WorkStationID
If set, specifies text pattern to match the client computer name.
UserName
If set, specifies text pattern to match the StarTeam user name.
BlockedApp
The BlockedApp element provides the ability to block a specific application. It must include the Name attribute.

For BlockedApp there are 4 recognized attributes: Name, SDKVersion, WorkStationID and UserName.

  • Attributes Name, WorkStationID and UserName can contain a specific string to be compared with, or a string with an asterisk ("*"). The asterisk in the string will match a pattern in that string.
  • Attributes WorkStationID and UserName can be empty or not specified at all. This will block any WorkStationID or any username.
  • Missing attributes other than Name, will either use values from AppDefault attributes if they exist or will assume the value "*".

Attribute SDKVersion corresponds to the SDK version to block and has a specific format. It is composed of four-part dot-noted positive numbers "1.2.3.4". This attribute specifies the SDK version to block. If any of the parts are skipped, any version for that part will be blocked. For example: 

SDKVersion="10" will block 10.1.0.0 but will not block 9.10.5.0
SDKVersion="10.4.50.0" will not block the SDK version specified
SDKVersion="11.4" will block 11.4.5.0 or 11.4.1.0 but will not block 11.3.0.0

Examples

<AppDefault MinimumSDKVersion="11" /> 
            ## defaults to accepting any SDK version with first part 11 or greater
<AppDefault WorkStationID="*" />   
            ## default accepts any WorkstationID. Not specifying a default accepts any value as well.
<AllowedApp Name="Bulk Checkout Utility" WorkStationID="build-*"/>  
            ## Accepts the application with specific string "Bulk Checkout Utility" 
            ## and matching specified worsktation pattern and default patterns for other attributes
<AllowedApp Name="CPC*" MinimumSDKVersion="8.0" /> 
            ## Accepts application starting with pattern CPC with minimum version first part 
            ## of 8.0 or greater and that matched other default pattern
<AllowedApp Name="CPC 10.4.1-a" WorkStationID="americas*" /> 
            ## Accepts application with specific Name 
            ## and should match the specified workstation pattern and other default patterns
<AllowedApp Name="*" UserName="Administrator" />    
            ## Accepts any application if login name is "Administrator"
<BlockedApp Name="CPC*" SDKVersion="10.0" /> 
            ## Blocks an application starting with pattern CPC with matching SDK version version 10.0.*.*
Parent topic: Configuring the Server