Permalink
Browse files

Replace all mentions of Paramiko in docs[trings].

Except in one or two spots where it still makes sense.

Re #19
  • Loading branch information...
1 parent 9affc58 commit 253b905c2ebb8f5b31f4ff697743702af3aa8c12 @bitprophet bitprophet committed Oct 23, 2011
View
3 README
@@ -30,5 +30,4 @@ Once a task is defined, it may be run on one or more servers, like so::
In addition to use via the ``fab`` tool, Fabric's components may be imported
into other Python code, providing a Pythonic interface to the SSH protocol
-suite at a higher level than that provided by e.g. Paramiko (which
-Fabric itself leverages.)
+suite at a higher level than that provided by e.g. the ``ssh`` library (which Fabric itself uses.)
View
@@ -144,10 +144,10 @@ This has been shown to work on FreeBSD and may work on other systems as well.
I'm sometimes incorrectly asked for a passphrase instead of a password.
=======================================================================
-Due to a bug of sorts in our SSH layer (Paramiko), it's not currently possible
-for Fabric to always accurately detect the type of authentication needed. We
-have to try and guess whether we're being asked for a private key passphrase or
-a remote server password, and in some cases our guess ends up being wrong.
+Due to a bug of sorts in our SSH layer, it's not currently possible for Fabric
+to always accurately detect the type of authentication needed. We have to try
+and guess whether we're being asked for a private key passphrase or a remote
+server password, and in some cases our guess ends up being wrong.
The most common such situation is where you, the local user, appear to have an
SSH keychain agent running, but the remote server is not able to honor your SSH
@@ -156,8 +156,8 @@ incorrect username. In this situation, Fabric will prompt you with "Please
enter passphrase for private key", but the text you enter is actually being
sent to the remote end's password authentication.
-We hope to address this in future releases, either by doing heavier
-introspection of Paramiko or patching Paramiko itself.
+We hope to address this in future releases by modifying a fork of the
+aforementioned SSH library.
Is Fabric thread-safe?
View
@@ -18,8 +18,8 @@ In order for Fabric's installation to succeed, you will need four primary pieces
* the Python programming language;
* the ``setuptools`` packaging/installation library;
-* the PyCrypto cryptography library;
-* and the Paramiko SSH2 library.
+* the Python ``ssh`` SSH2 library;
+* and ``ssh``'s dependency, the PyCrypto cryptography library.
and, if using the :doc:`parallel execution mode </usage/parallel>`:
@@ -59,11 +59,11 @@ setuptools dependency in the future, or include alternative support for the
PyCrypto
--------
-`PyCrypto <http://www.amk.ca/python/code/crypto.html>`_ is a dependency of
-Paramiko which provides the low-level (C-based) encryption algorithms used to
-run SSH. There are a couple gotchas associated with installing PyCrypto: its
-compatibility with Python's package tools, and the fact that it is a C-based
-extension.
+`PyCrypto <http://www.amk.ca/python/code/crypto.html>`_ provides the low-level
+(C-based) encryption algorithms used to run SSH, and is thus required by our
+SSH library. There are a couple gotchas associated with installing PyCrypto:
+its compatibility with Python's package tools, and the fact that it is a
+C-based extension.
.. _pycrypto-and-pip:
@@ -224,16 +224,16 @@ Windows users who already have ActiveState's `ActivePython
<http://www.activestate.com/activepython/downloads>`_ distribution installed
may find Fabric is best installed with `its package manager, PyPM
<http://code.activestate.com/pypm/>`_. Below is example output from an
-installation of Fabric 0.9.4 via ``pypm``::
+installation of Fabric via ``pypm``::
C:\> pypm install fabric
The following packages will be installed into "%APPDATA%\Python" (2.7):
- paramiko-1.7.6 pycrypto-2.0.1 fabric-0.9.4
- Get: [pypm-free.activestate.com] fabric 0.9.4
- Get: [pypm-free.activestate.com] paramiko 1.7.6
- Get: [pypm-free.activestate.com] pycrypto 2.0.1
- Installing paramiko-1.7.6
- Installing pycrypto-2.0.1
- Installing fabric-0.9.4
+ ssh-1.7.8 pycrypto-2.4 fabric-1.3.0
+ Get: [pypm-free.activestate.com] fabric 1.3.0
+ Get: [pypm-free.activestate.com] ssh 1.7.8
+ Get: [pypm-free.activestate.com] pycrypto 2.4
+ Installing ssh-1.7.8
+ Installing pycrypto-2.4
+ Installing fabric-1.3.0
Fixing script %APPDATA%\Python\Scripts\fab-script.py
C:\>
View
@@ -32,14 +32,14 @@ Longer-term but probably still 1.x plans
In no particular order, some potential future feature releases:
-* Fork Paramiko and fix `a number of outstanding issues/deficiencies
- <https://github.com/fabric/fabric/issues/275>`_ that cause problems for
- Fabric itself (authentication failure reasons being unclear, lack of SSH
- agent forwarding and/or gateway support, etc.)
+* Work on our fork of Paramiko, ``ssh``, to fix `a number of outstanding
+ issues/deficiencies <https://github.com/fabric/fabric/issues/275>`_ that
+ cause problems for Fabric itself (authentication failure reasons being
+ unclear, lack of SSH agent forwarding and/or gateway support, etc.)
* Re-examine `Tav's fork
<http://tav.espians.com/fabric-python-with-cleaner-api-and-parallel-deployment-support.html>`_
and see if anything remains which A) has not already been implemented based
- on older work, such as ``@task`` and parallel execution, and B) fits well
+ on older work, (meaning not ``@task`` or parallel execution), and B) fits well
with the current vision for Fabric's feature set and style/behavior.
* Improve core execution mechanisms, mostly by chopping up ``fab``'s action
loop and exposing chunks of it via the API.
View
@@ -303,8 +303,8 @@ contain the same value.
**Default:** ``False``
-If ``True``, will tell Paramiko not to seek out running SSH agents when using
-key-based authentication.
+If ``True``, will tell the SSH layer not to seek out running SSH agents when
+using key-based authentication.
.. versionadded:: 0.9.1
@@ -315,9 +315,9 @@ key-based authentication.
**Default:** ``False``
-If ``True``, will tell Paramiko not to load any private key files from one's
-``$HOME/.ssh/`` folder. (Key files explicitly loaded via ``fab -i`` will still
-be used, of course.)
+If ``True``, will tell the SSH layer not to load any private key files from
+one's ``$HOME/.ssh/`` folder. (Key files explicitly loaded via ``fab -i`` will
+still be used, of course.)
.. versionadded:: 0.9.1
View
@@ -85,8 +85,8 @@ below.
.. cmdoption:: -a
- Sets :ref:`env.no_agent <no_agent>` to ``True``, forcing Paramiko not to
- talk to the SSH agent when trying to unlock private key files.
+ 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
@@ -163,8 +163,8 @@ below.
.. cmdoption:: -k
- Sets :ref:`env.no_keys <no_keys>` to ``True``, forcing Paramiko to not look
- for SSH private key files in one's home directory.
+ Sets :ref:`env.no_keys <no_keys>` to ``True``, forcing the SSH layer to not
+ look for SSH private key files in one's home directory.
.. versionadded:: 0.9.1
@@ -55,10 +55,10 @@ time, they can become garbled or meshed together. While this can sometimes be
mitigated by line-buffering one of the streams and not the other, it's still a
serious issue.
-To solve this problem, Fabric uses a Paramiko setting that merges the two
-streams at a low level and causes output to appear more naturally. This setting
-is represented in Fabric as the :ref:`combine-stderr` env var and keyword
-argument, and is ``True`` by default.
+To solve this problem, Fabric uses a setting in our SSH layer which merges the
+two streams at a low level and causes output to appear more naturally. This
+setting is represented in Fabric as the :ref:`combine-stderr` env var and
+keyword argument, and is ``True`` by default.
Due to this default setting, output will appear correctly, but at the
cost of an empty ``.stderr`` attribute on the return values of
View
@@ -2,12 +2,11 @@
SSH behavior
============
-Fabric currently makes use of the `Paramiko
-<http://www.lag.net/paramiko/docs/>`_ SSH library for managing all connections,
-meaning that there are occasionally spots where it is limited by Paramiko's
-capabilities. Below are areas of note where Fabric will exhibit behavior that
-isn't consistent with, or as flexible as, the behavior of the ``ssh``
-command-line program.
+Fabric currently makes use of a pure-Python SSH re-implementation for managing
+connections, meaning that there are occasionally spots where it is limited by
+that library's capabilities. Below are areas of note where Fabric will exhibit
+behavior that isn't consistent with, or as flexible as, the behavior of the
+``ssh`` command-line program.
Unknown hosts
@@ -19,20 +18,20 @@ identifiers (IP address, sometimes with a hostname as well) and SSH keys. (For
details on how this works, please see the `OpenSSH documentation
<http://openssh.org/manual.html>`_.)
-Paramiko is capable of loading up your ``known_hosts`` file, and will then
-compare any host it connects to, with that mapping. Settings are available to
-determine what happens when an unknown host (a host whose username or IP is not
-found in ``known_hosts``) is seen:
+The ``ssh`` library is capable of loading up your ``known_hosts`` file, and
+will then compare any host it connects to, with that mapping. Settings are
+available to determine what happens when an unknown host (a host whose username
+or IP is not found in ``known_hosts``) is seen:
* **Reject**: the host key is rejected and the connection is not made. This
results in a Python exception, which will terminate your Fabric session with a
message that the host is unknown.
* **Add**: the new host key is added to the in-memory list of known hosts, the
connection is made, and things continue normally. Note that this does **not**
modify your on-disk ``known_hosts`` file!
-* **Ask**: not yet implemented at the Fabric level, this is a Paramiko option
- which would result in the user being prompted about the unknown key and
- whether to accept it.
+* **Ask**: not yet implemented at the Fabric level, this is an ``ssh`` library
+ option which would result in the user being prompted about the unknown key
+ and whether to accept it.
Whether to reject or add hosts, as above, is controlled in Fabric via the
:ref:`env.reject_unknown_hosts <reject-unknown-hosts>` option, which is False
@@ -47,16 +46,17 @@ Known hosts with changed keys
The point of SSH's key/fingerprint tracking is so that man-in-the-middle
attacks can be detected: if an attacker redirects your SSH traffic to a
computer under his control, and pretends to be your original destination
-server, the host keys will not match. Thus, the default behavior of SSH -- and
-Paramiko -- is to immediately abort the connection when a host previously
-recorded in ``known_hosts`` suddenly starts sending us a different host key.
+server, the host keys will not match. Thus, the default behavior of SSH (and
+its Python implementation) is to immediately abort the connection when a host
+previously recorded in ``known_hosts`` suddenly starts sending us a different
+host key.
In some edge cases such as some EC2 deployments, you may want to ignore this
-potential problem. Paramiko, at the time of writing, doesn't give us control
-over this exact behavior, but we can sidestep it by simply skipping the loading
-of ``known_hosts`` -- if the host list being compared to is empty, then there's
-no problem. Set :ref:`env.disable_known_hosts <disable-known-hosts>` to True
-when you want this behavior; it is False by default, in order to preserve
+potential problem. Our SSH layer, at the time of writing, doesn't give us
+control over this exact behavior, but we can sidestep it by simply skipping the
+loading of ``known_hosts`` -- if the host list being compared to is empty, then
+there's no problem. Set :ref:`env.disable_known_hosts <disable-known-hosts>` to
+True when you want this behavior; it is False by default, in order to preserve
default SSH behavior.
.. warning::
View
@@ -4,7 +4,7 @@
Necessary because if we did this in __init__, one would be unable to import
anything else inside the package -- like, say, the version number used in
setup.py -- without triggering loads of most of the code. Which doesn't work so
-well when you're using setup.py to install e.g. paramiko!
+well when you're using setup.py to install e.g. ssh!
"""
from fabric.context_managers import cd, hide, settings, show, path, prefix, lcd
from fabric.decorators import (hosts, roles, runs_once, with_settings, task,
View
@@ -169,7 +169,9 @@ def parallel(pool_size=None):
def real_decorator(func):
@wraps(func)
def inner(*args, **kwargs):
- # Required for Paramiko/PyCrypto to be happy in multiprocessing
+ # Required for ssh/PyCrypto to be happy in multiprocessing
+ # (as far as we can tell, this is needed even with the extra such
+ # calls in newer versions of the 'ssh' library.)
Random.atfork()
return func(*args, **kwargs)
inner.parallel = True
View
@@ -229,16 +229,16 @@ def connect(user, host, port):
# Otherwise, assume an auth exception, and prompt for new/better
# password.
- # Paramiko doesn't handle prompting for locked private keys (i.e.
- # keys with a passphrase and not loaded into an agent) so we have
- # to detect this and tweak our prompt slightly. (Otherwise,
- # however, the logic flow is the same, because Paramiko's connect()
- # method overrides the password argument to be either the login
- # password OR the private key passphrase. Meh.)
+ # The 'ssh' library doesn't handle prompting for locked private
+ # keys (i.e. keys with a passphrase and not loaded into an agent)
+ # so we have to detect this and tweak our prompt slightly.
+ # (Otherwise, however, the logic flow is the same, because
+ # ssh's connect() method overrides the password argument to be
+ # either the login password OR the private key passphrase. Meh.)
#
# NOTE: This will come up if you normally use a
# passphrase-protected private key with ssh-agent, and enter an
- # incorrect remote username, because Paramiko:
+ # incorrect remote username, because ssh.connect:
# * Tries the agent first, which will fail as you gave the wrong
# username, so obviously any loaded keys aren't gonna work for a
# nonexistent remote account;
@@ -247,11 +247,11 @@ def connect(user, host, port):
# because you didn't enter a password, because you're using
# ssh-agent;
# * In this condition (trying a key file, password is None)
- # Paramiko raises PasswordRequiredException.
+ # ssh raises PasswordRequiredException.
text = None
if e.__class__ is ssh.PasswordRequiredException:
# NOTE: we can't easily say WHICH key's passphrase is needed,
- # because Paramiko doesn't provide us with that info, and
+ # because ssh doesn't provide us with that info, and
# env.key_filename may be a list of keys, so we can't know
# which one raised the exception. Best not to try.
prompt = "[%s] Passphrase for private key"
View
@@ -36,7 +36,7 @@ def _pty_size():
"""
Obtain (rows, cols) tuple for sizing a pty on the remote end.
- Defaults to 80x24 (which is also the Paramiko default) but will detect
+ Defaults to 80x24 (which is also the 'ssh' lib's default) but will detect
local (stdout-based) terminal window size on non-Windows platforms.
"""
rows, cols = 24, 80
View
@@ -12,7 +12,7 @@
class SFTP(object):
"""
- SFTP helper class, which is also a facade for paramiko.SFTPClient.
+ SFTP helper class, which is also a facade for ssh.SFTPClient.
"""
def __init__(self, host_string):
self.ftp = connections[host_string].open_sftp()
@@ -114,8 +114,8 @@ def get(self, remote_path, local_path, local_is_path, rremote=None):
if local_is_path:
# Interpolate, then abspath (to make sure any /// are compressed)
local_path = os.path.abspath(local_path % path_vars)
- # Ensure we give Paramiko a file by prepending and/or creating
- # local directories as appropriate.
+ # Ensure we give ssh.SFTPCLient a file by prepending and/or
+ # creating local directories as appropriate.
dirpath, filepath = os.path.split(local_path)
if dirpath and not os.path.exists(dirpath):
os.makedirs(dirpath)
View
@@ -101,9 +101,9 @@ def _equalize(lists, fillval=None):
return lists
-class ParamikoServer(ssh.ServerInterface):
+class TestServer(ssh.ServerInterface):
"""
- Test-ready server implementing Paramiko's server interface parent class.
+ Test server implementing the 'ssh' lib's server interface parent class.
Mostly just handles the bare minimum necessary to handle SSH-level things
such as honoring authentication types and exec/shell/etc requests.
@@ -155,7 +155,7 @@ class SSHServer(ThreadingMixIn, TCPServer):
"""
def _socket_info(self, addr_tup):
"""
- Clone of the very top of Paramiko (1.7.6) SSHClient.connect().
+ Clone of the very top of Paramiko 1.7.6 SSHClient.connect().
We must use this in order to make sure that our address family matches
up with the client side (which we cannot control, and which varies
@@ -395,7 +395,7 @@ def init_transport(self):
transport.add_server_key(ssh.RSAKey(filename=SERVER_PRIVKEY))
transport.set_subsystem_handler('sftp', ssh.SFTPServer,
sftp_si=FakeSFTPServer)
- server = ParamikoServer(passwords, home, pubkeys, files)
+ server = TestServer(passwords, home, pubkeys, files)
transport.start_server(server=server)
self.ssh_server = server
self.transport = transport
View
@@ -81,7 +81,7 @@ def test_list_folder():
),
):
# Pass in fake server obj. (Can't easily clean up API to be more
- # testable since it's all implementing Paramiko interface stuff.)
+ # testable since it's all implementing 'ssh' interface stuff.)
server = AttrHolder()
server.files = file_map
interface = FakeSFTPServer(server)

0 comments on commit 253b905

Please sign in to comment.