Installing Distribeast

Installing the controller node

To install the controller node:

Run the distribeast\distribeast.msi installer on the target computer.
On the Distribeast controller page of the installer, you will be prompted to make a choice about which controller you want to use. Select "Set up a controller on this machine", and click Next.
On the Local port page, specify the network port that you want the Distribeast controller to use for network connections, or accept the default port shown. Click Next.

Installing a worker node

To install a worker node:

Run the distribeast\distribeast.msi installer on the target computer.
On the Distribeast controller page of the installer, you will be prompted to make a choice about which controller you want to use. Select "Connect to a controller on another machine", and click Next.
On the next page, specify the network address or host name of the controller, and the port configured for the controller on that machine. The value you set here must match the value specified when the controller was installed. Click Next.
On the Local port page, specify the network port that you want the Distribeast worker to use for network communications on its local computer, or accept the default port shown. Click Next.

When the installation has completed, the Distribeast node will be up and running. Your worker node will be able to send jobs to the controller for processing, and will be able to accept jobs from the controller that were sent by other worker nodes.

Command-line installation

You can run the Distribeast installer from the command line. Use the following command:

msiexec /i distribeast.msi property=value /qn

The /qn option suppresses the user interface. The property key may be any of the following:

ACT_AS_CONTROLLER: Configures the node to be a controller (true) or a worker (false).
LOCAL_PORT: Sets the local communication port used by this controller or worker node. If you omit this property, the default value of 7788 is used.
CONTROLLER: Sets the network name of the controller node to use. If you are installing a controller node, omit this property. If you are installing a worker node, you must set this property.
CONTROLLER_PORT: Sets the communication port used by the controller node. If you are installing a controller node, omit this property. If you are installing a worker node, set this property to match the local port set up for the controller node. If you omit this property, the default value of 7788 is used.
ENABLE_UPDATES: Determines whether or not the automatic upgrade mechanism is enabled on this node. If omitted, the default value of true is used.
SET_FIREWALL_EXCEPTIONS: Determines whether or not the installer attempts to set firewall exceptions needed by Distribeast in the Windows Firewall. By default, the installer sets the firewall exceptions it needs; set this property to 0 to skip setting firewall exceptions. See also Installing Distribeast below.

For example, the following command sets up a worker node to connect to the controller at controllerHost::7790, using port 7789 for its communications with the network:

msiexec /i distribeast.msi CONTROLLER=controllerHost CONTROLLER_PORT=7790 LOCAL_PORT=7789 /qn

What does the installer do?

When you run the Distribeast installer, it installs several components and makes the system changes described in the following sections.

The Distribeast service

The installer creates a Windows service named Distribeast. This service runs using the built-in NetworkService account, which means that the service has restricted privileges on the computer. By default, it will be started automatically when Windows is started, even when no user is logged on.

The Distribeast service sends and receives files from the other nodes in the network. Some of them are executables; when these executables are launched, they will also be executed using the NetworkService account. More information about the NetworkService account can be found at:

http://msdn.microsoft.com/en-us/library/ms684272(VS.85).aspx

The Distribeast Monitor tray application

The Distribeast system contains a lightweight monitoring application that runs in the system tray. This application provides users with the ability to control certain aspects of DistriBeast, and provides feedback about the state of the Distribeast network and the local worker node. See Configuring Distribeast and Monitoring Distribeast.

The dconfig application

Distribeast also offers a command line utility named dconfig.exe. This utility allows users to view the status of the nodes in the Distribeast network. See Monitoring Distribeast.

Firewall exceptions

The Distribeast installer adds a Windows Firewall exception that allows the Distribeast service to open up ports in the firewall for incoming and outgoing connections. The default port used by Distribeast is 7788, but this can be changed in the installer. The firewall exception is removed automatically when Distribeast is uninstalled from the node.

By default, the installer will fail if it is unable to add the necessary firewall exceptions to the Windows Firewall configuration, or if you have disabled the Windows Firewall. In order to install Distribeast when the Windows Firewall is disabled, you must launch the installation from the command line with the additional parameter SET_FIREWALL_EXCEPTIONS=0. See Installing Distribeast above.

Note that when using the automatic upgrade feature of Distribeast, the SET_FIREWALL_EXCEPTIONS property is not propagated to nodes that request upgrades from the controller. If you want to use the automatic upgrade feature in a deployment where your worker nodes are on hosts that do not have the Windows Firewall enabled, you will have to edit the .msi installer file manually in order to stop the installer from attempting to add the firewall exceptions on machines that download the installer from the controller.

Note also that if you use any other firewalls or network protection schemes, you may need to make additional exceptions or configuration changes in your software in order for Distribeast to be able to communicate with other computers on the network.

Automatic upgrade detection

Distribeast worker nodes include an automatic upgrade mechanism. Whenever a worker node connects to a controller node that is using a new version of Distribeast, the worker node can download the latest version from the controller. The worker node prompts the logged-on user to initiate the upgrade.

Disabling automatic upgrade detection

The automatic upgrade feature presents a potential security issue. If the security of the controller is compromised, this could allow a malicious attacker to launch an attack on the rest of the nodes running Distribeast. If you are using other means to distribute software automatically, or if you want tighter security, you may want to disable automatic upgrades.

You can disable automatic upgrades using either of the following approaches:

During command-line installation. Specify ENABLE_UPDATES=false on your command line. See Installing Distribeast above.
By editing the registry after installation. On 32-bit Windows, find the HKEY_LOCAL_MACHINE\Software\IlluminateLabs\Distribeast\NodeConfig\updates\enable key. On 64-bit Windows, find the HKEY_LOCAL_MACHINE\Software\Wow6432Node\IlluminateLabs\Distribeast\NodeConfig\updates\enable key. Set the value of this key to false. If you use this approach, you will need to restart the node in order for the change to take effect.

Uninstalling controller nodes and processor nodes

To uninstall a Distribeast controller node or worker node, use the tools available in the Windows Control Panel.

Alternatively, you can run the Distribeast installer and follow the on-screen instructions to remove the software from your computer.