diff options
Diffstat (limited to 'sites')
| -rw-r--r-- | sites/docs/api/agent.rst | 6 | ||||
| -rw-r--r-- | sites/docs/api/buffered_pipe.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/channel.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/client.rst | 5 | ||||
| -rw-r--r-- | sites/docs/api/config.rst | 5 | ||||
| -rw-r--r-- | sites/docs/api/file.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/hostkeys.rst | 5 | ||||
| -rw-r--r-- | sites/docs/api/keys.rst | 6 | ||||
| -rw-r--r-- | sites/docs/api/message.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/packet.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/pipe.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/proxy.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/server.rst | 5 | ||||
| -rw-r--r-- | sites/docs/api/sftp.rst | 13 | ||||
| -rw-r--r-- | sites/docs/api/ssh_exception.rst | 4 | ||||
| -rw-r--r-- | sites/docs/api/transport.rst | 5 | ||||
| -rw-r--r-- | sites/docs/conf.py | 16 | ||||
| -rw-r--r-- | sites/docs/index.rst | 72 | ||||
| -rw-r--r-- | sites/shared_conf.py | 41 | ||||
| -rw-r--r-- | sites/www/_templates/rss.xml | 19 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 220 | ||||
| -rw-r--r-- | sites/www/conf.py | 25 | ||||
| -rw-r--r-- | sites/www/contact.rst | 12 | ||||
| -rw-r--r-- | sites/www/contributing.rst | 26 | ||||
| -rw-r--r-- | sites/www/faq.rst | 26 | ||||
| -rw-r--r-- | sites/www/index.rst | 36 | ||||
| -rw-r--r-- | sites/www/installing.rst | 101 |
27 files changed, 676 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..af7b58c4 --- /dev/null +++ b/sites/docs/api/keys.rst @@ -0,0 +1,6 @@ +Key handling +============ + +.. automodule:: paramiko.pkey +.. automodule:: paramiko.dsskey +.. automodule:: paramiko.rsakey 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/changelog.rst b/sites/www/changelog.rst new file mode 100644 index 00000000..24679d5f --- /dev/null +++ b/sites/www/changelog.rst @@ -0,0 +1,220 @@ +========= +Changelog +========= + +* :support:`378 backported` Minor code cleanup in the SSH config module + courtesy of Olle Lundberg. +* :support:`249` 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 + 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. +* :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>` +* :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:`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. +* :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. **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, + 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..0b0fb85c --- /dev/null +++ b/sites/www/conf.py @@ -0,0 +1,25 @@ +# 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 * + +# Releases changelog extension +extensions.append('releases') +# 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" + +# 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': + 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..7e6c947e --- /dev/null +++ b/sites/www/contact.rst @@ -0,0 +1,12 @@ +======= +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. +* Submit contributions on Github - see the :doc:`contributing` page. diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst new file mode 100644 index 00000000..a44414e8 --- /dev/null +++ b/sites/www/contributing.rst @@ -0,0 +1,26 @@ +============ +Contributing +============ + +How to get the code +=================== + +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. 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 new file mode 100644 index 00000000..1b609709 --- /dev/null +++ b/sites/www/index.rst @@ -0,0 +1,36 @@ +Welcome to Paramiko! +==================== + +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. + +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>`_. + +Please see the sidebar to the left to begin. + +.. toctree:: + :hidden: + + changelog + FAQs <faq> + installing + contributing + contact + + +.. 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..052825c4 --- /dev/null +++ b/sites/www/installing.rst @@ -0,0 +1,101 @@ +========== +Installing +========== + +.. _paramiko-itself: + +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.6, 2.7 and 3.3+** (Python **3.2** should also +work but has a less-strong compatibility guarantee from us.) Users on Python +2.5 or older are urged to upgrade. + +Paramiko has two dependencies: the pure-Python ECDSA module ``ecdsa``, and the +PyCrypto C extension. ``ecdsa`` is easily installable from wherever you +obtained Paramiko's package; PyCrypto may require more work. Read on for +details. + +.. _release-lines: + +Release lines +------------- + +Users desiring stability may wish to pin themselves to a specific release line +once they first start using Paramiko; to assist in this, we guarantee bugfixes +for the last 2-3 releases including the latest stable one. + +If you're unsure which version to install, we have suggestions: + +* **Completely new users** should always default to the **latest stable + release** (as above, whatever is newest / whatever shows up with ``pip + install paramiko``.) +* **Users upgrading from a much older version** (e.g. the 1.7.x line) should + probably get the **oldest actively supported line** (see the paragraph above + this list for what that currently is.) +* **Everybody else** is hopefully already "on" a given version and can + carefully upgrade to whichever version they care to, when their release line + stops being supported. + + +PyCrypto +======== + +`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 +----------- + +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:\> |