lunch

[OPERATION]

The lunch executable is called the lunch master. The lunch-slave executable is called the lunch slave. If run as a master, it launches slaves. The slaves are responsible for launching child processes. The master launches slaves (via SSH or not) which, in turn, launch child processes.

The Lunch configuration file can be provided as a first argument to the lunch executable. If not given, the Lunch master will look for the ~/.lunchrc file. If not found, lunch will print an error and exit. The lunch config file is written in the Python programming language, and must call the add_command function. 

The process ID of the master is written to a file located in /tmp/lunch-pid-master-*.pid, where * varies depending on the lunch config file used to configure the master.

Here is how to kill every lunch master on your system :

  for f in /tmp/lunch-pid*.pid; do kill -15 $(cat $f); done

[ADDING COMMANDS]

add_command("process", options)

The add_command function is a regular python function and it is the function the user must call in his ~/.lunchrc file in order to launch processes with Lunch. It allows for a lot of flexibility. The first argument is the name of the process, as a python string, with all the command line switches that the command may require. This string can be formatted in a standard pythonesque way, using either % string substitution or the new .format function (since python 2.7).

Options:

env - (dict of str:str) a dictionary of environment variables that may be relevant to the running command

depends - (list of str) a list of process identifiers on which the current process depends

identifier - (str) a string that will identify a current process to refer to in depends option in the logs and in the GUI

host - (str) hostname or IP address for launching over SSH

user - (str) a UID, if launching over SSH

ssh_port - (int) port number of the remote SSH server if different from 22 (the default)

sleep_afer - (float) amount of seconds to sleep after launching the process

respawn - (bool) if True, lunch will relaunch the process every time it exits.  False will launch the process only once. Useful for running some pr

ocess only once, to set things up (i.e. firereset, setting environment variables etc.)

minimum_lifetime_to_respawn - (float) Minimum time a process must have lasted in order for it be respawned

log_dir - (str) path to the directory where log files should be stored.  Default is /var/tmp/lunch

try_again_delay - (float) a minimum delay to wait before relaunching the process if it crashes at startup.  The time is in seconds and the default is 0.25

give_up_after - (float) How many times to try respawning before giving up.

[SPECIFYING A LOCAL HOST]

add_local_address("address")

Commands launched on the local host and as the same user should not be launched over SSH. Sometimes it is easier to specify the host for all commands in the ~/.lunchrc file. One can let Lunch know which host is the local host by calling the add_local_address(address) function. One can use a domain name of an IP address. Many addresses can be set as local, since a computer might have many network interfaces.

[EXAMPLES]

See the examples directory for examples. On a Debian or Ubuntu system, they should located in the /usr/share/doc/lunch/examples/ directory.

Here is the simplest example possible for the contents of a ~/.lunchrc file. It tells Lunch to call only one command, called "xeyes".

  add_command("xeyes")

If you add more calls to add_command in this file, it will add more processes to be launched by Lunch. The add_command is the Python function you need to call from your Lunch configuration file in order to add commands to be called by Lunch. If you add more than one command, they will be called in the order you add them in the file.

Here is a more complex example of a configuration file. It creates three processes, with dependencies between processes.

  add_command("xeyes", identifier="xeyes")

  add_command("xlogo", depends=["xeyes"])

  add_command("xclock", depends=["xeyes", "xlogo"])

The configuration file above will first start xeyes, and next xlogo, and finally xclock. If xeyes quits, all three processes will be stopped and restarted. If the xlogo process quits, the xclock will be stopped and restarted again when the xlogo is running. The "depends" keyword argument of the "add_command" function needs a list of strings as argument. Those string must match the "identifier" keyword argument of an already added command. 

In the next example, we use SSH to launch processes on a remote host. Note that the lunch-slave script must be installed on each of the hosts on which to launch child processes.

  add_command("xeyes")

  add_command("xeyes", user="johndoe", host="example.org")

  add_command("xeyes", env = {"DISPLAY":":0.0"})

It will create a process tree such as this one : 

lunch_______________lunch-slave____xeyes

        |____ssh____lunch-slave____xeyes

The next one is a command that is run only once.

  add_command("ls -l", identifier="listing...", respawn=False)

If, for some reason, it is easier for you to specify the host name for every command you add, even for the local host, you can call "add_local_address" with the master's IP as an argument.

  add_local_address("192.168.1.2")

  # We will not use SSH for this one, 

  # since we just added its host using the 

  # "add_local_address" function.

  add_command("xeyes", 

    identifier="local_xeyes", 

    user="johndoe", host="192.168.0.2")

  # We will use SSH for the next one, 

  # since its host is not set as being the local host.

  add_command("xeyes -geometry 300x400", 

    identifier="remote_xeyes", 

    user="johndoe", host="example.org")

[GRAPHICAL USER INTERFACE]

When invoked with the --graphical option, (-g) the lunch master shows a graphical user interface displaying the state of every managed process. When this window is closed, the lunch master exits and kills all its children processes.

[SSH KEYS MANAGEMENT]

If using for more than one host, lunch needs a SSH server installed on each 

remote computer. It is also needed that the public SSH key of your user on the

master computer must be installed on every slave computer. Here is a summary of

the steps to do to create a SSH key on your master computer, and send your 

public key on each slave computer.

  $ mkdir -p ~/.ssh

  $ chmod 700 ~/.ssh

  $ ssh-keygen -f ~/.ssh/id_rsa -t rsa

Next, for each slave host, do:

  $ ssh-copy-id <username>@<host>

  $ ssh username@host 'echo Hello'

The latter command should display "Hello" when issued.

If you start lunch via SSH, and launch from there commands other hosts, you must first make sure that the ssh-agent is running and that you have unlocked your private SSH key. It can be done like this:

  $ ssh-agent bash

  $ ssh-add

[HISTORY]

2012 - Serious bugs fixed by Alexandre Quessy with contributions from

Michal Seta <mis@artengine.ca>.

2010 - Ported from multiprocessing to Twisted by Alexandre Quessy.

2009 - Written by Alexandre Quessy <alexandre@quessy.net> with contributions 

from Simon Piette <simonp@sat.qc.ca>

[REPORTING BUGS]

See http://code.sat.qc.ca/trac/lunch for help and documentation.

[SEE ALSO]

lunch-slave (1)