Getting started with Conductor (Last updated: $Date: 2001/10/17 16:46:03 $)

1. Getting the software

1.1 Getting Java

You must have Java installed on your machine to use Conductor. Java version 1.3 or greater is highly recommended.

The installation procedure has a tendency to change frequently; consult your sys-admin.

1.2 Getting IPcept

As of Linux kernel version 2.2, IPcept has been separated from Conductor. The version of IPcept bundled with Conductor should only be used for 2.0 kernels.

You must obtain and install IPcept. The location of the IPcept class library and JNI libraries must be configured in config.in (see below) or be otherwise locatable (perhaps in your CLASSPATH and LD_LIBRARY_PATH).

Conductor does not need the UDP facilities that have been added to IPcept. You may, therefore, wish to build a version with TCP_ONLY defined. See the Makefile for more details.

1.3 Getting the firewall control utilities

Conductor requires either the ipfwadm or ipchains utility (depending on your kernel version) to control the kernel firewall. One of these is typically available in your Linux distribution.

The firewall control utility is expected to be installed in either /sbin or /usr/local/sbin. Adjust the intercept script if the utility is located elsewhere.

1.4 Getting the Conductor code

The Conductor source code lives in CVS. To get the code, type The rest of this document will assume that you performed this command in your home directory, so you will now have the directory ~/Conductor. Make appropriate adjustments if needed.

2. The file hierarchy

Conductor/config This directory contains various configuration files for Conductor.
Conductor/Classes In this directory tree, you will find all of the Java source for Conductor. Running make in this directory will build Conductor.class and all dependencies. Running make clean will remove all *.class files. Note that neither command will descend into the ConductorExt directory.
Conductor/Classes/FMG/ConductorExt This directory tree contains all of the extensions upon which the main Conductor code does NOT depend. Running make in this directory will build all extensions.
Conductor/bin This directory contains support scripts for running Conductor.
Conductor/lib This directory contains the native code used by conductor in the form of dynamically loadable libraries.
Conductor/IPcept The code in this directory is designed for use with Linux kernel version 2.0 ONLY!!! It's presence is for historical purposes only. A new version of IPcept that is compatible with Linux kernel version 2.2 is packaged separately.
Conductor/Documentation This directory contains additional documentation for Conductor including javadoc generated class documentation.
Conductor/EnvironmentTest This directory contains code that is compiled by BuildAll to determine if your environment is corectly set up.

3. Configuring and Building Conductor

To configur Conductor, modify the file config.in for your system-specific paths. Also, adjust lib/config.h according to the facilities in your system. If you intend to run Conductor from the source directory, you may also need to edit the first few lines of the Conductor script (which are automatically modified during installation).

The easiest way to build Conductor is to us the BuildAll script in the top level directory. The BuildAll command will clean all parts of Conductor and then build the java class files, extensions, and libraries.

You can also build Conductor using make in the root directory or any subdirectory (to build parts of Conductor). However, the Conductor extensions will not automatically be build. Use make in Conductor/Classes/FMG/ConductorExt (or make extensions in the Conductor directory) to build these pieces. The security extensions will be automatically built if CRYPTIX is installed and it's location is properly configured in config.in.

4. Installing Conductor

Conductor can be run from the source directories, or it can be installed on a machine and run from the system directories. The installation procedure follows:
  1. Go to the Conductor directory.
  2. Modify config.in and lib/config.h to suit your system.
  3. Modify the definitions of HOME_INSTALL_DIR and BIN_INSTALL_DIR in config.in.
  4. Build Conductor (use one of BuildAll, make all, or make all extensions.
  5. Become the root user and run make install
Once installed, Conductor can optionally be started automatically upon system startup. During installation the startup script will be copied to RC_INSTALL_DIR (which is /etc/rc.d/init.d by default). An additional symlink is generally required to cause the script to run upon startup. For example, would cause Conductor to start upon entry to run level 3 (after most everything else). If this Conductor node should intercept client connections, the port numbers or protocol names can be placed in the file config/capture_ports in the Conductor install directory.

5. Running Conductor

5.1 Overview

When you use Conductor, you will normally have at least two Conductor-enabled nodes: the client and the server. You can also have intermediate nodes. See section 5.5 for dealing with more than two nodes. Each Conductor-enabled node will run a copy of the Conductor software.

It will be easiest to run Conductor at each node if all of the nodes mount the Conductor directory from one machine (perhaps in your home directory). This is not required, but it is frequently convenient when debugging. You may need to modify the amd configuration to arrange this.

5.2 Starting IPcept

The client node must have the IPcept loadable kernel module loaded when you run conductor. To load IPcept, do the following: You will be prompted by sudo for a password. Enter your normal password. You only need to load IPcept once, each time you boot your system.

If you want to unload IPcept, do the following

You may be asked for your password. If the operation fails, make sure that Conductor is not running.

5.3 Config files

The file Conductor.properties includes a set of values that can be adjusted to affect Conductor's behavior. A sample version of this file is provided in Conductor.properties.example. Uncomment and adjust any properties that you need. In particular, you will probably want to configure the extensions you wish to use. If the properites file is missing or empty, default property values will be used.

The Conductor.properties file lives in Conductor's home (either the root of the source directory, if Conductor has not been installed, or in the INSTALL_DIR). To reduce clutter, other configuration files are typically in the config subdirectory.

The default planner requires that the configuration file adaptors.cfg be present in the config directory. There are several sample files checked into CVS. For starters, use no adaptors by typing

More information about these configuration files can be found here and here.

5.4 Starting Conductor

Conductor is invoked as follows If you run an installed copy of Conductor, the configuration (Conductor.properties) is taken from the installation home (normally /usr/local/Conductor). If you run Conductor from the source directory the configuration is taken from the current directory.

Conductor must run as root (sudo is acceptable) at all nodes other than the server node (though it can also be used there, if you wish). The -v option provides debugging output. Additional v's mean more verbosity. The port number (or service name), when specified indicates the destination port number of locally initiated connections that Conductor will capture. It is only required on the client node.

So, for example, if the client is yeager and the server is hinge, the following two commands start up conductor on the respective machines to capture telnet traffic.
on yeager: sudo ./Conductor -vvv 23
on hinge: Conductor -vvv
Once Conductor is running, simply run the application on the client (yeager):

5.5 Using with more than two machines

Conductor will automatically detect Conductor-enabled nodes on the route between the client and server. To ensure that a machine is included in the route between two other machines, use the route command. For example, if we want the machine york to sit between yeager and hinge in the above example, we would do the following on yeager as root: Now we would do the following:
on yeager: sudo ./Conductor -vvv 23
on york: sudo ./Conductor -vvv
on hinge: Conductor -vvv
Note that sudo is required on all nodes, but the server. Also note that the port number is only required on the client.


Conductor is a product of Mark Yarvis (yarvis@fmg.cs.ucla.edu) and the FMG Research Group at UCLA's Department of Computer Science.
Copyright © 2001 The Regents of the University of California. All Rights Reserved.