Description

cm uses several configuration files:

Connection Types

A connection type defines the parameters for connecting to a remote system using a single method. The default configuration includes support for ssh, rdesktop, vnc, rlogin, and telnet.

Connection types are stored in a file called connectiontypes. cm looks for this file first in the ~/.cm/ directory, and then in the /etc/cm/ directory, using the first file it finds. The connectiontypes file uses XML to describe the parameters for each connection type.

The file consists of a single ConnectionTypes element, which contains one or more ConnectionType elements. Each ConnectionType element must have a name attribute, which must be set to a unique name for this connection type. Each ConnectionType contains of zero or more Param elements, and exactly one Script element.

Each Param element must have a name attribute. cm will create a variable with the specified name, which can be used by the python script contained in the Script element to construct a command string. Param elements may have a required attribute, which can have a value of 0, an empty string, or 1. This attribute indicates that a value is required for this parameter. Param elements may also have a default attribute, which may be set to the default value for this parameter if one is not supplied by a particular connection.

Param elements may contain zero or more Choice elements. Choice elements define the possible values of the parameter. Each Choice element has a value attribute, which gives the value of this choice.

The Script element contains a python script, which is run by cm to generate a command string which is then passed to the shell and executed. Indentation matters to python, so be careful when you edit this element. cm sets a variable for each parameter, and gives that variable the appropriate value. The code in the Script element must set the cmdstr variable to contain a string that can be executed by the shell to make the connection.

The rdesktop connection type looks like this (except that in the actual file, the contents of the Script element are wrapped in a CDATA construct):

  <ConnectionType name="rdesktop">
    <Param name="host" required="1"/>
    <Param name="geometry" default="1024x768">
      <Choice value="640x480"/>
      <Choice value="800x600"/>
      <Choice value="1024x768"/>
    </Param>
    <Param name="userid"/>
    <Param name="domain"/>
    <Param name="fullscreen" default="false">
      <Choice value="false"/>
      <Choice value="true"/>
    </Param>
    <Script>
cmd = "rdesktop"
args = []

if geometry != None:
  args.extend(["-g",geometry])

if userid != None:
  args.extend(["-u",userid])

if domain != None:
  args.extend(["-d",domain])

if fullscreen != None:
  if fullscreen == "true":
    args.extend(["-f"])

args.extend([host])
    </Script>

Launchers

When using a graphical interface, it is often necessary to start a helper program to initiate a connection. For example, ssh(1) does not have a graphical interface. Therefore, it must be launched inside a helper application, like xterm(1) or /usr/bin/konsole.

Launchers are stored in a file called launchers. cm looks for this file using the same methodlogy it uses to find the connectiontypes file; first in the ~/.cm/ directory, and then in the /etc/cm/ directory. The launchers file uses XML to describe the various launching programs and their arguments.

The launchers file consists of a single Launchers element, which may have zero or more Launcher elements. A Launcher element must have a name attribute, and may have a description attribute. A single Script element contains the python code which must set the launchcmd variable to the full path of the launch application. The script will have variables assigned for each parameter of the connection, as well as the cmd and args variables. These variables have already been set by the script for the particular connection type. The launch script can use these variables to create an appropriate value for the launchargs variable, which contains a list of arguments to be passed to launchcmd.

The launcher for the konsole application looks like this:

<Launchers>
  <Launcher name="konsole" description="KDE Terminal">
    <Script>
launchcmd = "/usr/bin/konsole"
launchargs = ['--notoolbar','--nomenubar','-e',cmd]
launchargs.extend(args)
    </Script>
  </Launcher>
</Launchers>

User Configuration

The user configuration file stores various parameters required by cm. It also contains a list of connection directories available to the user. This XML file is found in the ~/.cm directory and is called config. If it does not exist, cm will create an empty file.

The config file consists of a single Configuration element.

Users may specify a default launcher. This is not used by the cm command line program, but is used by the graphical programs. The name of the default launcher is stored in the DefaultLauncher element.

The Configurationelement may also contain a Directories element, which consists of one or more Directory elements. Each Directory element contains the filename of a Connection Directory file. If this filename is not an absolute path, the ~/.cm directory is used as a base directory. This feature allows a user to use a shared connection directory in combination with a private directory, easing the distribution and maintenance of connection directories in large enterprise installations.

A user configuration file might look like this:

<Configuration>
  <Directories>
    <Directory>myhosts</Directory>
    <Directory>/etc/cm/win32servers</Directory>
  </Directories>
</Configuration>

Connection Directories

A Connection Directory file contains the settings for one or more Connections. A Directory file is an XML file that contains a single Directory element. This Directory element must have a name attribute, and may have a description attribute. A Directory element contains zero or more Connection elements.

A Connection element must have a type attribute, which must reference a name attribute of a ConnectionType element in the Connection Types file. A Connection element must also have a name attribute, and may have an abbrev attribute as well. These attributes are used to identify and search for this connection.

The contents of a Connection element depend on what type of connection this is. The allowed elements are given by the Param definitions in the Connection Types file.

The ssh connection type defines three parameters, "host", "userid", and "port". The rdesktop connection type defines five parameters, "host", "geometry", "userid", "domain", and "fullscreen". These parameters become the names of the elements that are allowed inside Connection elements of their respective types.

A directory that has a ssh connection and a rdesktop connection would look like this:

<Directory name="Machines at work">
  <Connection type="rdesktop" name="slug">
    <host>slug.example.com</host>
    <domain>EXAMPLE</domain>
    <geometry>1024x768</geometry>
    <userid>fbar</userid>
  </Connection>
  <Connection type="ssh" name="lildevil">
    <host>firewall.example.com</host>
    <userid>foo</userid>
  </Connection>
</Directory>

Notice that the "fullscreen" element has not been used in the rdesktop connection. This is OK because it has a default value. If a connection type does not define a default value for a parameter, and a value for that parameter is not given in the connection definition, cm will generate an error when launching the connection.

See Also

cm(1)

Copyright

Copyright (c) 2004 Jared Crapo