Clean up & add docs; fixes #72

AUTHORS

@@ -46,3 +46,4 @@ Matt Chisholm
 Mark Merritt
 Max Arnold
 Szymon Reichmann
+Ben Davis

docs/changelog.rst

@@ -25,6 +25,10 @@ would have also been included in the 1.2 line.
 Changelog
 =========
 
+* :feature:`72` SSH agent forwarding support has made it into Fabric's ssh
+  library, and hooks for using it have been added (enabled by default; use
+  :option:`-A` to disable.) Thanks to Ben Davis for porting an existing
+  Paramiko patch to `ssh` and providing the necessary tweak to Fabric.
 * :bug:`230` Fix regression re: combo of no fabfile & arbitrary command use.
   Thanks to Ali Saifee for the catch.
 * :release:`1.3.2 <2011-11-07>`

docs/usage/env.rst

@@ -324,6 +324,20 @@ using key-based authentication.
 
 .. versionadded:: 0.9.1
 
+.. _no_agent_forward:
+
+``no_agent_forward``
+--------------------
+
+**Default:** ``False``
+
+If ``True``, disables the on-by-default forwarding of your local SSH agent to
+the remote end.
+
+.. versionadded:: 1.4.0
+
+.. seealso:: :option:`-A`
+
 .. _no_keys:
 
 ``no_keys``

docs/usage/fab.rst

@@ -83,13 +83,20 @@ below.
 
 .. _optparse: http://docs.python.org/library/optparse.html
 
-.. cmdoption:: -a
+.. cmdoption:: -a, --no_agent
 
     Sets :ref:`env.no_agent <no_agent>` to ``True``, forcing our SSH layer not
     to talk to the SSH agent when trying to unlock private key files.
 
     .. versionadded:: 0.9.1
 
+.. cmdoption:: -A, --no-agent-forward
+
+    Sets :ref:`env.no_agent_forward <no_agent_forward>` to ``True``, disabling
+    agent forwarding.
+
+    .. versionadded:: 1.4.0
+
 .. cmdoption:: --abort-on-prompts
 
     Sets :ref:`env.abort_on_prompts <abort-on-prompts>` to ``True``, forcing

fabric/operations.py

@@ -13,9 +13,10 @@
 import time
 from glob import glob
 from traceback import format_exc
-
 from contextlib import closing
 
+from ssh.agent import AgentClientProxy
+
 from fabric.context_managers import settings, char_buffered
 from fabric.io import output_loop, input_loop
 from fabric.network import needs_host
@@ -752,9 +753,9 @@ def _execute(channel, command, pty=True, combine_stderr=None,
             rows, cols = _pty_size()
             channel.get_pty(width=cols, height=rows)
 
-        # request agent
-        from ssh.agent import AgentClientProxy
-        forward = AgentClientProxy(channel)
+        # Use SSH agent forwarding from 'ssh', unless user has turned it off.
+        if not env.no_agent_forward:
+            forward = AgentClientProxy(channel)
 
         # Kick off remote command
         if invoke_shell:

fabric/state.py

@@ -157,12 +157,21 @@ def _rc_path():
     ),
 
     # Use -a here to mirror ssh(1) options.
+    # Note, much later on: well, no. ssh -a concerns agent *forwarding*. Sigh.
     make_option('-a', '--no_agent',
         action='store_true',
         default=False,
         help="don't use the running SSH agent"
     ),
 
+    # Another minor departure from SSH, due to above mixup: use -A to allow
+    # disabling of agent forwarding (which is on by default.)
+    make_option('-A', '--no-agent-forward',
+        action='store_true',
+        default=False,
+        help="don't forward local agent to remote end"
+    ),
+
     # No matching option for ssh(1) so just picked something appropriate.
     make_option('-k', '--no-keys',
         action='store_true',