Dsh

  This page is part of the OLPC Community testing Project. How to test an Activity | Reporting test results | Meetings

WARNING: These instructions are unofficial. OLPC does not support them. THESE INSTRUCTIONS ARE EXPERIMENTAL. FOLLOWING THEM MAY DAMAGE YOUR MACHINE. By following them, you take responsibility for this risk.

Introduction

(from the 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

1. Follow the instructions on the dsh homepage to install dsh.
2. Generate an SSH keypair. Instructions on how to do this can be found here (Linux, concise), here (Linux, detailed), and here (Windows). You should end up with these two files in the .ssh folder in your home directory: id_rsa and id_rsa.pub.
3. For each XO in your testbed (follow these instructions on your XOs):
   1. Connect to the network.
   2. Copy the id_rsa.pub file you just generated into a new line on your supervisor machine into the /home/olpc/.ssh/authorized_keys file of each XO (use a thumbdrive, or upload to the web and use wget). (The /home/olpc/.ssh/authorized_keys file will not exist on most XOs; you may have to create it.)
   3. Run the ifconfig command (or use the Analyze Activity) to get the IP address of your XO.
   4. Add this IP address to a new line in the /etc/dsh/machines.list file on your supervisor machine, with the text olpc@ before it (you may need root on the supervisor machine to edit this file).
4. You should now have an /etc/dsh/machines.list 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 /etc/dsh/machines.list 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 ps 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 (man dsh) 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 /etc/dsh/machines.list 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 /etc/dsh/machines.list 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 simple examples that work on OSX, XO and standard linux distros. I see the many 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). --Garycmartin 15:29, 14 November 2008 (UTC)