= How to ... setup a Hive slave = 

HeuristicLab Hive is a distributed computing software that follows the master - slave model: The master (or server) holds the jobs that should be calculated and is responsible for scheduling these. The slaves (or clients) are computers that poll the server for these jobs: they fetch them, run them and send the results back. 
The HeuristicLab Hive Slave is a modular application that is compromised of the core application logic and some views for visualization. These parts can be run in different ways and combinations:
* Console client with text output
* HeuristicLab app with visualization
* Windows service with optional tray icon

The following gives an overview: 

== Console client ==
For testing and debugging purposes or if you don't have local administration privileges you can use the `HeuristicLab.Clients.Hive.Slave.ConsoleClient-3.3`.
The Slave console client is a simple console application which you can execute without the need to install it. 
It starts the slave and shows information as output on the console:
\\ [[Image(consoleclient.png)]] \\ 


== HeuristicLab app ==
If you compile the `HeuristicLab.Clients.Hive.Slave.App-3.3` project, you get a new icon ''Hive Slave'' in the HL starter:
\\ [[Image(starter.png)]] \\ 
When starting this application, the hive slave is startet together with an UI that shows some statistics and a log window. This again does not need any special privileges to run. 


== Windows service ==
The slave can also be run as a windows service with an optional tray icon that shows the same information as the HL Slave app but lives in the Windows tray icon. This is especially useful for production environments where you just want to deploy the slave on a large number ob computers. 

There exist two projects:

=== HeuristicLab.Clients.Hive.Slave.WindowsService ===
This needs to be compiled to get the binaries for the Hive Slave Windows service. After doing that, an installer can be generated that installs the slave and registers it as a windows service on the client computer. The installer is created with the NSIS (Nullsoft Scriptable Install System). Download and install NSIS from http://nsis.sourceforge.net/. The installer scripts are located in the `Installers` directory in the source tree. Right-click on the file `HiveSlaveInstaller.nsi` and select ''Compile NSIS Script''. If everything works, you get, in the same directory, a file called ''HeuristicLab Hive Slave Installer.exe''. You can now copy and install this file on your clients. Please note that you have to compile the HeuristicLab Slave Windows Services solution before as the installer just takes the binaries and creates the installer out of them. You can open *.nsi files with a text editor to see what's actually happening. You can also find there at the beginning of the file that BUILDCONFIGURATION is set to Debug. If you want to package Release binaries change this in the nsi file and rebuild the solution using Release mode. 
When installed, the service runs in the background and connects to the Hive server, from which it fetches jobs and calculates them. If you don't want the slave to always calculate jobs, you can install the Slave Tray Icon where you can control the behavior of the service. Or you can use the Hive Administrator to define times when slaves or groups of slaves are not allowed to calculate jobs. 
Please note that you need local administration privileges on your computer to execute the installer.
\\ [[Image(installer.png)]] \\
The Slave Windows Service is now visible in the Windows Service Viewer and can be started and stopped from there:
\\ [[Image(service.png)]] \\ 
The Slave Windows Service Setup also creates an Event Source. You can view entries with the Windows Event Viewer. 
If something goes wrong while executing jobs, the slave tries to get the exceptions to the server so that the user can view them in the Experiment Manager. In cases where the slave doesn't know how to react to an exception and has to shut down, these exceptions are logged as Windows Event entries. 


=== HeuristicLab.Clients.Hive.Slave.TrayIcon ===
This is an application which sits in the Windows taskbar and shows you information about your locally installed slave. Besides the information it shows, you can use the Tray Icon to pause or stop the Slave service. 
[[BR]]

\\ [[Image(trayicon.png)]] \\ 

The Slave Tray Icon application shows on the first page an overview of the slave. 
The Kill button lets you stop the Windows service. If you are not logged in as administrator, UAC asks you to confirm this operation and the tray icon restarts with administration privileges. You may notice that the icon on the kill button changed and if you click it now, the service is stopped. 
The Stop button can be used to pause the Slave. This means that the slave is still connected to the Hive, but the server doesn't send new jobs to the slave. 
Start resumes operation. If the service is stopped, it tries to start the service. If the slave is paused, it tells the service to accept new jobs. The Jobs page shows a list of all currently running jobs and their execution time and the Log tab page displays all messages logged by the service.