From 8ffef33a1694d7b9ba4dad0d3f7b0f45d0eee8df Mon Sep 17 00:00:00 2001
From: Scott Duckworth <sduckwo@clemson.edu>
Date: Wed, 26 Mar 2014 11:34:29 -0400
Subject: [PATCH] replace markdown with reStructuredText
---
README.md | 144 ------------------------------------------------------------------------------------------------------------------------------------------------
README.rst | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.upgrading.md | 53 -----------------------------------------------------
README.upgrading.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 226 insertions(+), 197 deletions(-)
delete mode 100644 README.md
create mode 100644 README.rst
delete mode 100644 README.upgrading.md
create mode 100644 README.upgrading.rst
diff --git a/README.md b/README.md
deleted file mode 100644
index 2488e0b..0000000
--- a/README.md
+++ /dev/null
@@ -1,144 +0,0 @@
-# django-sshkey
-
-django-sshkey allows you to associate multiple SSH public keys with Django
-user accounts. It provides views to list, add, edit, and delete keys, each of
-which is intended for end-user consumption. It also provides a lookup view
-and corresponding lookup commands that are suitable for use with the
-`AuthorizedKeysCommand` feature in [OpenSSH][1] 6.2 and above.
-
-## The Django app
-
-To use django-sshkey in your Django project, simply add `django_sshkey` to
-`INSTALLED_APPS` in `settings.py`, map the URLs into your project, and provide
-templates for the views (example templates are provided in the source).
-
-In order to associate an incoming public key with a user you must define
-`SSHKEY_AUTHORIZED_KEYS_OPTIONS` in your project's `settings.py`. This should
-be a string containing options accepted by sshd, with `{username}` being
-replaced with the username of the user associated with the incoming public key.
-
-For instance:
-
- SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
-
-in settings.py will cause keys produced by the below commands to look similar
-to:
-
- command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
-
-assuming the key `AAAAB3NzaC1yc2E...` is owned by fred.
-
-### URL Configuration
-
-This text assumes that your project's `urls.py` maps `django_sshkey.urls` into
-the URL namespace as follows:
-
- import django_sshkey.urls
- urlpatterns = patterns('',
- ...
- url('^sshkey/', include(django_sshkey.urls)),
- ...
- )
-
-You will need to adjust your URLs in the examples below if you use a different
-mapping.
-
-**WARNING**: The `/sshkey/lookup` URL can expose all public keys that have
-been uploaded to your site. Although they are public keys, it is probably a
-good idea to limit what systems can access this URL via your web server's
-configuration (most of the lookup methods below require access to this URL).
-
-## Tying OpenSSH to django-sshkey
-
-There are multiple methods of connecting OpenSSH to django-sshkey. All of the
-methods listed here require the use of the `AuthorizedKeysCommand` directive
-in `sshd_config` present in OpenSSH 6.2 and above. Please note that the
-command that is referenced by this directive and its ancestor directories must
-be owned by root and writable only by owner.
-
-Unless otherwise stated, all of the methods below use the `SSHKEY_LOOKUP_URL`
-environment variable to determine the URL of the `/sshkey/lookup` URL. If
-this environment variable is not defined then it will default to
-`http://localhost:8000/sshkey/lookup`. If this environment variable is
-defined in the sshd process then it will be inherited by the
-`AuthorizedKeysCommand`.
-
-Additionally, all of the methods below use either `curl` (preferred) or `wget`.
-Some commands also use `ssh-keygen`. These commands must be present in `PATH`.
-
-If you would prefer not to use these external commands then there are variants
-of these commands implemented purely in Python. However, they are *much*
-slower. To use the variants, replace `lookup` with `pylookup`. For example,
-use `django-sshkey-pylookup-all` instead of `django-sshkey-lookup-all`.
-
-### Using `django-sshkey-lookup-all`
-
-`Usage: django-sshkey-lookup-all`
-
-This program prints all SSH public keys that are defined on your site. sshd
-will have to scan through all of them to find the first match, so with many
-keys this method will be slow. However, it does not require a patched OpenSSH
-server.
-
-This program:
-
- * can be used directly with `AuthorizedKeysCommand` (the username parameter
- is ignored).
- * does not require a patched OpenSSH server.
- * does not scale well to a large number of user keys.
-
-### Using `django-sshkey-lookup-by-username`
-
-`Usage: django-sshkey-lookup-by-username USERNAME`
-
-This program prints all SSH public keys that are associated with the specified
-user.
-
-This program:
-
- * can be used directly with `AuthorizedKeysCommand`.
- * does not require a patched OpenSSH server.
- * is ideal if each Django user corresponds to a system user account.
-
-### Using `django-sshkey-lookup-by-fingerprint`
-
-`Usage: django-sshkey-lookup-by-fingerprint`
-
-This program prints all SSH public keys that match the given fingerprint. The
-fingerprint is determined by the first of the following conditions that is met:
-
- 1. The `SSH_KEY_FINGERPRINT` environment variable, which should contain the
- MD5 fingerprint of the key (this is what is generated by `ssh-keygen -l`).
- 2. The `SSH_KEY` environment variable, which should contain the key in
- standard openssh format (the same format as `~/.ssh/id_rsa.pub`), is sent
- to `ssh-keygen -l` to determine the fingerprint.
- 3. The key in standard openssh format is read from standard input and is
- sent to `ssh-keygen -l` to determine the fingerprint.
-
-This program:
-
- * can be used directly with `AuthorizedKeysCommand` (the username parameter
- is ignored).
- * requires a patched OpenSSH server; compatible patches can be found at one
- of the following locations:
- * [openssh-akcenv][2] (this is the preferred patch)
- * [openssh-stdinkey][3]
- * is ideal if you want all Django users to access SSH via a shared system
- user account and be identified by their SSH public key.
-
-### Using `django-sshkey-lookup`
-
-`Usage: django-sshkey-lookup URL [USERNAME]`
-
-This program is a wrapper around the previous two commands. The first
-parameter is placed in the `SSHKEY_LOOKUP_URL` environment variable. If the
-second parameter is present then `django-sshkey-lookup-by-username` is
-executed; otherwise `django-sshkey-lookup-by-fingerprint` is executed.
-
-This command is compatible with the old script `lookup.sh` but was renamed to
-have a less ambiguous name when installed system-wide. A symlink is left in
-its place for backwards compatibility.
-
-[1]: http://www.openssh.com/
-[2]: https://github.com/ScottDuckworth/openssh-akcenv
-[3]: https://github.com/ScottDuckworth/openssh-stdinkey
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..8cc327d
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,170 @@
+=============
+django-sshkey
+=============
+
+django-sshkey allows you to associate multiple SSH public keys with Django
+user accounts. It provides views to list, add, edit, and delete keys, each of
+which is intended for end-user consumption. It also provides a lookup view
+and corresponding lookup commands that are suitable for use with the
+``AuthorizedKeysCommand`` feature in OpenSSH_ 6.2 and above.
+
+The Django app
+==============
+
+To use django-sshkey in your Django project, simply add ``django_sshkey`` to
+``INSTALLED_APPS`` in ``settings.py``, map the URLs into your project, and
+provide templates for the views (example templates are provided in the source).
+
+In order to associate an incoming public key with a user you must define
+``SSHKEY_AUTHORIZED_KEYS_OPTIONS`` in your project's ``settings.py``. This
+should be a string containing options accepted by sshd, with ``{username}``
+being replaced with the username of the user associated with the incoming
+public key.
+
+For instance::
+
+ SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
+
+in settings.py will cause keys produced by the below commands to look similar
+to::
+
+ command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
+
+assuming the key ``AAAAB3NzaC1yc2E...`` is owned by fred.
+
+URL Configuration
+-----------------
+
+This text assumes that your project's ``urls.py`` maps ``django_sshkey.urls``
+into the URL namespace as follows::
+
+ import django_sshkey.urls
+ urlpatterns = patterns('',
+ ...
+ url('^sshkey/', include(django_sshkey.urls)),
+ ...
+ )
+
+You will need to adjust your URLs in the examples below if you use a different
+mapping.
+
+.. WARNING::
+
+ The ``/sshkey/lookup`` URL can expose all public keys that have
+ been uploaded to your site. Although they are public keys, it is probably a
+ good idea to limit what systems can access this URL via your web server's
+ configuration. Most of the lookup methods below require access to this URL,
+ and only the systems that need to run the lookup commands should have access
+ to it.
+
+Tying OpenSSH to django-sshkey
+==============================
+
+There are multiple methods of connecting OpenSSH to django-sshkey. All of the
+methods listed here require the use of the ``AuthorizedKeysCommand`` directive
+in ``sshd_config`` present in OpenSSH 6.2 and above. Please note that the
+command that is referenced by this directive and its ancestor directories must
+be owned by root and writable only by owner.
+
+Unless otherwise stated, all of the methods below use the ``SSHKEY_LOOKUP_URL``
+environment variable to determine the URL of the ``/sshkey/lookup`` URL. If
+this environment variable is not defined then it will default to
+``http://localhost:8000/sshkey/lookup``. If this environment variable is
+defined in the sshd process then it will be inherited by the
+``AuthorizedKeysCommand``.
+
+Additionally, all of the methods below use either ``curl`` (preferred) or
+``wget``. Some commands also use ``ssh-keygen``. These commands must be
+present in ``PATH``.
+
+If you would prefer not to use these external commands then there are variants
+of the lookup commands implemented purely in Python. However, they are *much*
+slower. To use the variants, replace ``lookup`` with ``pylookup``. For
+example, use ``django-sshkey-pylookup-all`` instead of
+``django-sshkey-lookup-all``.
+
+Using ``django-sshkey-lookup-all``
+----------------------------------
+
+``Usage: django-sshkey-lookup-all``
+
+This program prints all SSH public keys that are defined on your site. sshd
+will have to scan through all of them to find the first match, so with many
+keys this method will be slow. However, it does not require a patched OpenSSH
+server.
+
+This program:
+
+ * can be used directly with ``AuthorizedKeysCommand`` (the username
+ parameter is ignored).
+
+ * does not require a patched OpenSSH server.
+
+ * does not scale well to a large number of user keys.
+
+Using ``django-sshkey-lookup-by-username``
+------------------------------------------
+
+``Usage: django-sshkey-lookup-by-username USERNAME``
+
+This program prints all SSH public keys that are associated with the specified
+user.
+
+This program:
+
+ * can be used directly with ``AuthorizedKeysCommand``.
+
+ * does not require a patched OpenSSH server.
+
+ * is ideal if each Django user corresponds to a system user account.
+
+Using ``django-sshkey-lookup-by-fingerprint``
+---------------------------------------------
+
+``Usage: django-sshkey-lookup-by-fingerprint``
+
+This program prints all SSH public keys that match the given fingerprint. The
+fingerprint is determined by the first of the following that is found:
+
+ 1. The ``SSH_KEY_FINGERPRINT`` environment variable, which should contain
+ the MD5 fingerprint of the key (this is the second field generated by
+ ``ssh-keygen -l``).
+
+ 2. The ``SSH_KEY`` environment variable, which should contain the key in
+ standard openssh format (the same format as ``~/.ssh/id_rsa.pub``), is
+ sent to ``ssh-keygen -l`` to determine the fingerprint.
+
+ 3. The key in standard openssh format is read from standard input and is
+ sent to ``ssh-keygen -l`` to determine the fingerprint.
+
+This program:
+
+ * can be used directly with ``AuthorizedKeysCommand`` (the username
+ parameter is ignored).
+
+ * requires a patched OpenSSH server; compatible patches can be found at one
+ of the following locations:
+
+ - openssh-akcenv_ (this is the preferred patch)
+ - openssh-stdinkey_
+
+ * is ideal if you want all Django users to access SSH via a shared system
+ user account and be identified by their SSH public key.
+
+Using ``django-sshkey-lookup``
+------------------------------
+
+``Usage: django-sshkey-lookup URL [USERNAME]``
+
+This program is a wrapper around the previous two commands. The first
+parameter is placed in the ``SSHKEY_LOOKUP_URL`` environment variable. If the
+second parameter is present then ``django-sshkey-lookup-by-username`` is
+executed; otherwise ``django-sshkey-lookup-by-fingerprint`` is executed.
+
+This command is compatible with the old script ``lookup.sh`` but was renamed
+to have a less ambiguous name when installed system-wide. A symlink is left in
+its place for backwards compatibility.
+
+.. _OpenSSH: http://www.openssh.com/
+.. _openssh-akcenv: https://github.com/ScottDuckworth/openssh-akcenv
+.. _openssh-stdinkey: https://github.com/ScottDuckworth/openssh-stdinkey
diff --git a/README.upgrading.md b/README.upgrading.md
deleted file mode 100644
index 78a048c..0000000
--- a/README.upgrading.md
+++ /dev/null
@@ -1,53 +0,0 @@
-Upgrading and Downgrading
-=========================
-
-django-sshkey is equipped with [South][1] migrations. This makes changes to
-the database schema in upgrades or downgrades a simple process. Migrations
-will only be present on minor version changes.
-
-To use South migrations, you must have the south app in your project's
-INSTALLED_APPS.
-
-The following table maps django-sshkey version to migration labels:
-
- Version App Name Label Notes
- 1.0.x sshkey 0001 Migrations were not present in 1.0.x
- 1.1.x sshkey 0002
- 2.0.x django_sshkey 0001 See Upgrading from 1.1.x to 2.x below
-
-
-To upgrade, install the new version of django-sshkey and then migrate your
-project to its corresponding label from the table above using the following
-command:
-
- python manage.py migrate <app_name> <label>
-
-To downgrade, perform the migration down to the label of the desired version
-before installing the older django-sshkey.
-
-
-Upgrading from 1.1.x to 2.x
----------------------------
-
-django-sshkey 2.x renames the sshkey app to django_sshkey. However, the
-database table names are not changed.
-
-To upgrade, all references to the sshkey module must be changed to
-django_sshkey. This includes all instances of "import sshkey" or
-"from sshkey import ..." and all references to sshkey in url patterns, views,
-or templates, as well as updating INSTALLED_APPS in settings.py.
-
-Once you have made those changes you will need to fake the initial migration
-for django_sshkey:
-
- python manage.py migrate --fake django_sshkey 0001_initial
-
-This completes the upgrade process. The only thing that remains is the two
-existing migration records in the south_migrationhistory table from the now
-nonexistent sshkey app. These records do not cause any problems, but they can
-be removed at your discrection using the following SQL statement on your
-database:
-
- DELETE FROM south_migrationhistory WHERE app_name="sshkey";
-
-[1]: http://south.aeracode.org/
diff --git a/README.upgrading.rst b/README.upgrading.rst
new file mode 100644
index 0000000..061db44
--- /dev/null
+++ b/README.upgrading.rst
@@ -0,0 +1,56 @@
+Upgrading and Downgrading
+=========================
+
+django-sshkey is equipped with South_ migrations. This makes changes to the
+database schema in upgrades or downgrades a simple process. Migrations will
+only be present on minor version changes.
+
+To use South migrations, you must have the south app in your project's
+``INSTALLED_APPS``.
+
+The following table maps django-sshkey version to migration labels:
+
++---------+---------------+-------+------------------------------------------+
+| Version | App Name | Label | Notes |
++=========+===============+=======+==========================================+
+| 1.0 | sshkey | 0001 | Migrations were not present in 1.0.x |
++---------+---------------+-------+------------------------------------------+
+| 1.1 | sshkey | 0002 | |
++---------+---------------+-------+------------------------------------------+
+| 2.0+ | django_sshkey | 0001 | See Upgrading from 1.1.x to 2.x below |
++---------+---------------+-------+------------------------------------------+
+
+To upgrade, install the new version of django-sshkey and then migrate your
+project to its corresponding label from the table above using the following
+command::
+
+ python manage.py migrate APP_NAME LABEL
+
+To downgrade, perform the migration down to the label of the desired version
+before installing the older django-sshkey.
+
+Upgrading from 1.1.x to 2.x
+---------------------------
+
+django-sshkey 2.x renames the sshkey app to django_sshkey. However, the
+database table names are not changed.
+
+To upgrade, all references to the sshkey module must be changed to
+django_sshkey. This includes all instances of ``import sshkey`` or
+``from sshkey import ...`` and all references to sshkey in URL patterns,
+views, or templates, as well as updating ``INSTALLED_APPS`` in ``settings.py``.
+
+Once you have made those changes you will need to fake the initial migration
+for django_sshkey::
+
+ python manage.py migrate --fake django_sshkey 0001_initial
+
+This completes the upgrade process. The only thing that remains is the two
+existing migration records in the ``south_migrationhistory`` table from the
+now nonexistent sshkey app. These records do not cause any problems, but they
+can be removed at your discrection using the following SQL statement on your
+database::
+
+ DELETE FROM south_migrationhistory WHERE app_name="sshkey";
+
+.. _South: http://south.aeracode.org/
--
libgit2 0.26.0