From b0b6a827b96453cfe9bddb343f94c5c2f4243f7b Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 13 Mar 2014 21:05:32 -0700 Subject: Update docs to reflect Python 2.6+, 3.3+ compat --- sites/www/installing.rst | 34 +++------------------------------- 1 file changed, 3 insertions(+), 31 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 0d4dc1ac..955a0a59 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -14,9 +14,9 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming -soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on -Python 2.4 still, but there is no longer any support guarantee. +We currently support **Python 2.6, 2.7 and 3.3** (Python **3.2** should also +work but has a less-strong compatibility guarantee from us.) Users on Python +2.5 or older are urged to upgrade. Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the PyCrypto C extension. `ecdsa` is easily installable from wherever you @@ -31,34 +31,6 @@ PyCrypto 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: - -Possible gotcha on older Python and/or pip versions ---------------------------------------------------- - -We strongly recommend using ``pip`` to as it is newer and generally better than -``easy_install``. However, a combination of bugs in specific (now rather old) -versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto. -Specifically: - -* Python = 2.5.x -* PyCrypto >= 2.1 (required for most modern versions of Paramiko) -* ``pip`` < 0.8.1 - -When all three criteria are met, you may encounter ``No such file or -directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install -PyCrypto``. - -The fix is to make sure at least one of the above criteria is not met, by doing -the following (in order of preference): - -* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``. -* Upgrade to Python 2.6 or above. -* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1, - and install PyCrypto 2.0.1 (the oldest version on PyPI which works with - Paramiko 1.7.6/1.7.7) - - C extension ----------- -- cgit v1.2.3 From 6fac5df53598e6dedb806121ae40261d7491a341 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:28:19 -0700 Subject: Start an FAQ and answer it with a new install section --- sites/www/faq.rst | 9 +++++++++ sites/www/index.rst | 1 + sites/www/installing.rst | 24 ++++++++++++++++++++++++ 3 files changed, 34 insertions(+) create mode 100644 sites/www/faq.rst (limited to 'sites/www/installing.rst') diff --git a/sites/www/faq.rst b/sites/www/faq.rst new file mode 100644 index 00000000..a7e80014 --- /dev/null +++ b/sites/www/faq.rst @@ -0,0 +1,9 @@ +=================================== +Frequently Asked/Answered Questions +=================================== + +Which version should I use? I see multiple active releases. +=========================================================== + +Please see :ref:`the installation docs ` which have an explicit +section about this topic. diff --git a/sites/www/index.rst b/sites/www/index.rst index a8e72624..0864decd 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -13,6 +13,7 @@ usage and API documentation can be found at our code documentation site, .. toctree:: changelog + faq installing contributing contact diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 955a0a59..7d61632d 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -2,6 +2,8 @@ Installing ========== +.. _paramiko-itself: + Paramiko itself =============== @@ -23,6 +25,28 @@ PyCrypto C extension. `ecdsa` is easily installable from wherever you obtained Paramiko's package; PyCrypto may require more work. Read on for details. +.. _release-lines: + +Release lines +------------- + +Users desiring stability may wish to pin themselves to a specific release line +once they first start using Paramiko; to assist in this, we guarantee bugfixes +for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**. + +If you're unsure which version to install, we have suggestions: + +* **Completely new users** should always default to the **latest stable + release** (as above, whatever is newest / whatever shows up with ``pip + install paramiko``.) +* **Users upgrading from a much older version** (e.g. the 1.7.x line) should + probably get the **oldest actively supported line** (see the paragraph above + this list for what that currently is.) +* **Everybody else** is hopefully already "on" a given version and can + carefully upgrade to whichever version they care to, when their release line + stops being supported. + + PyCrypto ======== -- cgit v1.2.3 From 7feeb272a059ac189de1c2c375baca0916c6fc54 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 21 Mar 2014 17:28:25 -0700 Subject: Uggh how did this slip in --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 7d61632d..74c5c6e8 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -7,7 +7,7 @@ Installing Paramiko itself =============== -The recommended way to get Invoke is to **install the latest stable release** +The recommended way to get Paramiko is to **install the latest stable release** via `pip `_:: $ pip install paramiko -- cgit v1.2.3 From 178e43060c52b9f65026a5ec57bbe5fae166ba4e Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 21 Aug 2014 09:28:58 -0700 Subject: This isn't worth having and then always forgetting about --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index a28ce6cd..546aad9d 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -32,7 +32,7 @@ Release lines Users desiring stability may wish to pin themselves to a specific release line once they first start using Paramiko; to assist in this, we guarantee bugfixes -for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**. +for at least the last 2-3 releases including the latest stable one. If you're unsure which version to install, we have suggestions: -- cgit v1.2.3 From e941d56e8a385f4f2ef5c0e9a77e66c844b5a729 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 21 Aug 2014 09:30:12 -0700 Subject: More tweaks - don't make it sound like we routinely support >3, we don't --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 546aad9d..729147c5 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -32,7 +32,7 @@ Release lines Users desiring stability may wish to pin themselves to a specific release line once they first start using Paramiko; to assist in this, we guarantee bugfixes -for at least the last 2-3 releases including the latest stable one. +for the last 2-3 releases including the latest stable one. If you're unsure which version to install, we have suggestions: -- cgit v1.2.3 From 2a88241ea7ed3facf730678ef28a8281903cf9a9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 25 Aug 2014 16:27:15 -0700 Subject: Add a plus to our 3.3 support to denote 3.4 and on --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 729147c5..052825c4 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -16,7 +16,7 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.6, 2.7 and 3.3** (Python **3.2** should also +We currently support **Python 2.6, 2.7 and 3.3+** (Python **3.2** should also work but has a less-strong compatibility guarantee from us.) Users on Python 2.5 or older are urged to upgrade. -- cgit v1.2.3 From 150b0797e935ebf2f62e86ae1c08a1a1ab94c459 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Mon, 8 Sep 2014 16:36:33 -0700 Subject: Update README, docs, changelog re #267 --- README | 16 +++------------- sites/www/changelog.rst | 4 ++-- sites/www/installing.rst | 28 +++++++++++++++++++++++++++- 3 files changed, 32 insertions(+), 16 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/README b/README index ceb3598a..b5ccb697 100644 --- a/README +++ b/README @@ -75,19 +75,9 @@ Please file bug reports at https://github.com/paramiko/paramiko/. There is curre Kerberos Support ---------------- -If you want paramiko to do kerberos authentication or key exchange using GSS-API or SSPI, you -need the following python packages: - -- pyasn1 0.1.7 or better -- python-gssapi 0.6.1 or better (Unix) -- pywin32 2.1.8 or better (Windows) - -So you have to install pyasn1 and python-gssapi on Unix or pywin32 on Windows. -To enable GSS-API / SSPI authentication or key exchange see the demos or paramiko docs. -Note: If you use Microsoft SSPI for kerberos authentication and credential -delegation in paramiko, make sure that the target host is trusted for -delegation in the active directory configuration. For details see: -http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx +Paramiko ships with optional Kerberos/GSSAPI support; for info on the extra +dependencies for this, see the 'GSS-API' section on the 'Installation' page of +our main website, http://paramiko.org . Demo diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index a42cfb3d..3be56890 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -3,8 +3,8 @@ Changelog ========= * :feature:`250` (also :issue:`267`) Add GSS-API / SSPI (e.g. Kerberos) key - exchange and authentication support. Mega thanks to Sebastian Deiß, with - assist by Torsten Landschoff. + exchange and authentication support (:ref:`installation docs here `). + Mega thanks to Sebastian Deiß, with assist by Torsten Landschoff. * :bug:`346 major` Fix an issue in private key files' encryption salts that could cause tracebacks and file corruption if keys were re-encrypted. Credit to Xavier Nunn. diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 052825c4..5528b28a 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -20,11 +20,14 @@ We currently support **Python 2.6, 2.7 and 3.3+** (Python **3.2** should also work but has a less-strong compatibility guarantee from us.) Users on Python 2.5 or older are urged to upgrade. -Paramiko has two dependencies: the pure-Python ECDSA module ``ecdsa``, and the +Paramiko has two hard dependencies: the pure-Python ECDSA module ``ecdsa``, and the PyCrypto C extension. ``ecdsa`` is easily installable from wherever you obtained Paramiko's package; PyCrypto may require more work. Read on for details. +If you need GSS-API / SSPI support, see :ref:`the below subsection on it +` for details on additional dependencies. + .. _release-lines: Release lines @@ -99,3 +102,26 @@ installation of Paramiko via ``pypm``:: Installing paramiko-1.7.8 Installing pycrypto-2.4 C:\> + + +.. _gssapi: + +Optional dependencies for GSS-API / SSPI / Kerberos +=================================================== + +In order to use Kerberos & related functionality, a couple of additional +dependencies are required (these are not listed in our ``setup.py`` due to +their infrequent utility & non-platform-agnostic requirements): + +* **All platforms** need `pyasn1 `_ + ``0.1.7`` or better. +* **Unix** needs `python-gssapi `_ + ``0.6.1`` or better. +* **Windows** needs `pywin32 `_ ``2.1.8`` + or better. + +.. note:: + If you use Microsoft SSPI for kerberos authentication and credential + delegation, make sure that the target host is trusted for delegation in the + active directory configuration. For details see: + http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx -- cgit v1.2.3 From 8df6f80337208374304085dbc9408aa1bae5f1e9 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 18 Sep 2014 15:19:01 -0700 Subject: Install docs tweak re: GSSAPI req --- sites/www/installing.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 5528b28a..486ed7e3 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -109,10 +109,12 @@ installation of Paramiko via ``pypm``:: Optional dependencies for GSS-API / SSPI / Kerberos =================================================== -In order to use Kerberos & related functionality, a couple of additional -dependencies are required (these are not listed in our ``setup.py`` due to -their infrequent utility & non-platform-agnostic requirements): +In order to use GSS-API/Kerberos & related functionality, a couple of +additional dependencies are required (these are not listed in our ``setup.py`` +due to their infrequent utility & non-platform-agnostic requirements): +* It hopefully goes without saying but **all platforms** need **a working + installation of GSS-API itself**, e.g. Heimdal. * **All platforms** need `pyasn1 `_ ``0.1.7`` or better. * **Unix** needs `python-gssapi `_ -- cgit v1.2.3 From 8bdd921d4c5c607b7c1f568df27f5460acd5a548 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Thu, 18 Sep 2014 15:34:48 -0700 Subject: Note how python-gssapi only works on 2.7+ --- sites/www/changelog.rst | 6 ++++++ sites/www/installing.rst | 3 +++ 2 files changed, 9 insertions(+) (limited to 'sites/www/installing.rst') diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 1dab5219..a40338b0 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -6,6 +6,12 @@ Changelog SSPI (e.g. Kerberos) key exchange and authentication support (:ref:`installation docs here `). Mega thanks to Sebastian Deiß, with assist by Torsten Landschoff. + + .. note:: + Unix users should be aware that the ``python-gssapi`` library (a + requirement for using this functionality) only appears to support + Python 2.7 and up at this time. + * :bug:`346 major` Fix an issue in private key files' encryption salts that could cause tracebacks and file corruption if keys were re-encrypted. Credit to Xavier Nunn. diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 486ed7e3..a657c3fc 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -119,6 +119,9 @@ due to their infrequent utility & non-platform-agnostic requirements): ``0.1.7`` or better. * **Unix** needs `python-gssapi `_ ``0.6.1`` or better. + + .. note:: This library appears to only function on Python 2.7 and up. + * **Windows** needs `pywin32 `_ ``2.1.8`` or better. -- cgit v1.2.3