diff options
Diffstat (limited to 'sites')
30 files changed, 859 insertions, 0 deletions
diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst new file mode 100644 index 00000000..3b614a82 --- /dev/null +++ b/sites/docs/api/agent.rst @@ -0,0 +1,6 @@ +SSH Agents +========== + +.. automodule:: paramiko.agent + :inherited-members: + :no-special-members: diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst new file mode 100644 index 00000000..54d87c59 --- /dev/null +++ b/sites/docs/api/buffered_pipe.rst @@ -0,0 +1,4 @@ +Buffered pipes +============== + +.. automodule:: paramiko.buffered_pipe diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst new file mode 100644 index 00000000..e71526f6 --- /dev/null +++ b/sites/docs/api/channel.rst @@ -0,0 +1,4 @@ +Channel +======= + +.. automodule:: paramiko.channel diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst new file mode 100644 index 00000000..b201812f --- /dev/null +++ b/sites/docs/api/client.rst @@ -0,0 +1,5 @@ +Client +====== + +.. automodule:: paramiko.client + :member-order: bysource diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst new file mode 100644 index 00000000..afb004c9 --- /dev/null +++ b/sites/docs/api/config.rst @@ -0,0 +1,5 @@ +Configuration +============= + +.. automodule:: paramiko.config + :member-order: bysource diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst new file mode 100644 index 00000000..199f3ecc --- /dev/null +++ b/sites/docs/api/file.rst @@ -0,0 +1,4 @@ +Buffered files +============== + +.. automodule:: paramiko.file diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst new file mode 100644 index 00000000..770652fd --- /dev/null +++ b/sites/docs/api/hostkeys.rst @@ -0,0 +1,5 @@ +Host keys / ``known_hosts`` files +================================= + +.. automodule:: paramiko.hostkeys + :member-order: bysource diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst new file mode 100644 index 00000000..c6412f77 --- /dev/null +++ b/sites/docs/api/keys.rst @@ -0,0 +1,23 @@ +============ +Key handling +============ + +Parent key class +================ + +.. automodule:: paramiko.pkey + +DSA (DSS) +========= + +.. automodule:: paramiko.dsskey + +RSA +=== + +.. automodule:: paramiko.rsakey + +ECDSA +===== + +.. automodule:: paramiko.ecdsakey diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst new file mode 100644 index 00000000..8d531e01 --- /dev/null +++ b/sites/docs/api/message.rst @@ -0,0 +1,4 @@ +Message +======= + +.. automodule:: paramiko.message diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst new file mode 100644 index 00000000..4089203b --- /dev/null +++ b/sites/docs/api/packet.rst @@ -0,0 +1,4 @@ +Packetizer +========== + +.. automodule:: paramiko.packet diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst new file mode 100644 index 00000000..e480446f --- /dev/null +++ b/sites/docs/api/pipe.rst @@ -0,0 +1,4 @@ +Cross-platform pipe implementations +=================================== + +.. automodule:: paramiko.pipe diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst new file mode 100644 index 00000000..489b14e7 --- /dev/null +++ b/sites/docs/api/proxy.rst @@ -0,0 +1,4 @@ +``ProxyCommand`` support +======================== + +.. automodule:: paramiko.proxy diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst new file mode 100644 index 00000000..ea854544 --- /dev/null +++ b/sites/docs/api/server.rst @@ -0,0 +1,5 @@ +Server implementation +===================== + +.. automodule:: paramiko.server + :member-order: bysource diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst new file mode 100644 index 00000000..956eada2 --- /dev/null +++ b/sites/docs/api/sftp.rst @@ -0,0 +1,13 @@ +SFTP +==== + +.. automodule:: paramiko.sftp +.. automodule:: paramiko.sftp_client +.. automodule:: paramiko.sftp_server +.. automodule:: paramiko.sftp_attr +.. automodule:: paramiko.sftp_file + :inherited-members: + :no-special-members: + :show-inheritance: +.. automodule:: paramiko.sftp_handle +.. automodule:: paramiko.sftp_si diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst new file mode 100644 index 00000000..64872dc2 --- /dev/null +++ b/sites/docs/api/ssh_exception.rst @@ -0,0 +1,4 @@ +Exceptions +========== + +.. automodule:: paramiko.ssh_exception diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst new file mode 100644 index 00000000..7c9d9fd1 --- /dev/null +++ b/sites/docs/api/transport.rst @@ -0,0 +1,5 @@ +Transport +========= + +.. automodule:: paramiko.transport + :member-order: bysource diff --git a/sites/docs/conf.py b/sites/docs/conf.py new file mode 100644 index 00000000..5674fed1 --- /dev/null +++ b/sites/docs/conf.py @@ -0,0 +1,16 @@ +# Obtain shared config values +import os, sys +sys.path.append(os.path.abspath('..')) +sys.path.append(os.path.abspath('../..')) +from shared_conf import * + +# Enable autodoc, intersphinx +extensions.extend(['sphinx.ext.autodoc']) + +# Autodoc settings +autodoc_default_flags = ['members', 'special-members'] + +# Sister-site links to WWW +html_theme_options['extra_nav_links'] = { + "Main website": 'http://www.paramiko.org', +} diff --git a/sites/docs/index.rst b/sites/docs/index.rst new file mode 100644 index 00000000..f336b393 --- /dev/null +++ b/sites/docs/index.rst @@ -0,0 +1,72 @@ +==================================== +Welcome to Paramiko's documentation! +==================================== + +This site covers Paramiko's usage & API documentation. For basic info on what +Paramiko is, including its public changelog & how the project is maintained, +please see `the main project website <http://paramiko.org>`_. + + +API documentation +================= + +The high-level client API starts with creation of an `.SSHClient` object. For +more direct control, pass a socket (or socket-like object) to a `.Transport`, +and use `start_server <.Transport.start_server>` or `start_client +<.Transport.start_client>` to negotiate with the remote host as either a server +or client. + +As a client, you are responsible for authenticating using a password or private +key, and checking the server's host key. (Key signature and verification is +done by paramiko, but you will need to provide private keys and check that the +content of a public key matches what you expected to see.) + +As a server, you are responsible for deciding which users, passwords, and keys +to allow, and what kind of channels to allow. + +Once you have finished, either side may request flow-controlled `channels +<.Channel>` to the other side, which are Python objects that act like sockets, +but send and receive data over the encrypted session. + +For details, please see the following tables of contents (which are organized +by area of interest.) + + +Core SSH protocol classes +------------------------- + +.. toctree:: + api/channel + api/client + api/message + api/packet + api/transport + + +Authentication & keys +--------------------- + +.. toctree:: + api/agent + api/hostkeys + api/keys + + +Other primary functions +----------------------- + +.. toctree:: + api/config + api/proxy + api/server + api/sftp + + +Miscellany +---------- + +.. toctree:: + api/buffered_pipe + api/file + api/pipe + api/ssh_exception diff --git a/sites/shared_conf.py b/sites/shared_conf.py new file mode 100644 index 00000000..4a6a5c4e --- /dev/null +++ b/sites/shared_conf.py @@ -0,0 +1,41 @@ +from datetime import datetime + +import alabaster + + +# Alabaster theme + mini-extension +html_theme_path = [alabaster.get_path()] +extensions = ['alabaster', 'sphinx.ext.intersphinx'] +# Paths relative to invoking conf.py - not this shared file +html_theme = 'alabaster' +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, +} +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + 'searchbox.html', + 'donate.html', + ] +} + +# Everything intersphinx's to Python +intersphinx_mapping = { + 'python': ('http://docs.python.org/2.6', None), +} + +# Regular settings +project = 'Paramiko' +year = datetime.now().year +copyright = '%d Jeff Forcier' % year +master_doc = 'index' +templates_path = ['_templates'] +exclude_trees = ['_build'] +source_suffix = '.rst' +default_role = 'obj' diff --git a/sites/www/_templates/rss.xml b/sites/www/_templates/rss.xml new file mode 100644 index 00000000..f6f9cbd1 --- /dev/null +++ b/sites/www/_templates/rss.xml @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="utf-8"?> +<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <atom:link href="{{ atom }}" rel="self" type="application/rss+xml" /> + <title>{{ title }}</title> + <link>{{ link }}</link> + <description>{{ description }}</description> + <pubDate>{{ date }}</pubDate> + {% for link, title, desc, date in posts %} + <item> + <link>{{ link }}</link> + <guid>{{ link }}</guid> + <title><![CDATA[{{ title }}]]></title> + <description><![CDATA[{{ desc }}]]></description> + <pubDate>{{ date }}</pubDate> + </item> + {% endfor %} + </channel> +</rss> diff --git a/sites/www/blog.py b/sites/www/blog.py new file mode 100644 index 00000000..3b129ebf --- /dev/null +++ b/sites/www/blog.py @@ -0,0 +1,140 @@ +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 new file mode 100644 index 00000000..af9651e4 --- /dev/null +++ b/sites/www/blog.rst @@ -0,0 +1,16 @@ +==== +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 new file mode 100644 index 00000000..7b075073 --- /dev/null +++ b/sites/www/blog/first-post.rst @@ -0,0 +1,7 @@ +=========== +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 new file mode 100644 index 00000000..c4463f33 --- /dev/null +++ b/sites/www/blog/second-post.rst @@ -0,0 +1,7 @@ +=========== +Another one +=========== + +.. date:: 2013-12-05 + +Indeed! diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst new file mode 100644 index 00000000..9ce2eded --- /dev/null +++ b/sites/www/changelog.rst @@ -0,0 +1,234 @@ +========= +Changelog +========= + +* :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:`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. +* :support:`422 backported` Clean up some unused imports. Courtesy of Olle + Lundberg. +* :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 + ``@egroeper`` for catch & patch. +* :bug:`459` Tighten up agent connection closure behavior to avoid spurious + ``ResourceWarning`` display in some situations. Thanks to ``@tkrapp`` for the + catch. +* :bug:`429` Server-level debug message logging was overlooked during the + Python 3 compatibility update; Python 3 clients attempting to log SSH debug + packets encountered type errors. This is now fixed. Thanks to ``@mjmaenpaa`` + for the catch. +* :bug:`320` Update our win_pageant module to be Python 3 compatible. Thanks to + ``@sherbang`` and ``@adamkerz`` for the patches. +* :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.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 + Lundberg. +* :support:`324 backported` A bevvy of documentation typo fixes, courtesy of Roy + Wellington. +* :bug:`312` `paramiko.transport.Transport` had a bug in its ``__repr__`` which + surfaces during errors encountered within its ``__init__``, causing + problematic tracebacks in such situations. Thanks to Simon Percivall for + catch & patch. +* :bug:`272` Fix a bug where ``known_hosts`` parsing hashed the input hostname + as well as the hostnames from the ``known_hosts`` file, on every comparison. + Thanks to ``@sigmunau`` for final patch and ``@ostacey`` for the original + report. +* :bug:`239` Add Windows-style CRLF support to SSH config file parsing. Props + to Christopher Swenson. +* :support:`229 backported` Fix a couple of incorrectly-copied docstrings' ``.. + versionadded::`` RST directives. Thanks to Aarni Koskela for the catch. +* :support:`169 backported` Minor refactor of + `paramiko.sftp_client.SFTPClient.put` thanks to Abhinav Upadhyay. +* :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim + to handle ``buffer`` objects correctly; this fixes a frequently reported + issue affecting many users, including users of the ``bzr`` software suite. + Thanks to ``@basictheprogram`` for the initial report, Jelmer Vernooij for + the fix and Andrew Starr-Bochicchio & Jeremy T. Bouse (among others) for + discussion & feedback. +* :release:`1.13.1 <2014-05-07>` +* :release:`1.12.4 <2014-05-07>` +* :release:`1.11.6 <2014-05-07>` +* :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings + after the Python 3 migration, despite bytes being more appropriate for file + contents (which may be binary or of an unknown encoding.) This has been + addressed. + + .. note:: + `paramiko.file.BufferedFile.readline` continues to return strings, not + bytes, as "lines" only make sense for textual data. It assumes UTF-8 by + default. + + This should fix `this issue raised on the Obnam mailing list + <http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252>`_. Thanks + to Antoine Brenner for the patch. +* :bug:`-` Added self.args for exception classes. Used for unpickling. Related + to (`Fabric #986 <https://github.com/fabric/fabric/issues/986>`_, `Fabric + #714 <https://github.com/fabric/fabric/issues/714>`_). Thanks to Alex + Plugaru. +* :bug:`-` Fix logging error in sftp_client for filenames containing the '%' + character. Thanks to Antoine Brenner. +* :bug:`308` Fix regression in dsskey.py that caused sporadic signature + verification failures. Thanks to Chris Rose. +* :support:`290` (also :issue:`292`) Add support for building universal + (Python 2+3 compatible) wheel files during the release process. Courtesy of + Alex Gaynor. +* :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks + to Alex Gaynor for catch & patch. +* :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if + type(x) is str/if isinstance(x, basestring)/g``.) Thanks to ``@ksamuel`` for + the report. +* :release:`1.13.0 <2014-03-13>` +* :release:`1.12.3 <2014-03-13>` +* :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. + + The merged code was built on many contributors' efforts, both code & + feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny, + Tomi Pieviläinen, Jason R. Coombs, Jan N. Schulze, ``@Lazik``, Dorian Pula, + Scott Maxwell, Tshepang Lekhonkhobe, Aaron Meurer, and Dave Halter. +* :support:`256 backported` Convert API documentation to Sphinx, yielding a new + API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for + the initial conversion work. +* :bug:`-` Use constant-time hash comparison operations where possible, to + protect against `timing-based attacks + <http://codahale.com/a-lesson-in-timing-attacks/>`_. Thanks to Alex Gaynor + for the patch. +* :release:`1.12.2 <2014-02-14>` +* :release:`1.11.4 <2014-02-14>` +* :release:`1.10.6 <2014-02-14>` +* :feature:`58` Allow client code to access the stored SSH server banner via + `Transport.get_banner <paramiko.transport.Transport.get_banner>`. Thanks to + ``@Jhoanor`` for the patch. +* :bug:`252` (`Fabric #1020 <https://github.com/fabric/fabric/issues/1020>`_) + Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang + condition that frequently occurs at ``Transport`` shutdown time. Thanks to + Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original + reports and to Marius Gedminas for helping test nontrivial use cases. +* :bug:`268` Fix some missed renames of ``ProxyCommand`` related error classes. + Thanks to Marius Gedminas for catch & patch. +* :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some + SFTP servers regarding request/response ordering. Thanks to Richard + Kettlewell. +* :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`) Fix SSH agent + problems present on Windows. Thanks to David Hobbs for initial report and to + Aarni Koskela & Olle Lundberg for the patches. +* :release:`1.12.1 <2014-01-08>` +* :release:`1.11.3 <2014-01-08>` +* :release:`1.10.5 <2014-01-08>` +* :bug:`225 (1.12+)` Note ecdsa requirement in README. Thanks to Amaury + Rodriguez for the catch. +* :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks + to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test + case. +* :release:`1.12.0 <2013-09-27>` +* :release:`1.11.2 <2013-09-27>` +* :release:`1.10.4 <2013-09-27>` +* :feature:`152` Add tentative support for ECDSA keys. **This adds the ecdsa + module as a new dependency of Paramiko.** The module is available at + `warner/python-ecdsa on Github <https://github.com/warner/python-ecdsa>`_ and + `ecdsa on PyPI <https://pypi.python.org/pypi/ecdsa>`_. + + * Note that you might still run into problems with key negotiation -- + Paramiko picks the first key that the server offers, which might not be + what you have in your known_hosts file. + * Mega thanks to Ethan Glasser-Camp for the patch. + +* :feature:`136` Add server-side support for the SSH protocol's 'env' command. + Thanks to Benjamin Pollack for the patch. +* :bug:`156 (1.11+)` Fix potential deadlock condition when using Channel + objects as sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan + and Frank Arnold for catch & patch. +* :bug:`179` Fix a missing variable causing errors when an ssh_config file has + a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for + catch & patch. +* :bug:`200` Fix an exception-causing typo in ``demo_simple.py``. Thanks to Alex + Buchanan for catch & Dave Foster for patch. +* :bug:`199` Typo fix in the license header cross-project. Thanks to Armin + Ronacher for catch & patch. +* :release:`1.11.1 <2013-09-20>` +* :release:`1.10.3 <2013-09-20>` +* :bug:`162` Clean up HMAC module import to avoid deadlocks in certain uses of + SSHClient. Thanks to Gernot Hillier for the catch & suggested fix. +* :bug:`36` Fix the port-forwarding demo to avoid file descriptor errors. + Thanks to Jonathan Halcrow for catch & patch. +* :bug:`168` Update config handling to properly handle multiple 'localforward' + and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. +* :release:`1.11.0 <2013-07-26>` +* :release:`1.10.2 <2013-07-26>` +* :bug:`98 major` On Windows, when interacting with the PuTTY PAgeant, Paramiko + now creates the shared memory map with explicit Security Attributes of the + user, which is the same technique employed by the canonical PuTTY library to + avoid permissions issues when Paramiko is running under a different UAC + context than the PuTTY Ageant process. Thanks to Jason R. Coombs for the + patch. +* :support:`100` Remove use of PyWin32 in ``win_pageant`` module. Module was + already dependent on ctypes for constructing appropriate structures and had + ctypes implementations of all functionality. Thanks to Jason R. Coombs for + the patch. +* :bug:`87 major` Ensure updates to ``known_hosts`` files account for any + updates to said files after Paramiko initially read them. (Includes related + fix to guard against duplicate entries during subsequent ``known_hosts`` + loads.) Thanks to ``@sunweaver`` for the contribution. +* :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts + file. Thanks to ``@glasserc`` for patch. +* :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for + catch & patch. +* :release:`1.10.1 <2013-04-05>` +* :bug:`142` (`Fabric #811 <https://github.com/fabric/fabric/issues/811>`_) + SFTP put of empty file will still return the attributes of the put file. + Thanks to Jason R. Coombs for the patch. +* :bug:`154` (`Fabric #876 <https://github.com/fabric/fabric/issues/876>`_) + Forwarded SSH agent connections left stale local pipes lying around, which + could cause local (and sometimes remote or network) resource starvation when + running many agent-using remote commands. Thanks to Kevin Tegtmeier for catch + & patch. +* :release:`1.10.0 <2013-03-01>` +* :feature:`66` Batch SFTP writes to help speed up file transfers. Thanks to + Olle Lundberg for the patch. +* :bug:`133 major` Fix handling of window-change events to be on-spec and not + attempt to wait for a response from the remote sshd; this fixes problems with + less common targets such as some Cisco devices. Thanks to Phillip Heller for + catch & patch. +* :feature:`93` Overhaul SSH config parsing to be in line with ``man + ssh_config`` (& the behavior of ``ssh`` itself), including addition of parameter + expansion within config values. Thanks to Olle Lundberg for the patch. +* :feature:`110` Honor SSH config ``AddressFamily`` setting when looking up + local host's FQDN. Thanks to John Hensley for the patch. +* :feature:`128` Defer FQDN resolution until needed, when parsing SSH config + files. Thanks to Parantapa Bhattacharya for catch & patch. +* :bug:`102 major` Forego random padding for packets when running under + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random + byte generation is inefficient (e.g. Windows). Thanks to ``@warthog618`` for + catch & patch, and Michael van der Kolff for code/technique review. +* :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael + Williamson for the patch. +* :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect + against potential DoS vectors. Thanks to ``@mvschaik`` for catch & patch. +* :feature:`115` Add convenience ``get_pty`` kwarg to ``Client.exec_command`` so + users not manually controlling a channel object can still toggle PTY + creation. Thanks to Michael van der Kolff for the patch. +* :feature:`71` Add ``SFTPClient.putfo`` and ``.getfo`` methods to allow direct + uploading/downloading of file-like objects. Thanks to Eric Buehl for the + patch. +* :feature:`113` Add ``timeout`` parameter to ``SSHClient.exec_command`` for + easier setting of the command's internal channel object's timeout. Thanks to + Cernov Vladimir for the patch. +* :support:`94` Remove duplication of SSH port constant. Thanks to Olle + Lundberg for the catch. +* :feature:`80` Expose the internal "is closed" property of the file transfer + class ``BufferedFile`` as ``.closed``, better conforming to Python's file + interface. Thanks to ``@smunaut`` and James Hiscock for catch & patch. diff --git a/sites/www/conf.py b/sites/www/conf.py new file mode 100644 index 00000000..c7828203 --- /dev/null +++ b/sites/www/conf.py @@ -0,0 +1,33 @@ +# Obtain shared config values +import sys +import os +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" +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) + +# Sister-site links to API docs +html_theme_options['extra_nav_links'] = { + "API Docs": 'http://docs.paramiko.org', +} diff --git a/sites/www/contact.rst b/sites/www/contact.rst new file mode 100644 index 00000000..2b6583f5 --- /dev/null +++ b/sites/www/contact.rst @@ -0,0 +1,11 @@ +======= +Contact +======= + +You can get in touch with the developer & user community in any of the +following ways: + +* IRC: ``#paramiko`` on Freenode +* Mailing list: ``paramiko@librelist.com`` (see `the LibreList homepage + <http://librelist.com>`_ for usage details). +* This website - a blog section is forthcoming. diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst new file mode 100644 index 00000000..2b752cc5 --- /dev/null +++ b/sites/www/contributing.rst @@ -0,0 +1,19 @@ +============ +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.) + + +How to submit bug reports or new code +===================================== + +Please see `this project-agnostic contribution guide +<http://contribution-guide.org>`_ - we follow it explicitly. diff --git a/sites/www/index.rst b/sites/www/index.rst new file mode 100644 index 00000000..0f07d7e9 --- /dev/null +++ b/sites/www/index.rst @@ -0,0 +1,40 @@ +Welcome to Paramiko! +==================== + +Paramiko is a Python (2.5+) 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. + +This website covers project information for Paramiko such as the changelog, +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>`_. + +.. toctree:: + :hidden: + + changelog + 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 + <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 new file mode 100644 index 00000000..0ca9b156 --- /dev/null +++ b/sites/www/installing.rst @@ -0,0 +1,105 @@ +========== +Installing +========== + +Paramiko itself +=============== + +The recommended way to get Paramiko is to **install the latest stable release** +via `pip <http://pip-installer.org>`_:: + + $ pip install paramiko + +.. note:: + 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. + +Paramiko has two 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. + +.. _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 +----------- + +Unless you are installing from a precompiled source such as a Debian apt +repository or RedHat RPM, or using :ref:`pypm <pypm>`, you will also need the +ability to build Python C-based modules from source in order to install +PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will +need the traditional C build toolchain installed (e.g. Developer Tools / XCode +Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux +-- basically, anything with ``gcc``, ``make`` and so forth) as well as the +Python development libraries, often named ``python-dev`` or similar. + +For **Windows** users we recommend using :ref:`pypm`, installing a C +development environment such as `Cygwin <http://cygwin.com>`_ or obtaining a +precompiled Win32 PyCrypto package from `voidspace's Python modules page +<http://www.voidspace.org.uk/python/modules.shtml#pycrypto>`_. + +.. note:: + Some Windows users whose Python is 64-bit have found that the PyCrypto + dependency ``winrandom`` may not install properly, leading to ImportErrors. + In this scenario, you'll probably need to compile ``winrandom`` yourself + via e.g. MS Visual Studio. See `Fabric #194 + <https://github.com/fabric/fabric/issues/194>`_ for info. + + +.. _pypm: + +ActivePython and PyPM +===================== + +Windows users who already have ActiveState's `ActivePython +<http://www.activestate.com/activepython/downloads>`_ distribution installed +may find Paramiko is best installed with `its package manager, PyPM +<http://code.activestate.com/pypm/>`_. Below is example output from an +installation of Paramiko via ``pypm``:: + + C:\> pypm install paramiko + The following packages will be installed into "%APPDATA%\Python" (2.7): + paramiko-1.7.8 pycrypto-2.4 + Get: [pypm-free.activestate.com] paramiko 1.7.8 + Get: [pypm-free.activestate.com] pycrypto 2.4 + Installing paramiko-1.7.8 + Installing pycrypto-2.4 + C:\> |