View source for Dsh

{{Community testing}}
{{Experimental}}

== Introduction ==

''(from the [http://www.netfort.gr.jp/~dancer/software/dsh.html.en dsh homepage]): dsh is an implementation of a wrapper for executing multiple remote shell (rsh/remsh/ssh) commands. rsh/remsh/ssh are wrappers for executing shell (ksh/bash/zsh/tcsh/sh .. etc... ) on remote hosts.''

The [[community testing]] group is experimenting with using dsh to:

* Manage large testbeds with many XOs together in 1 room (100 XOs in an office or a school, etc.)
* Create impromptu distributed large testbeds from multiple small XO pools
* Use an [[XS]] to monitor the XOs connected to it

== How to use for XO testing ==

Note:

* The instructions below will use the term '''supervisor''' to refer to the computer you are running the commands from (and on which dsh is installed), and the term '''XO''' to refer generically to any XOs in the testbed you are remotely managing. 
* Unless otherwise stated, all instructions are intended to be executed by/on the supervisor machine. 
* You must have terminal access to the supervisor machine.
* These instructions have only been tested with Linux (Debian/Ubuntu). Help testing and writing instructions for Mac OS X, Windows, and other operating systems is welcomed.

=== Setup ===

# Follow the instructions on the [http://www.netfort.gr.jp/~dancer/software/dsh.html.en dsh homepage] to install dsh.
# Generate an SSH keypair. Instructions on how to do this can be found [http://w3.pppl.gov/cppg/seminars/papers/linux_talk/node11.html here (Linux, concise)], [http://sial.org/howto/openssh/publickey-auth/ here (Linux, detailed)], and [http://linux-sxs.org/networking/openssh.putty.html here (Windows)]. You should end up with these two files in the .ssh folder in your home directory: id_rsa and id_rsa.pub.
# For each XO in your testbed (follow these instructions on your XOs):
## Connect to the network.
## Copy the id_rsa.pub file you just generated into a new line on your supervisor machine into the <code>/home/olpc/.ssh/authorized_keys</code> file of each XO (use a thumbdrive, or upload to the web and use wget). (The <code>/home/olpc/.ssh/authorized_keys</code> file will not exist on most XOs; you may have to create it.)
## Run the <code>ifconfig</code> command (or use the [[Analyze]] Activity) to get the IP address of your XO.
## Add this IP address to a new line in the <code>/etc/dsh/machines.list</code> file on your supervisor machine, with the text <code>olpc@</code> before it (you may need root on the supervisor machine to edit this file).
# You should now have an <code>/etc/dsh/machines.list</code> file on your supervisor machine that looks something like this:
 olpc@18.85.49.113
 olpc@18.85.49.114
 olpc@18.85.49.115

This concludes the dsh setup instructions for XO testing.

=== Running commands ===

On your supervisor machine, run the following command in a terminal:
 dsh -Mac <command you want to run>

* The '''-M''' option prepends the IP address of the XO before the terminal output it sends.
* The '''-a''' option runs it on all the machines in your <code>/etc/dsh/machines.list</code> file.
* The '''-c''' option runs the command concurrently on all machines. If some machines are unreachable (have disconnected from the network etc.), dsh will give output for the XOs it is able to talk to and then continue to attempt to connect to the remaining machines. (For this reason, you may want to terminate the command after several minutes if it is still running.)

For example, to run the <code>ps</code> command:

 mchua@tumtum-tree:~$ dsh -Ma ps
 olpc@18.85.49.113:  PID TTY          TIME CMD
 olpc@18.85.49.113: 1166 ?        00:00:00 startx
 olpc@18.85.49.113: 1185 ?        00:00:00 xinit
 olpc@18.85.49.113: 1211 ?        00:00:02 ck-xinit-sessio
 olpc@18.85.49.113: 1240 ?        00:00:40 python
 olpc@18.85.49.113: 1244 ?        00:00:00 dbus-launch
 <...more entries from 18.85.49.113 go here>
 olpc@18.85.49.114:  PID TTY          TIME CMD
 olpc@18.85.49.114: 1549 ?        00:00:00 startx
 olpc@18.85.49.114: 1566 ?        00:00:00 xinit
 olpc@18.85.49.114: 1577 ?        00:01:31 python
 olpc@18.85.49.114: 1585 ?        00:00:16 dbus-daemon
 <...more entries from 18.85.49.114 go here>

Read the dsh manpage (<code>man dsh</code>) for further options.

== Specific setups ==

=== Using an XS as the supervisor machine ===

Using dsh, it is possible to use an XS as a supervisor machine to control/monitor all the XOs that are connected to it.

This also provides a level of security, as by default an XO connected to an XS is only accessible by machines on that subnet, so only machines on the XS ssid with the correct private key will be able to control those XOs via dsh. (Machines outside the subnet will not be able to remotely access those XOs at all.) Another suggestion for even more security is to use a weekly cron job to create a new key pair on the XS and have the XOs run a similar cronjob to pull that new publickey.

Since it is impossible to predict the IP addresses of specific XOs connected to an XS, you will want to include all possible addresses on the subnet in your <code>/etc/dsh/machines.list</code> file. Since XS subnets use a 23 bit mask, there are 512 possible addresses: 172.18.0.X and 172.18.1.Y, where X and Y are numbers between 1 and 254 inclusive.

Your <code>/etc/dsh/machines.list</code> file will look something like this:

 olpc@172.18.0.1
 olpc@172.18.0.2
 olpc@172.18.0.3
 ...
 olpc@172.18.0.252
 olpc@172.18.0.253
 olpc@172.18.0.254
 ...
 olpc@172.18.1.1
 olpc@172.18.1.2
 olpc@172.18.1.3
 ...
 olpc@172.18.1.252
 olpc@172.18.1.253
 olpc@172.18.1.254

You can then run commands via dsh on the XS as in the normal usage instructions, above.

== Help wanted ==

* It would be great if someone could test/develop/write instructions on how to use dsh with supervisor machines running Mac OS X and/or Windows.

: I did try Dsh, but didn't see the point of another custom install, all its features are already doable from a command line out the box. There's a range of [[Scripts_for_testing_multiple_XOs|simple examples]] that work on OSX, XO and standard linux distros. I see the main challenge as not remote access automation, but the actual gathering and logging of useful data in an accessible way (some examples already on above page). --[[User:Garycmartin|Garycmartin]] 15:29, 14 November 2008 (UTC)