diff options
Diffstat (limited to 'sites/www')
| -rw-r--r-- | sites/www/blog.py | 140 | ||||
| -rw-r--r-- | sites/www/blog.rst | 16 | ||||
| -rw-r--r-- | sites/www/blog/first-post.rst | 7 | ||||
| -rw-r--r-- | sites/www/blog/second-post.rst | 7 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 163 | ||||
| -rw-r--r-- | sites/www/conf.py | 12 | ||||
| -rw-r--r-- | sites/www/contact.rst | 1 | ||||
| -rw-r--r-- | sites/www/contributing.rst | 19 | ||||
| -rw-r--r-- | sites/www/faq.rst | 26 | ||||
| -rw-r--r-- | sites/www/index.rst | 20 | ||||
| -rw-r--r-- | sites/www/installing.rst | 89 |
11 files changed, 268 insertions, 232 deletions
diff --git a/sites/www/blog.py b/sites/www/blog.py deleted file mode 100644 index 3b129ebf..00000000 --- a/sites/www/blog.py +++ /dev/null @@ -1,140 +0,0 @@ -from collections import namedtuple -from datetime import datetime -import time -import email.utils - -from sphinx.util.compat import Directive -from docutils import nodes - - -class BlogDateDirective(Directive): - """ - Used to parse/attach date info to blog post documents. - - No nodes generated, since none are needed. - """ - has_content = True - - def run(self): - # Tag parent document with parsed date value. - self.state.document.blog_date = datetime.strptime( - self.content[0], "%Y-%m-%d" - ) - # Don't actually insert any nodes, we're already done. - return [] - -class blog_post_list(nodes.General, nodes.Element): - pass - -class BlogPostListDirective(Directive): - """ - Simply spits out a 'blog_post_list' temporary node for replacement. - - Gets replaced at doctree-resolved time - only then will all blog post - documents be written out (& their date directives executed). - """ - def run(self): - return [blog_post_list('')] - - -Post = namedtuple('Post', 'name doc title date opener') - -def get_posts(app): - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Obtain common data used for list page & RSS - data = [] - for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True): - # Welp. No "nice" way to get post title. Thanks Sphinx. - title = doc[0][0][0] - # Date. This may or may not end up reflecting the required - # *input* format, but doing it here gives us flexibility. - date = doc.blog_date - # 1st paragraph as opener. TODO: allow a role or something marking - # where to actually pull from? - opener = doc.traverse(nodes.paragraph)[0] - data.append(Post(post, doc, title, date, opener)) - return data - -def replace_blog_post_lists(app, doctree, fromdocname): - """ - Replace blog_post_list nodes with ordered list-o-links to posts. - """ - # Obtain blog posts - post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs) - posts = map(lambda x: (x, app.env.get_doctree(x)), post_names) - # Build "list" of links/etc - post_links = [] - for post, doc, title, date, opener in get_posts(app): - # Link itself - uri = app.builder.get_relative_uri(fromdocname, post) - link = nodes.reference('', '', refdocname=post, refuri=uri) - # Title, bolded. TODO: use 'topic' or something maybe? - link.append(nodes.strong('', title)) - date = date.strftime("%Y-%m-%d") - # Meh @ not having great docutils nodes which map to this. - html = '<div class="timestamp"><span>%s</span></div>' % date - timestamp = nodes.raw(text=html, format='html') - # NOTE: may group these within another element later if styling - # necessitates it - group = [timestamp, nodes.paragraph('', '', link), opener] - post_links.extend(group) - - # Replace temp node(s) w/ expanded list-o-links - for node in doctree.traverse(blog_post_list): - node.replace_self(post_links) - -def rss_timestamp(timestamp): - # Use horribly inappropriate module for its magical daylight-savings-aware - # timezone madness. Props to Tinkerer for the idea. - return email.utils.formatdate( - time.mktime(timestamp.timetuple()), - localtime=True - ) - -def generate_rss(app): - # Meh at having to run this subroutine like 3x per build. Not worth trying - # to be clever for now tho. - posts_ = get_posts(app) - # LOL URLs - root = app.config.rss_link - if not root.endswith('/'): - root += '/' - # Oh boy - posts = [ - ( - root + app.builder.get_target_uri(x.name), - x.title, - str(x.opener[0]), # Grab inner text element from paragraph - rss_timestamp(x.date), - ) - for x in posts_ - ] - location = 'blog/rss.xml' - context = { - 'title': app.config.project, - 'link': root, - 'atom': root + location, - 'description': app.config.rss_description, - # 'posts' is sorted by date already - 'date': rss_timestamp(posts_[0].date), - 'posts': posts, - } - yield (location, context, 'rss.xml') - -def setup(app): - # Link in RSS feed back to main website, e.g. 'http://paramiko.org' - app.add_config_value('rss_link', None, '') - # Ditto for RSS description field - app.add_config_value('rss_description', None, '') - # Interprets date metadata in blog post documents - app.add_directive('date', BlogDateDirective) - # Inserts blog post list node (in e.g. a listing page) for replacement - # below - app.add_node(blog_post_list) - app.add_directive('blog-posts', BlogPostListDirective) - # Performs abovementioned replacement - app.connect('doctree-resolved', replace_blog_post_lists) - # Generates RSS page from whole cloth at page generation step - app.connect('html-collect-pages', generate_rss) diff --git a/sites/www/blog.rst b/sites/www/blog.rst deleted file mode 100644 index af9651e4..00000000 --- a/sites/www/blog.rst +++ /dev/null @@ -1,16 +0,0 @@ -==== -Blog -==== - -.. blog-posts directive gets replaced with an ordered list of blog posts. - -.. blog-posts:: - - -.. The following toctree ensures blog posts get processed. - -.. toctree:: - :hidden: - :glob: - - blog/* diff --git a/sites/www/blog/first-post.rst b/sites/www/blog/first-post.rst deleted file mode 100644 index 7b075073..00000000 --- a/sites/www/blog/first-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -First post! -=========== - -A blog post. - -.. date:: 2013-12-04 diff --git a/sites/www/blog/second-post.rst b/sites/www/blog/second-post.rst deleted file mode 100644 index c4463f33..00000000 --- a/sites/www/blog/second-post.rst +++ /dev/null @@ -1,7 +0,0 @@ -=========== -Another one -=========== - -.. date:: 2013-12-05 - -Indeed! diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 50447c04..bd890b4e 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -4,18 +4,110 @@ Changelog * :bug:`502` Fix an issue in server mode, when processing an exec request. A command that is not a valid UTF-8 string, caused an UnicodeDecodeError. +* :bug:`401` Fix line number reporting in log output regarding invalid + ``known_hosts`` line entries. Thanks to Dylan Thacker-Smith for catch & + patch. +* :support:`525 backported` Update the vendored Windows API addon to a more + recent edition. Also fixes :issue:`193`, :issue:`488`, :issue:`498`. Thanks + to Jason Coombs. +* :release:`1.15.4 <2015-11-02>` +* :release:`1.14.3 <2015-11-02>` +* :release:`1.13.4 <2015-11-02>` +* :bug:`366` Fix `~paramiko.sftp_attributes.SFTPAttributes` so its string + representation doesn't raise exceptions on empty/initialized instances. Patch + by Ulrich Petri. +* :bug:`359` Use correct attribute name when trying to use Python 3's + ``int.bit_length`` method; prior to fix, the Python 2 custom fallback + implementation was always used, even on Python 3. Thanks to Alex Gaynor. +* :support:`594 backported` Correct some post-Python3-port docstrings to + specify ``bytes`` type instead of ``str``. Credit to ``@redixin``. +* :bug:`565` Don't explode with ``IndexError`` when reading private key files + lacking an ``-----END <type> PRIVATE KEY-----`` footer. Patch courtesy of + Prasanna Santhanam. +* :feature:`604` Add support for the ``aes192-ctr`` and ``aes192-cbc`` ciphers. + Thanks to Michiel Tiller for noticing it was as easy as tweaking some key + sizes :D +* :feature:`356` (also :issue:`596`, :issue:`365`, :issue:`341`, :issue:`164`, + :issue:`581`, and a bunch of other duplicates besides) Add support for SHA-2 + based key exchange (kex) algorithm ``diffie-hellman-group-exchange-sha256`` + and (H)MAC algorithms ``hmac-sha2-256`` and ``hmac-sha2-512``. + + This change includes tweaks to debug-level logging regarding + algorithm-selection handshakes; the old all-in-one log line is now multiple + easier-to-read, printed-at-handshake-time log lines. + + Thanks to the many people who submitted patches for this functionality and/or + assisted in testing those patches. That list includes but is not limited to, + and in no particular order: Matthias Witte, Dag Wieers, Ash Berlin, Etienne + Perot, Gert van Dijk, ``@GuyShaanan``, Aaron Bieber, ``@cyphase``, and Eric + Brown. +* :release:`1.15.3 <2015-10-02>` +* :support:`554 backported` Fix inaccuracies in the docstring for the ECDSA key + class. Thanks to Jared Hance for the patch. +* :support:`516 backported` Document `~paramiko.agent.AgentRequestHandler`. + Thanks to ``@toejough`` for report & suggestions. +* :bug:`496` Fix a handful of small but critical bugs in Paramiko's GSSAPI + support (note: this includes switching from PyCrypo's Random to + `os.urandom`). Thanks to Anselm Kruis for catch & patch. +* :bug:`491` (combines :issue:`62` and :issue:`439`) Implement timeout + functionality to address hangs from dropped network connections and/or failed + handshakes. Credit to ``@vazir`` and ``@dacut`` for the original patches and + to Olle Lundberg for reimplementation. +* :bug:`490` Skip invalid/unparseable lines in ``known_hosts`` files, instead + of raising `~paramiko.ssh_exception.SSHException`. This brings Paramiko's + behavior more in line with OpenSSH, which silently ignores such input. Catch + & patch courtesy of Martin Topholm. +* :bug:`404` Print details when displaying + `~paramiko.ssh_exception.BadHostKeyException` objects (expected vs received + data) instead of just "hey shit broke". Patch credit: Loic Dachary. +* :bug:`469` (also :issue:`488`, :issue:`461` and like a dozen others) Fix a + typo introduced in the 1.15 release which broke WinPageant support. Thanks to + everyone who submitted patches, and to Steve Cohen who was the lucky winner + of the cherry-pick lottery. +* :bug:`353` (via :issue:`482`) Fix a bug introduced in the Python 3 port + which caused ``OverFlowError`` (and other symptoms) in SFTP functionality. + Thanks to ``@dboreham`` for leading the troubleshooting charge, and to + Scott Maxwell for the final patch. +* :support:`582` Fix some old ``setup.py`` related helper code which was + breaking ``bdist_dumb`` on Mac OS X. Thanks to Peter Odding for the patch. +* :bug:`22 major` Try harder to connect to multiple network families (e.g. IPv4 + vs IPv6) in case of connection issues; this helps with problems such as hosts + which resolve both IPv4 and IPv6 addresses but are only listening on IPv4. + Thanks to Dries Desmet for original report and Torsten Landschoff for the + foundational patchset. +* :bug:`402` Check to see if an SSH agent is actually present before trying to + forward it to the remote end. This replaces what was usually a useless + ``TypeError`` with a human-readable + `~paramiko.ssh_exception.AuthenticationException`. Credit to Ken Jordan for + the fix and Yvan Marques for original report. +* :release:`1.15.2 <2014-12-19>` +* :release:`1.14.2 <2014-12-19>` * :release:`1.13.3 <2014-12-19>` * :bug:`413` (also :issue:`414`, :issue:`420`, :issue:`454`) Be significantly smarter about polling & timing behavior when running proxy commands, to avoid unnecessary (often 100%!) CPU usage. Major thanks to Jason Dunsmore for report & initial patchset and to Chris Adams & John Morrissey for followup improvements. +* :bug:`455` Tweak packet size handling to conform better to the OpenSSH RFCs; + this helps address issues with interactive program cursors. Courtesy of Jeff + Quast. * :bug:`428` Fix an issue in `~paramiko.file.BufferedFile` (primarily used in the SFTP modules) concerning incorrect behavior by `~paramiko.file.BufferedFile.readlines` on files whose size exceeds the buffer size. Thanks to ``@achapp`` for catch & patch. +* :bug:`415` Fix ``ssh_config`` parsing to correctly interpret ``ProxyCommand + none`` as the lack of a proxy command, instead of as a literal command string + of ``"none"``. Thanks to Richard Spiers for the catch & Sean Johnson for the + fix. +* :support:`431 backported` Replace handrolled ``ssh_config`` parsing code with + use of the ``shlex`` module. Thanks to Yan Kalchevskiy. * :support:`422 backported` Clean up some unused imports. Courtesy of Olle Lundberg. +* :support:`421 backported` Modernize threading calls to user newer API. Thanks + to Olle Lundberg. +* :support:`419 backported` Modernize a bunch of the codebase internals to + leverage decorators. Props to ``@beckjake`` for realizing we're no longer on + Python 2.2 :D * :bug:`266` Change numbering of `~paramiko.transport.Transport` channels to start at 0 instead of 1 for better compatibility with OpenSSH & certain server implementations which break on 1-indexed channels. Thanks to @@ -29,10 +121,69 @@ Changelog for the catch. * :bug:`320` Update our win_pageant module to be Python 3 compatible. Thanks to ``@sherbang`` and ``@adamkerz`` for the patches. +* :release:`1.15.1 <2014-09-22>` +* :bug:`399` SSH agent forwarding (potentially other functionality as + well) would hang due to incorrect values passed into the new window size + arguments for `.Transport` (thanks to a botched merge). This has been + corrected. Thanks to Dylan Thacker-Smith for the report & patch. +* :feature:`167` Add `.SSHConfig.get_hostnames` for easier introspection of a + loaded SSH config file or object. Courtesy of Søren Løvborg. +* :release:`1.15.0 <2014-09-18>` +* :support:`393` Replace internal use of PyCrypto's ``SHA.new`` with the + stdlib's ``hashlib.sha1``. Thanks to Alex Gaynor. +* :feature:`267` (also :issue:`250`, :issue:`241`, :issue:`228`) Add GSS-API / + SSPI (e.g. Kerberos) key exchange and authentication support + (:ref:`installation docs here <gssapi>`). 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. +* :feature:`362` Allow users to control the SSH banner timeout. Thanks to Cory + Benfield. +* :feature:`372` Update default window & packet sizes to more closely adhere to + the pertinent RFC; also expose these settings in the public API so they may + be overridden by client code. This should address some general speed issues + such as :issue:`175`. Big thanks to Olle Lundberg for the update. +* :bug:`373 major` Attempt to fix a handful of issues (such as :issue:`354`) + related to infinite loops and threading deadlocks. Thanks to Olle Lundberg as + well as a handful of community members who provided advice & feedback via + IRC. +* :support:`374` (also :issue:`375`) Old code cleanup courtesy of Olle + Lundberg. +* :support:`377` Factor `~paramiko.channel.Channel` openness sanity check into + a decorator. Thanks to Olle Lundberg for original patch. +* :bug:`298 major` Don't perform point validation on ECDSA keys in + ``known_hosts`` files, since a) this can cause significant slowdown when such + keys exist, and b) ``known_hosts`` files are implicitly trustworthy. Thanks + to Kieran Spear for catch & patch. + + .. note:: + This change bumps up the version requirement for the ``ecdsa`` library to + ``0.11``. + +* :bug:`234 major` Lower logging levels for a few overly-noisy log messages + about secure channels. Thanks to David Pursehouse for noticing & contributing + the fix. +* :feature:`218` Add support for ECDSA private keys on the client side. Thanks + to ``@aszlig`` for the patch. +* :bug:`335 major` Fix ECDSA key generation (generation of brand new ECDSA keys + was broken previously). Thanks to ``@solarw`` for catch & patch. +* :feature:`184` Support quoted values in SSH config file parsing. Credit to + Yan Kalchevskiy. +* :feature:`131` Add a `~paramiko.sftp_client.SFTPClient.listdir_iter` method + to `~paramiko.sftp_client.SFTPClient` allowing for more efficient, + async/generator based file listings. Thanks to John Begeman. * :support:`378 backported` Minor code cleanup in the SSH config module courtesy of Olle Lundberg. * :support:`249 backported` Consolidate version information into one spot. Thanks to Gabi Davar for the reminder. +* :release:`1.14.1 <2014-08-25>` * :release:`1.13.2 <2014-08-25>` * :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` files, which results in a speedup of SSH config parsing. Credit to Olle @@ -59,6 +210,9 @@ Changelog Thanks to ``@basictheprogram`` for the initial report, Jelmer Vernooij for the fix and Andrew Starr-Bochicchio & Jeremy T. Bouse (among others) for discussion & feedback. +* :support:`371` Add Travis support & docs update for Python 3.4. Thanks to + Olle Lundberg. +* :release:`1.14.0 <2014-05-07>` * :release:`1.13.1 <2014-05-07>` * :release:`1.12.4 <2014-05-07>` * :release:`1.11.6 <2014-05-07>` @@ -83,6 +237,12 @@ Changelog character. Thanks to Antoine Brenner. * :bug:`308` Fix regression in dsskey.py that caused sporadic signature verification failures. Thanks to Chris Rose. +* :support:`299` Use deterministic signatures for ECDSA keys for improved + security. Thanks to Alex Gaynor. +* :support:`297` Replace PyCrypto's ``Random`` with `os.urandom` for improved + speed and security. Thanks again to Alex. +* :support:`295` Swap out a bunch of PyCrypto hash functions with use of + `hashlib`. Thanks to Alex Gaynor. * :support:`290` (also :issue:`292`) Add support for building universal (Python 2+3 compatible) wheel files during the release process. Courtesy of Alex Gaynor. @@ -96,7 +256,8 @@ Changelog * :release:`1.11.5 <2014-03-13>` * :release:`1.10.7 <2014-03-13>` * :feature:`16` **Python 3 support!** Our test suite passes under Python 3, and - it (& Fabric's test suite) continues to pass under Python 2. + it (& Fabric's test suite) continues to pass under Python 2. **Python 2.5 is + no longer supported with this change!** The merged code was built on many contributors' efforts, both code & feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny, diff --git a/sites/www/conf.py b/sites/www/conf.py index c7828203..0b0fb85c 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -6,24 +6,16 @@ from os.path import abspath, join, dirname sys.path.append(abspath(join(dirname(__file__), '..'))) from shared_conf import * -# Local blog extension -sys.path.append(abspath('.')) -extensions.append('blog') -rss_link = 'http://paramiko.org' -rss_description = 'Paramiko project news' - # Releases changelog extension extensions.append('releases') -releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s" +# Paramiko 1.x tags start with 'v'. Meh. +releases_release_uri = "https://github.com/paramiko/paramiko/tree/v%s" releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" -# Intersphinx for referencing API/usage docs -extensions.append('sphinx.ext.intersphinx') # Default is 'local' building, but reference the public docs site when building # under RTD. target = join(dirname(__file__), '..', 'docs', '_build') if os.environ.get('READTHEDOCS') == 'True': - # TODO: switch to docs.paramiko.org post go-live of sphinx API docs target = 'http://docs.paramiko.org/en/latest/' intersphinx_mapping['docs'] = (target, None) diff --git a/sites/www/contact.rst b/sites/www/contact.rst index 2b6583f5..7e6c947e 100644 --- a/sites/www/contact.rst +++ b/sites/www/contact.rst @@ -9,3 +9,4 @@ following ways: * Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage <http://librelist.com>`_ for usage details). * This website - a blog section is forthcoming. +* Submit contributions on Github - see the :doc:`contributing` page. diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst index 2b752cc5..a44414e8 100644 --- a/sites/www/contributing.rst +++ b/sites/www/contributing.rst @@ -5,15 +5,22 @@ Contributing How to get the code =================== -Our primary Git repository is on Github at `paramiko/paramiko -<https://github.com/paramiko/paramiko>`_; please follow their instructions for -cloning to your local system. (If you intend to submit patches/pull requests, -we recommend forking first, then cloning your fork. Github has excellent -documentation for all this.) +Our primary Git repository is on Github at `paramiko/paramiko`_; +please follow their instructions for cloning to your local system. (If you +intend to submit patches/pull requests, we recommend forking first, then +cloning your fork. Github has excellent documentation for all this.) How to submit bug reports or new code ===================================== Please see `this project-agnostic contribution guide -<http://contribution-guide.org>`_ - we follow it explicitly. +<http://contribution-guide.org>`_ - we follow it explicitly. Again, our code +repository and bug tracker is `on Github`_. + +Our current changelog is located in ``sites/www/changelog.rst`` - the top +level files like ``ChangeLog.*`` and ``NEWS`` are historical only. + + +.. _paramiko/paramiko: +.. _on Github: https://github.com/paramiko/paramiko diff --git a/sites/www/faq.rst b/sites/www/faq.rst new file mode 100644 index 00000000..a5d9b383 --- /dev/null +++ b/sites/www/faq.rst @@ -0,0 +1,26 @@ +=================================== +Frequently Asked/Answered Questions +=================================== + +Which version should I use? I see multiple active releases. +=========================================================== + +Please see :ref:`the installation docs <release-lines>` which have an explicit +section about this topic. + +Paramiko doesn't work with my Cisco, Windows or other non-Unix system! +====================================================================== + +In an ideal world, the developers would love to support every possible target +system. Unfortunately, volunteer development time and access to non-mainstream +platforms are limited, meaning that we can only fully support standard OpenSSH +implementations such as those found on the average Linux distribution (as well +as on Mac OS X and \*BSD.) + +Because of this, **we typically close bug reports for nonstandard SSH +implementations or host systems**. + +However, **closed does not imply locked** - affected users can still post +comments on such tickets - and **we will always consider actual patch +submissions for these issues**, provided they can get +1s from similarly +affected users and are proven to not break existing functionality. diff --git a/sites/www/index.rst b/sites/www/index.rst index 0f07d7e9..8e7562af 100644 --- a/sites/www/index.rst +++ b/sites/www/index.rst @@ -1,7 +1,7 @@ Welcome to Paramiko! ==================== -Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_, +Paramiko is a Python (2.6+, 3.3+) implementation of the SSHv2 protocol [#]_, providing both client and server functionality. While it leverages a Python C extension for low level cryptography (`PyCrypto <http://pycrypto.org>`_), Paramiko itself is a pure Python interface around SSH networking concepts. @@ -11,30 +11,22 @@ contribution guidelines, development roadmap, news/blog, and so forth. Detailed usage and API documentation can be found at our code documentation site, `docs.paramiko.org <http://docs.paramiko.org>`_. +Please see the sidebar to the left to begin. + .. toctree:: :hidden: changelog + FAQs <faq> installing contributing contact -.. Hide blog in hidden toctree for now (to avoid warnings.) - -.. toctree:: - :hidden: - - blog - .. rubric:: Footnotes .. [#] - SSH is defined in RFCs - `4251 <http://www.rfc-editor.org/rfc/rfc4251.txt>`_, - `4252 <http://www.rfc-editor.org/rfc/rfc4252.txt>`_, - `4253 <http://www.rfc-editor.org/rfc/rfc4253.txt>`_, and - `4254 <http://www.rfc-editor.org/rfc/rfc4254.txt>`_; - the primary working implementation of the protocol is the `OpenSSH project + SSH is defined in :rfc:`4251`, :rfc:`4252`, :rfc:`4253` and :rfc:`4254`. The + primary working implementation of the protocol is the `OpenSSH project <http://openssh.org>`_. Paramiko implements a large portion of the SSH feature set, but there are occasional gaps. diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 0ca9b156..a657c3fc 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -2,6 +2,8 @@ Installing ========== +.. _paramiko-itself: + Paramiko itself =============== @@ -14,50 +16,47 @@ via `pip <http://pip-installer.org>`_:: 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 +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. -PyCrypto -======== - -`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ provides the low-level -(C-based) encryption algorithms we need to implement the SSH protocol. 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. +If you need GSS-API / SSPI support, see :ref:`the below subsection on it +<gssapi>` for details on additional dependencies. -.. _pycrypto-and-pip: +.. _release-lines: -Possible gotcha on older Python and/or pip versions ---------------------------------------------------- +Release lines +------------- -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: +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 the last 2-3 releases including the latest stable one. -* Python = 2.5.x -* PyCrypto >= 2.1 (required for most modern versions of Paramiko) -* ``pip`` < 0.8.1 +If you're unsure which version to install, we have suggestions: -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``. +* **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. -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) +PyCrypto +======== +`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ provides the low-level +(C-based) encryption algorithms we need to implement the SSH protocol. 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. C extension ----------- @@ -103,3 +102,31 @@ 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 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 <https://pypi.python.org/pypi/pyasn1>`_ + ``0.1.7`` or better. +* **Unix** needs `python-gssapi <https://pypi.python.org/pypi/python-gssapi/>`_ + ``0.6.1`` or better. + + .. note:: This library appears to only function on Python 2.7 and up. + +* **Windows** needs `pywin32 <https://pypi.python.org/pypi/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 |