Creating a configuration file using a text or XML editor

This section is intended for ADM administrators.

The configuration file is an input file in XML format in which the ADM administrator defines the configuration. In principle, you can create the file on any system using a text editor. It is, however, advantageous if you work on the (future) remote administration server and use an XML editor, for instance, the free XML editor "XML Notepad 2007" from Microsoft. If you do this, you can use the supplied template, complete with schema so that your entries are immediately checked. See section “Creating a configuration file using a text or XML editor”.

Describing the configuration data in XML format provides a simple way to represent a complex configuration clearly by forming groups.

In the configuration file, you define:

• the configuration, see section “Creating a configuration file using a text or XML editor”,

• the remote administrators, see section “Creating a configuration file using a text or XML editor”,

• the openFT instances and groups of instances to be administered by these remote administrators, see section “Creating a configuration file using a text or XML editor”,

• the remote administration permissions that the remote administrators have on each of the openFT instances (access list), see section “Creating a configuration file using atext or XML editor”,

• the encoding mode for ftadm commands, see section “Creating a configuration file using a text or XML editor”.

The ADM administrator must then import the configuration file into the remote administration server using the ftimpc command. See section “Importing the configuration”. The ftexpc command allows you to create an XML file from the internal configuration data again at any time, in order to modify the configuration, for instance.

The structure of the XML file is described in the following sections. An exhaustive example is given in the section “Example of an XML configuration file”.

Using the XML template and XML schema

The directory samples/ftadm (Unix systems) or samples\ftadm (Windows systems) under the openFT installation directory contains the file config.xml, which contains a simple sample configuration that can be used as a template and adapted appropriately.

The schema on which the XML file is based is defined in the file config.xsd, which is located in the include directory of openFT after installation. If you are using an XML editor, you can use the file config.xml as the basis for your work. The installation path of the schema file config.xsd is entered in this file. This means that the XML editor uses this schema in order to immediately verify your entries. If config.xsd has been copied elsewhere or renamed, you must adjust the installation path of config.xsd in config.xml.

Defining the configuration

The configuration file contains precisely one configuration for a remote administration server. It is structured hierarchically, i.e. child elements are nested inside a parent element.

A configuration starts with the XML tag <Configuration> and comprises the following attributes:

• Mandatory attribute Version. The value of the attribute Version is a string that specifies the version of the configuration data. The maximum length of the string is 4 bytes. In openFT V12.1, "1210" must be specified for the version.

• Optional attribute Description. The value of the attribute Description is a string that describes the configuration data in more detail. The maximum length of the string is 100 bytes.

Example:

<Configuration
   Version="1210"
   Description="Configuration for central server MCHSRV01">
   <...
   .../>
</Configuration> 

Elements of a configuration

A configuration contains the following elements:

• At least one administrator ID element with the tag <AdministratorID> for defining a remote administrator. You can define up to 100 remote administrators. For a detailed description, refer to the section “Creating a configuration file using a text or XML editor”.

• Optional access list element with the tag <AccessList>. You use an access list to define the administration permissions on the openFT instances for the individual remote administrators. For a detailed description of the access list, refer to the section “Creating a configuration file using a text or XML editor”.

• Optional group elements with the tag <Group>. Groups can be nested, thus allowing the geographical or organizational structure of a company to be represented, for instance. The maximum nesting depth is limited. See the note in section “Creating a configurationfile using a text or XML editor”. For a detailed description of a group, refer to section “Creating a configuration file using a text or XML editor”.

• At least one instance element with the tag <Instance> for the openFT instances. You can define up to 5000 instances. For a detailed description of an instance, refer to section “Creating a configuration file using a text or XML editor”.

A pathname is formed from the name of the instance and the name of the group (where appropriate with subgroups) according to the following pattern:

group/subgroup1/subgroup2/.../instance

The remote administrator must enter precisely this pathname in a remote administration request to the instance. See also section “Remote administration using the command interface”.

This pathname can be a maximum of 200 characters long. The maximum number of subgroups therefore depends on the lengths of the individual names.

Defining remote administrators

In the configuration file, you specify which remote administrators are permitted to perform remote administration. To do this, proceed as follows:

• Define one or more remote administrators

• Assign each remote administrator a profile name and/or a user ID on the remote administration server.

A remote administrator is defined using the XML tag <AdministratorID>. You can enter a maximum of 100 remote administrators in the XML file. The <AdministratorID> tags must be defined immediately following the <Configuration> tag, because the subsequent definitions for the groups and instances reference them.

<AdministratorID> has the following attributes:

• Mandatory attribute Name. The value of the attribute Name is a string that specifies the name of the remote administrator. The maximum length of the string is 32 bytes. The name must be unique, i.e. the configuration file must not contain any other <AdministratorID> tags with the same name. The name is used both internally in the configuration data and externally in log records in order to uniquely identify the initiator of a remote administration request.

• Optional attribute Description. The value of the attribute Description is a string that describes the remote administrator in more detail. The maximum length of the string is 100 bytes.

• Optional attributes UserID and Profile. These attributes identify the remote administrator depending on the type of access to the remote administration server. You must therefore specify a least one of the two attributes UserID or Profile. It is also possible to enter both attributes.

  The following applies to UserID and Profile:

  • The value of the UserID attribute is a string with the name of a valid login ID on the remote administration server. The maximum length of the string depends on the platform and can be up to 36 bytes.

    The user that logs in on the remote administration server locally under this ID is therefore a remote administrator and possesses the administration permissions granted to this AdministratorID. A particular login ID must therefore only be specified for one AdministratorID, otherwise the correlation between the user ID <-> remote administrator is no longer unique.

  • The value of the Profile attribute is a string with the name of a valid FTAC profile. The maximum length of the string is 8 bytes. The ADM administrator of the remote administration server must be the owner of the profile. Each FTAC profile name may only be used with exactly one AdministratorID.

    This profile is used if the remote administrator issues a remote administration request on a remote computer and sends it to the remote administration server using the FTADM protocol. In this event, the remote administrator must specify the associated transfer admission in the request.

    The profile must include the function ACCESS-TO-ADMINISTRATION (corresponds to ftcrep -ff=c) See section “Setting up admission profiles for accessing the remote administration server”.

Example:

<Configuration
   Version="1210">
   <AdministratorID
        Name="John"
        Description="Domain Controller Administrator"
        UserID="rz\John"
        Profile="Profile01"/>
   <AdministratorID
        Name="Fred"
        Profile="Profile02"/>
   <...
          .../>
</Configuration>

Defining groups and openFT instances to be administered

The configuration file contains all the openFT instances that can be administered via this remote administration server using the remote administration facility.

Defining groups

By defining groups and subgroups with freely selectable names, it is possible to organize the openFT instances that are to be administered in a way that meets your precise requirements. When groups are formed, the path of an instance is made up of the Name attributes of the parent groups and the instance in question, e.g. Muenchen/MCH1/OPENFT01. The complete pathname must not exceed a total length of 200 bytes. The maximum nesting depth therefore depends on the lengths of the individual names.

A group starts with the XML tag <Group>. There is no limit to the maximum number of groups in the XML file. The groups must be defined after the remote administrators in the XML file, because the subsequent definitions for the groups and instances reference the remote administrators.

A group is made up of the following attributes:

• Mandatory attribute Name. The value of the attribute Name is a string that specifies the name of the group. The maximum length of the string is 24 bytes and it may not contain a slash (/). The name could, for instance, be the name of a town, a branch office or a department, or it could simply be the description of the functions of a group of openFT instances.

• Optional attribute Description. The value of the attribute Description is a string that describes the group in more detail. The maximum length of the string is 100 bytes.

The following elements can be assigned to a group:

• Optional access list element with the tag <AccessList>. You use the access list to define for the individual remote administrators the remote administration permissions on the openFT instances that belong to this group and to any subsequent child groups. For a detailed description of the access list, refer to section “Creating a configuration file usinga text or XML editor”.

• Optional group elements with the tag <Group>. You can specify any number of groups. By specifying further nested groups, it is possible to represent the relationships between the groups hierarchically. In this event, the total path length must not exceed 200 bytes. See the note in section “Creating a configuration file using a text or XML editor”.

• Optional instance elements with the tag <Instance> for the openFT instances that belong to this group. You can define up to 5000 instances in a single configuration.

Specification of the group and instance elements within a group is optional, but a group must contain at least one further group or one instance.

Example:

<Configuration
   ...>
   <AdministratorID
           .../>
   <Group
          Name="Muenchen"
          Description="Computer Center Muenchen">
       <Group
          Name="MCH1"
          Description="Computer Center Muenchen Schwabing">
          <AccessList>
             <AccessEntry
                .../>
          </AccessList>

          <Instance
             Name="MCHSRV01"
            ... />
          <Instance
             Name="OPENFT01"
            ... />
       </Group>
       <Group
          Name="MCH2"
          Description="Computer Center Muenchen Freimann">
            ...
       </Group>
        ...
   </Group>
   ...
</Configuration>

Defining instances

An openFT instance starts with the XML tag <Instance>. You can define a maximum of 5000 instances in the XML file.

An instance can be assigned to a group or defined independently of a group. You must observe the following assignment hierarchy:

• With group(s):

  Configuration

  Remote administrator(s)

  Optional access list

  Group(s):

  Optional access list

  Instance

  Optional instance-specific access list

• Without group:

  Configuration

  Remote administrator(s)

  Optional access list

  Instance

  Optional instance-specific access list

You will find detailed information on the access list in section “Creating a configuration file using a text or XML editor”.

An instance is made up of the following attributes:

• Mandatory attribute Name. The value of the attribute Name is a string that specifies the name of the openFT instance. The maximum length of the string is 24 bytes and it may not contain a slash (/). The name of the instance can be freely selected.

• Optional attribute Description. The value of the attribute Description is a string that describes the instance in more detail. The maximum length of the string is 100 bytes.

• Mandatory attribute Address. The value of the attribute Address is a string with a maximum length of 200 bytes that specifies the address of the openFT instance to be administered. You can specify the name from the partner list or enter the address directly.

  The address format of the administered openFT instance depends on its version:

  • openFT as of V11.0:
    The address must have the protocol prefix ftadm: //, i.e. it must be entered with this prefix in the partner list or the prefix must be specified here. If this is not done, the openFT instance will be administered as an openFT instance < V11.0 using ftexec.

  • openFT < V11.0:
    The address must have the standard format, i.e. it must be entered without a prefix in the partner list or the prefix must not be specified here. You must also set the Mode attribute to the value "Legacy". See below.

• Mandatory attribute Admission. The value of the attribute Admission is a string containing the FTAC transfer admission. The maximum length of the string is 36 bytes (67 bytes if specified in hexadecimal format). An admission profile with this transfer admission must be defined in the openFT instance to be administered. Depending on the version of the instance to be administered, this profile must permit the following function(s). See the section “Configuring an openFT instance to be administered”:

  • openFT as of V11.0:
    REMOTE-ADMINISTRATION (corresponds to ftcrep ... -ff=a)

  • openFT < V11.0:
    TRANSFER-FILE + FILE-PROCESSING (corresponds to ftcrep ... -ff=tp)

  If there are separate FT and FTAC administrators in the openFT instance that is to be administered then enter one of the two transfer admissions (for the FT administrator or FTAC administrator) for the Admission attribute. If necessary, you may have to create a second instance with the other transfer admission.

• Optional Attribute Mode. The string "Legacy" can be specified for the Mode attribute. This means that the openFT instance is an instance < V11.0 that can only be administered using ftexec. In this case, no protocol prefix ftadm: // is allowed to be specified in the partner address.

• Optional Attribute DataEncryption. The string "Yes" can be specified for the DataEncryption attribute. This means that the user data exchanged between the remote administration server and the openFT instance to be administered is transferred in encrypted form. If the DataEncryption attribute is missing, the user data is not encrypted when it is transferred.

  DataEncryption="Yes" can only be specified if openFT-CR is installed both on the remote administration server and on the instance that is to be administered.

An instance can contain the following element:

• Optional access list with the tag <AccessList>. The access list allows you to define nonstandard permissions for individual remote administrators that only apply to this instance. You can extend or restrict the inherited permissions or deactivate inheritance and specify other permissions. For a detailed description of the access list, refer to the section “Creating a configuration file using a text or XML editor”.

Example:

...
   <Group
       Name="MCH1"
       Description="Computer Center Muenchen Schwabing">
       <AccessList>
          <AccessEntry
              .../>
       </AccessList>
       <Instance
          Name="MCHSRV01"
          Description="Remote administration server"
          Address="ftadm: //MCHSRV01.mch.mycompany.net"
          Admission="mchsrv01remote"/>
       <Instance
          Name="OPENFT01"
          Description="Windows 7"
          Address="ftadm: //OPENFT01.mch.mycompany.net:11009"
          Admission="openft01remote">
          <AccessList>
             <AccessEntry
              .../>
          </AccessList>
       </Instance>
   </Group>
...

Defining an access list

In the access list, you specify which remote administrators have access to the given openFT instance to be administered and what remote administration permissions are granted to each of the remote administrators.

The following rules apply:

• An access list can be defined at the following locations:

  • before all groups and/or instances. The list then applies to all subsequent groups and/or instances provided that separate access lists have not been defined for these.

  • as an element of a group. The list then applies to all openFT instances that belong to this group and is inherited by all child groups.

  • as an element of an openFT instance that is to be administered. The list then only applies to this instance.

• Every openFT instance that is to be administered requires an access list that is either defined explicitly with the instance or that is inherited from parent elements (associated group, parent group or an access list defined before all groups/instances).

  An openFT instance without an access list (access lists) that has been either explicitly set or implicitly inherited cannot be administered.

• You can explicitly control the scope of inheritance in an access list of a child group or for an openFT instance:

  • You can deactivate inheritance using the optional attribute InheritFromParent. In this event, you must define a separate access list for this instance in which you specify the administration permissions for the remote administrators.

  • You can expand or restrict inherited permissions for particular remote administrators (AllowFunction and DenyFunction attributes under
    <AccessEntry>). Entries which deny a function to a specific remote administrator take priority over entries that permit a function for a specific remote administrator. Additional entries in access lists for groups are also inherited by child groups.

Elements of an access list

An access list starts with the XML tag <AccessList>. There is no limit to the maximum number of access lists in the configuration file. The access list can be defined at different places in the file. See section “Creating a configuration file using a text or XML editor”.

An access list has the following attribute:

• Optional attribute InheritFromParent.
  The value of the attribute InheritFromParent can accept the string "No". If "No" is specified, inheritance of access lists from parent groups is deactivated. Because access lists are inherited from parent groups by default, it is only necessary to specify the attribute InheritFromParent if inheritance is to be explicitly deactivated.

An access list can contain the following element:

• one or more access entries with the XML tag <AccessEntry>.
  Any number of access entries is permitted. However, an access list may contain a maximum of one access entry for each remote administrator. An access entry allows you to explicitly define the access permissions for a remote administrator. This means that you can specify which remote administration functions are granted or denied to this remote administrator.

  Note that parent access permissions are inherited unless you have deactivated this by specifying InheritFromParent="No".

Defining an access entry

An access entry is an element of an access list and starts with the XML tag <AccessEntry>. There is no limit to the maximum number of access entries in the configuration file. An access entry is made up of the following attributes:

• Mandatory attribute AdministratorID. The value of the attribute AdministratorID is a string that specifies the name of the remote administrator. This remote administrator must be defined at the start of the configuration file using the tag <AdministratorID>. See section “Creating a configuration file using a text or XML editor”. A remote administrator may only be specified in one access entry in an access list.

• AllowFunction and DenyFunction attributes. These attributes specify which remote administration functions are granted (AllowFunction) and denied (DenyFunction). The AllowFunction and DenyFunction attributes are in principle optional, but you must specify at least one of the two attributes in every access entry.

  If both attributes are specified, note that entries for the attribute DenyFunction, which deny a function to the remote administrator, take priority over entries for the attribute AllowFunction, which grant this function to the remote administrator.

  The following points apply:

  • The value of the attribute AllowFunction specifies what remote administration functions are permitted to the remote administrator to carry out. The string can have the following values (remote administration permissions):

    "FTOP"
    "FT"
    "FTAC"
    "FT FTAC"
    "FTAC FT"
    "FTAC FTOP"
    "FTOP FTAC" 
    

    • Specifying "FTOP" (FT operator) only permits read FT access.

    • Specifying "FT" permits FT access for reading and modification.

    • Specifying "FTAC" permits FTAC access for reading and modification.

    Combinations mean that the remote administrator has been granted both permissions.

  
  

  • The value of the attribute DenyFunction determines which remote administration functions have been denied to the remote administrator. The string can have the following values:

    "FT" 
    "FTMOD"
    "FTAC" 
    "FT FTAC" 
    "FTAC FT"
    "FTAC FTMOD" 
    "FTMOD FTAC"
    

    • Specifying "FTMOD" denies FT access for modification.

    • Specifying "FT" denies FT access for reading and modification.

    • Specifying "FTAC" denies FTAC access for reading and modification.

    Combinations mean that both functions are denied.
    This means, for example, that "FTAC FTMOD" means that neither FTAC access nor FT access for modification is permitted. In other words, read FT access only is permitted, which corresponds to specifying "FTOP" under AllowFunction.

Example:

<Group
   Name="HH1"
   Description="QA Computer Center">
   <AccessList>
      <AccessEntry
         AdministratorID="Jack"
         AllowFunction="FT FTAC"/>
      <AccessEntry
         AdministratorID="Mike"
         AllowFunction="FT FTAC"/>
   </AccessList>
   <Instance
      Name="HHWSRV02"
      Description="HP-11"
      Address="ftadm: //HHWSRV02.hhw.mycompany.net"
      Admission="hhwsrv02remote"/>
   <Instance
      Name="HHWSRV11"
      Description="Solaris 10"
      Address="HHWSRV11.hhw.mycompany.net"
      Admission="hhwsrv11remote"
      Mode="Legacy">
      <AccessList>
         <AccessEntry
            AdministratorID="Mike" 
            DenyFunction="FTAC"/>
      </AccessList>
   </Instance>
</Group>

Defining encoding mode

The attribute CmdMode definies a recommendation in the remote administration server for every administered instance as to whether character or transparent mode is to be used. The openFT desktop of the administrator can take its bearings from these specifications after a ftshwc call to the central server. CmdMode does not force you to use a specific mode, but helps avoid errors in the process and achieve optimal behavior.

CmdMode can be set to one of the two following values:

• Transparent:
  The central remote administration recommends the use of transparent mode (ftadm -fnc=t)

• Char:
  The central remote administration recommends the use of character mode (ftadm -fnc=c)

CmdMode can be specified in the XML configuration of the remote administration server in three different places:

• as a parameter in <Configuration>: This specification is the default setting for all instances and groups, unless there are individual settings there.

• as a parameter in the <Group>: This specification overwrites default settings from the configuration or from superior groups and applies for all groups and instances within this group, unless these have individual settings.

• as a parameter in the <Instance>: This specification has priority over all default settings. If this is an instance that works in legacy mode, the transparent mode is automatically assumed - even if nothing is explicitly specified for this instance. If a CmdMode specification is not found in an instance, which does not work in legacy mode, neither in the instance itself nor in one of the groups, to which the instance belongs, nor in the configuration, then there is no mode recommendation.

If the CmdMode attribute is set, the version in the configuration must be 1210 or higher. openFT V12.1 can import XML configuration files of the previous versions (with the version specification 1100, for example); but the version has to be set to 1210 for export.