Merge branch 'master' into 502-int

16 files changed, 290 insertions, 234 deletions

diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst
index 3b614a82..f01ad972 100644
--- a/sites/docs/api/agent.rst
+++ b/sites/docs/api/agent.rst
@@ -1,4 +1,4 @@
-SSH Agents
+SSH agents
 ==========
 
 .. automodule:: paramiko.agent
diff --git a/sites/docs/api/kex_gss.rst b/sites/docs/api/kex_gss.rst
new file mode 100644
index 00000000..9fd09221
--- /dev/null
+++ b/sites/docs/api/kex_gss.rst
@@ -0,0 +1,5 @@
+GSS-API key exchange
+====================
+
+.. automodule:: paramiko.kex_gss
+    :member-order: bysource
diff --git a/sites/docs/api/ssh_gss.rst b/sites/docs/api/ssh_gss.rst
new file mode 100644
index 00000000..7a687e11
--- /dev/null
+++ b/sites/docs/api/ssh_gss.rst
@@ -0,0 +1,14 @@
+GSS-API authentication
+======================
+
+.. automodule:: paramiko.ssh_gss
+    :member-order: bysource
+
+.. autoclass:: _SSH_GSSAuth
+    :member-order: bysource
+
+.. autoclass:: _SSH_GSSAPI
+    :member-order: bysource
+
+.. autoclass:: _SSH_SSPI
+    :member-order: bysource
diff --git a/sites/docs/index.rst b/sites/docs/index.rst
index f336b393..87265d95 100644
--- a/sites/docs/index.rst
+++ b/sites/docs/index.rst
@@ -50,6 +50,8 @@ Authentication & keys
     api/agent
     api/hostkeys
     api/keys
+    api/ssh_gss
+    api/kex_gss
 
 
 Other primary functions
diff --git a/sites/shared_conf.py b/sites/shared_conf.py
index 4a6a5c4e..99fab315 100644
--- a/sites/shared_conf.py
+++ b/sites/shared_conf.py
@@ -12,7 +12,6 @@ html_theme_options = {
     'description': "A Python implementation of SSHv2.",
     'github_user': 'paramiko',
     'github_repo': 'paramiko',
-    'gratipay_user': 'bitprophet',
     'analytics_id': 'UA-18486793-2',
     'travis_button': True,
 }
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