Lunch
Lunch
Download
Get the Latest Version
Older versions
Learn More
How-to
Installation
Try it out
How to customize your lunch file
The add_command function
Lunch is a distributed process starter and manager. It works on GNU/Linux and other operating systems which provide Python, bash, SSH and Twisted. For instance, it works on Mac OS X.
If you need to use it to start process on more than one computer, the first step is to configure your SSH client. The steps to manage ssh keys are in the SshKeysManagement page.
Next, download and install lunch on every computer.

Download
See the Downloads page for tarball archives to download.

Get the Latest Version
If you are running Ubuntu GNU/Linux, the latest package for Ubuntu Lucid can be found in the Metalab archive. See https://launchpad.net/~sat-metalab/+archive/metalab

To quickly install lunch on Ubuntu Lucid:

sudo add-apt-repository ppa:sat-metalab/metalab
sudo apt-get update
sudo apt-get install lunch
If you run an other operating system, download the latest tarball archive and follow the instructions in the INSTALL file. We use the Python module setuptools (distutils) for the packaging.

The 0.3 branch has an unstable API, but contains many bugfixes and new features. Please read the list of deprecated arguments for the add_command function. They are listed at the end of this page.

Older versions
For production use, one can use the latest release in the 0.2 branch.

The first release of the 0.4 stable branch should be ready for June 30th, 2010. Again, see the Downloads page for the tarballs archives.

Learn More
See the RoadMap to see what is coming.
Please add tickets to warn us about bugs and ask for features.
If you are curious, the ReleaseProcess page has details on how we package the application.
In a latter version, a UserInterface is planned.
See CopyrightInformations to learn that it is licensed under the GNU General Public License.
You can also add the new SoftwareSource to your APT sources list.
Here is a process tree created with lunch:

python─┬─python───xeyes
└─ssh───python───xeyes
How-to
Installation
On Ubuntu GNU/Linux, you should use the package. Simply download it and Gdebi should ask you if you want to install it.

If you are using an other system, (like Mac OS X) you might need to do it the hard way. See the InstallationHowTo page to learn how.

Try it out
Copy the "simple.lunch" example config file to the local ~/.lunchrc. Edit the configuration file to suit your needs.

cp doc/examples/simple.lunch ~/.lunchrc
edit ~/.lunchrc
Start the lunch master::

lunch -g
When the "-g" option is provided, you should see Lunch's window:

How to customize your lunch file
The ~/.lunchrc file is written in Python programming language. You only need to call a few functions, such as the add_command() function. Here are some examples::

add_command(command="xlogo", env={}, identifier="xlogo")
add_command(command="mplayer /usr/share/example-content/Ubuntu_Free_Culture_Showcase/StopMotionUbuntu.ogv", env={}, identifier="mplayer")
Setting the user and host arguments make it be issued through SSH to a remote host::

add_command(command="xlogo", env={"DISPLAY":":0.0"}, user="johndoe", host="example.org", identifier="remote_xlogo")
Here is a Lunch config file for miville. Note that the sleep attribute is for processes AFTER which we need to wait.

add_command("/home/aalex/src/miville/branches/services/py/mivilled -o 0", identifier="miville un", sleep_after=1)
add_command("/home/aalex/src/miville/branches/services/py/mivilled -o 1", identifier="miville deux", sleep_after=1)
add_command("xterm -c telnet localhost 14444", identifier="miville un")
add_command("xterm -c telnet localhost 14445", identifier="miville deux")
The Python documentation is at http://docs.python.org/
You might like to have a look at the PythonTricks page.

The add_command function
The add_command function is the only thing you need to call from your Python script. You need to call it once for each child process to run, on either local or remote host. Here is a list of its keyword arguments and their default values.

Keyword Default value Python Type Note
command None str The bash command to run. The only mandatory argument, and the first positional argument.
identifier None str Determines the name of the log files and the log keys.
env None dict A dict of name=value pairs of environment variables to set for the child process.
user None str The UNIX user name, when using SSH
host None str The IP address or host name to which connect using SSH. Lunch will not use SSH if not set.
sleep_after 0.25 float How long to wait before launching next command.
respawn True bool Should a child be respawned or not. Will only be run once if set to False.
minimum_lifetime_to_respawn 0.5 float Minimum life time a child must last in order to be respawned.
log_dir None str Specifies the logging directory for the lunch slave and child.
depends None str or list or str Specifies one or more identifiers of processes on which this one depends.
ssh_port None int Specifies the SSH port to use when using a remote host.
See the Deprecated page for options to avoid with this function.

from lunch.

Deprecated options of the add_command function.

Here is the list of deprecated keyword arguments to avoid:

Keyword Default value Python Type Note
title None str DEPRECATED in version 0.3 ! Use identifier instead.
log_file None str DEPRECATED in version 0.2
sleep None float DEPRECATED in version 0.2 ! Use sleep_after instead.
priority None int DEPRECATED in version 0.2 ! The order in which each command is added now determines the launching order.
order None int DEPRECATED in version 0.2 ! The order in which each command is added now determines the launching order.

from lunch.

How to generate and install ssh keys in order to avoid being prompted for a password every time you use ssh.

The new way (simpler)
On the machine FROM WHICH you will connect to others:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -f ~/.ssh/id_rsa -t rsa

for each desired host (including localhost), do:

ssh-copy-id @
ssh username@host 'echo Hello'

... where username and host are the other machines you will connect to (including localhost).
The old way
Here is how to generate a key:

ssh-keygen
Once this is done, you need to issue the following for each host you want to avoid typing the password for:

We put a modified version of the ssh-keyinstall script in postures/trunk/scripts.

cd ~/src/postures/trunk/scripts
./ssh-keyinstall -s dummyhostname -u dummyusername
ssh -l dummyusername dummyhostname 'echo HI'
A bug under gnome
When using gnome, after some time the gnome-keyring-daemon makes ssh-agent crash.
So the workaround is to disable gnome-keyring ssh support.

To get a graphical prompt for you ssh keys at login (since gnome-keyring won't prompt you for them anymore), add "ssh-add l" in your Startup Applications (System>Preferences). br
Image(ssh-add.png, nolink)

from lunch.

installation

Installation
Here is how to compile and install lunch for any operating system.

Dependencies
It uses ssh, xterm and the multiprocessing and subprocess python modules. Python2.4 or later is needed for subprocess.

sudo apt-get install openssh-client openssh-server python-setuptools mercurial

sudo easy_install --prefix=/usr/local multiprocessing

(there might be a python-multiprocessing package if you use a newer Ubuntu or Debian) We will drop multiprocessing in version 0.2.
Installing it the low-level way
Checkout the latest version from the repository.

mkdir -p ~/src
cd ~/src
hg clone https://svn.sat.qc.ca/hg/lunch
cd lunch
Install lunch to /usr/local/bin/lunch on both local and remote hosts. (type your password)

sudo make install

There should be a Lunch icon in the Application/Other Gnome menu.

from lunch.

license

LICENSE
Lunch
Copyright (C) 2008 Société des arts technologiques (SAT)
http://www.sat.qc.ca
All rights reserved.

This file is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

Lunch is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Lunch. If not, see http://www.gnu.org/licenses/.
IMAGES
The source of Lunch's icon is http://commons.wikimedia.org/wiki/File:Fruit-cherries.svg and is in the public domain. Thank you Rocket000 !

from lunch.

release process

Lunch Release Process =
Freeze the features ==
Announce a freeze in the IRC channel.

h2. Document it

• Update the documentation if needed :
  *** scripts/lunch
  *** scripts/lunch-slave
  *** man_lunch.txt
  *** README.txt
  *** debian/control

h2. Debian packaging and versionning

• Update dependencies if there are some :
  *** debian/control
• Update Lunch version number in the following files :

  $ vim -o lunch/runner.py scripts/lunch-slave setup.py lunch/gui.py
  

• Update Debian package changelog with the new version number :

h2. Create a tag

• Commit with a summary of changes since latest tag.

  $ hg ci
  

• Create a tag with the new version number.

  $ hg tag 0.1.3 
  

h2. Create the tarball

• Export the sources of the tag.
• Create a tarball

  $ cd ~/src/lunch
  $ hg tags
  tip                               81:6af627065d59
  0.1.4                             80:30c2df205258
  0.1.3                             75:1d9498d5f77b
  $ hg archive -r 80 ../lunch-0.1.4
  $ cd ..
  $ tar -zcvf lunch-0.1.4.orig.tar.gz lunch-0.1.4/
  

• Create the Debian archive. (the tarball with ".orig" in the file name is needed)

  $ cd ./lunch-0.1.4/
  $ dpkg-buildpackge -r
  

• Upload the tarball to the web site.
• Upload the Debian package to the web site.
• Announce the new release to the IRC channel and the mailing list.

h2. Create the source package and upload it to the PPA

$ cd ./lunch-0.1.4/
$ debuild -S -sa
$ cd ..
$ dput sat lunch_0.1.4-0ubuntu1_source.changes

Assumed that the content of your ~/.dput.cf is like below, and that you have the rights on Launchpad to write to this PPA.

[sat]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~sat-metalab/propulseart/ubuntu
login = anonymous
allow_unsigned_uploads = 0

from lunch.

user interface

Here is how one child process' info could look : Mockup of the information for a single child process.

Screenshot-Lunch.png - Mockup of the information for a single child process. (14,63 ko) Alexandre Quessy, 2010-01-10 22:17
snapshot_lunch_0.4_window.png (41,53 ko) Alexandre Quessy, 2011-03-26 18:03
snapshot_lunch_0.4_xeyes.png (55,19 ko) Alexandre Quessy, 2011-03-26 18:03

from lunch.

roadmap

Lunch RoadMap

Odd minor version numbers (such as 0.1.x, 0.3.x, ...) are unstable development branches. The even ones (0.4, 0.6, ...) are stable and should be well supported.

Todo =
For Version 0.4
Important =
Accessory ===
add buttons: "add command" (plus its dialog) and "remove command".
improve automatic names for commands
move logging to the right directory - not in /var/tmp
accessory: Use twisted.python.reflect.prefixedMethods for on_* methods.
Deprecate title, and use identifier.
Write a better documentation for add_command. Put in on the wiki, with versions as titles.
Done
DONE: add/remove commands live
DONE: get the return value of the command once done
DONE: Update GUI to allow it to detect if there are new processes added
DONE: Do not copy commands in the GUI App class
DONE: Poll commands, or better, use a command_added signal
DONE: Remove slot for state_change signal when a slave has been removed.
DONE: add the DONE, FAILED and GAVE UP states
DONE: improve reports on the state of processes
DONE: flush more often stdout/stderr to files
DONE: respawn after a little while instead of giving up
DONE: Do not ask confirmation to exit when no process is running.
For Version 0.6
Multiple process per Slave.
Killing order.
Post-Killing commands. (teardown)
Done =
Version 0.2 ==
DONE: Use Trac with Mercurial
DONE: Split lunch in 4 files.
DONE: Port to Twisted. Drop multiprocessing. See http://twistedmatrix.com/trac/browser/tags/releases/twisted-9.0.0/twisted/runner/procmon.py
DONE: Get rid of the former lunch 0.1. Split the Master. Keep the slave in one file, for easier installation.
DONE: Use key=value pairs for env, drop JSON.
DONE: Drop sig.Signal in slave.
DONE: Split messages, use the first word as key, and the leftover as a line to pass to the right on_* method.
DONE: Use bash -c exec to run commands.
DONE: Remove a need for the lunch/constants file.
DONE: Re-implement starting order, with weight filtering from lowest to highest.
DONE: master: Make that master does not kill Slave when its child is dead. (configurable)
DONE: master: Simplify master states to 4: STOPPED, STARTING, RUNNING, STOPPING.
DONE: master: Use on_* callbacks style for the Slave Process Manager as well.
DONE: master: Use send_* methods style for the senders on both side.
DONE: master: The order of commands should be automatically ordered with calling order.
DONE: master: Depenmdencies: when one slave dies, kill all slaves who depend on it, restart them all again - if needed.
DONE: master: Wait for the greetings message, not the connection to the process stdin.
DONE: slave: Make sure each process is dead. Poll with a timer and use signals if needed.
DONE: slave: use a kill_delay option, with a default of 1.0 second.
DONE: master: Separate log for each slave on the master's side.
DONE: GTK+ GUI for the Master Lunch.

from lunch.

python tricks

Python Tricks =
Keyword arguments ==
With Lunch, avoid using ssh to log in to your localhost ! This can be done with keyword arguments, which allow one to put some keyword arguments in a dict and expand those when calling a function.¶

Look at the following example:

def add_command(command=None, user=None, host=None):
print("command:%s user:%s host:%s" % (command, user, host))

all = [
{"command":"hello", "user":"me", "host":"localhost"},
{"command":"hello", "user":"me", "host":"example.org"}
]

for kwargs in all:
if kwargs[[host]] == "localhost":
del kwargs[[host]]
del kwargs[[user]]
add_command(**kwargs)

from lunch.