Permalink
Browse files

Improve discoverability of Connection(..., connect_kwargs={})

Support request made me realize, uh...this was NOT visible AT ALL
and it's kind of a core concept for most users.
  • Loading branch information...
bitprophet committed Nov 30, 2018
1 parent 401aa9f commit 6186c9e8909a0e0d230237dc026946647dec2872
Showing with 26 additions and 2 deletions.
  1. +21 −2 fabric/connection.py
  2. +5 −0 sites/docs/getting-started.rst
@@ -42,6 +42,14 @@ class Connection(Context):
level operations with that `~paramiko.client.SSHClient` and
`~paramiko.channel.Channel` instances generated from it.
.. _connect_kwargs:
.. note::
Many SSH specific options -- such as specifying private keys and
passphrases, timeouts, disabling SSH agents, etc -- are handled
directly by Paramiko and should be specified via the
:ref:`connect_kwargs argument <connect_kwargs-arg>` of the constructor.
**Lifecycle**
`.Connection` has a basic "`create <__init__>`, `connect/open <open>`, `do
@@ -206,15 +214,26 @@ def __init__(
Default: ``config.timeouts.connect``.
.. _connect_kwargs-arg:
:param dict connect_kwargs:
Keyword arguments handed verbatim to
`SSHClient.connect <paramiko.client.SSHClient.connect>` (when
`.open` is called).
`.Connection` tries not to grow additional settings/kwargs of its
own unless it is adding value of some kind; thus,
``connect_kwargs`` is currently the right place to hand in
parameters such as ``pkey`` or ``key_filename``.
``connect_kwargs`` is currently the right place to hand in paramiko
connection parameters such as ``pkey`` or ``key_filename``. For
example::
c = Connection(
host="hostname",
user="admin",
connect_kwargs={
"key_filename": "/home/myuser/.ssh/private.key",
},
)
Default: ``config.connect_kwargs``.
@@ -100,6 +100,11 @@ instances of `invoke.runners.Result` (or subclasses thereof) exposing the sorts
of details seen above: what was requested, what happened while the remote
action occurred, and what the final result was.
.. note::
Many lower-level SSH connection arguments (such as private keys and
timeouts) can be given directly to the SSH backend by using the
:ref:`connect_kwargs argument <connect_kwargs-arg>`.
Superuser privileges via auto-response
======================================

0 comments on commit 6186c9e

Please sign in to comment.