[Swift-commit] r6533 - branches/release-0.94/docs/siteguide

[davidk at ci.uchicago.edu]

Author: davidk
Date: 2013-06-11 06:56:21 -0500 (Tue, 11 Jun 2013)
New Revision: 6533

Added:
   branches/release-0.94/docs/siteguide/ssh
Modified:
   branches/release-0.94/docs/siteguide/siteguide.txt
Log:
SSH example


Modified: branches/release-0.94/docs/siteguide/siteguide.txt
===================================================================
--- branches/release-0.94/docs/siteguide/siteguide.txt	2013-06-08 00:15:43 UTC (rev 6532)
+++ branches/release-0.94/docs/siteguide/siteguide.txt	2013-06-11 11:56:21 UTC (rev 6533)
@@ -26,6 +26,8 @@
 
 include::midway[]
 
+include::ssh[]
+
 include::stampede[]
 
 include::uc3[]

Added: branches/release-0.94/docs/siteguide/ssh
===================================================================
--- branches/release-0.94/docs/siteguide/ssh	                        (rev 0)
+++ branches/release-0.94/docs/siteguide/ssh	2013-06-11 11:56:21 UTC (rev 6533)
@@ -0,0 +1,91 @@
+SSH
+---
+This section describes how to use the SSH provider to connect to remote sites
+and to handle data transfer.
+
+Generate a unique SSH key
+~~~~~~~~~~~~~~~~~~~~~~~~~
+It is recommended that you create a new SSH key exclusively for this purpose.
+In order to avoid being prompted for passwords/passphrases, your SSH passphrase
+will be stored in a read protected file. Instead of using your real SSH key and
+passphrase for this purpose, create a new one. Run this command on the machine
+where you will be running Swift:
+
+-----
+ssh-keygen -t dsa -f $HOME/.ssh/id_dsa-swift
+-----
+
+You will be prompted to create a passphrase. This will create two files: 
+$HOME/.ssh/id_dsa-swift and $HOME/.ssh/id_dsa-swift.pub. 
+
+Add your public key to the remote host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+On the remote host where you will be running, edit or create the file 
+$HOME/.ssh/authorized_keys. Paste in the contents of the newly created 
+$HOME/.ssh/id_dsa-swift.pub from the previous step to the end of the file.
+
+Verify your new key works
+~~~~~~~~~~~~~~~~~~~~~~~~~
+From the host where you will be running Swift, run the following 
+command to verify your keys are working:
+
+-----
+ssh -i $HOME/.ssh/id_dsa-swift user at login.remotehost.edu
+-----
+
+You should be able to connect without being asked for a password or passphrase.
+
+Create auth.defaults
+~~~~~~~~~~~~~~~~~~~~
+Once you verify your keys are working, create a file called 
+$HOME/.ssh/auth.defaults by running the following commands
+
+-----
+touch $HOME/.ssh/auth.defaults
+chmod 600 $HOME/.ssh/auth.defaults
+-----
+
+Next, edit $HOME/.ssh/auth.defaults and add the following lines:
+------
+login.remotehost.edu.type=key
+login.remotehost.edu.username=your_remote_username
+login.remotehost.edu.key=/your/home/.ssh/id_dsa-swift
+login.remotehost.edu.passphrase=your_passphrase
+-----
+
+Replace the values for "your_remote_username", "your_passphrase", and the path 
+to the private key you generated.
+
+Create a sites.xml file
+~~~~~~~~~~~~~~~~~~~~~~~
+Here is an example sites.xml file that will allow you to connect and transfer
+data to a remote host:
+
+-----
+<config>
+   <pool handle="remotehost">
+      <execution provider="coaster" jobmanager="ssh:local" url="login.remotehost.edu"/> 
+      <filesystem provider="ssh" url="login.remotehost.edu"/>
+      <profile namespace="karajan" key="jobThrottle">0</profile>
+      <profile namespace="karajan" key="initialScore">10000</profile>
+      <workdirectory>/path/to/remote/workdirectory</workdirectory>
+   </pool>
+</config>
+-----
+
+NOTE: This example will run work directly on login.remotehost.edu. In most 
+cases you will not want to do this. You'll like want to modify your sites.xml
+to use a remote scheduler, by setting jobmanager to ssh:pbs or ssh:slurm, for
+example. This usually requires also setting things like queues and walltimes.
+This example is provided for simplicity and testing.
+
+Setting your properties
+~~~~~~~~~~~~~~~~~~~~~~~
+Since you want to data transfer via ssh, you'll want to verify that you're not
+using any other file transfer mechanisms. Make sure you have the following 
+swift properties defined in your configuration file:
+
+-----
+use.provider.staging=false
+use.wrapper.staging=false
+-----