Commit 14a34d78 authored by Andrew Perry's avatar Andrew Perry
Browse files

Docs fixes. git+https for pip command. Formatting and english.

No long lines.
parent f7b36a60
......@@ -3,13 +3,17 @@ Purpose
sshshare (pronounced like you're telling someone to be quite) is a tool to make
files stored on an SSH server (like most High Performance Computing frontends)
accessible and sharable. Using sshshare you can create a link for a coleague to be able to upload or download files without:
accessible and sharable. Using sshshare you can create a link for a coleague to
be able to upload or download files without:
- Your colleague needing an account
- You sharing your password
- Transfering to a publicly accessible http or ftp server
sshshare was originally intended to be used as a workflow component. The idea being that a workflow (or container) you were running could access your files on a different system without needing your password embeded in it. The ability to share with another human rather than a program was a nice side effect.
sshshare was originally intended to be used as a workflow component. The idea
being that a workflow (or container) you were running could access your files
on a different system without needing your password embeded in it. The ability
to share with another human rather than a program was a nice side effect.
Installation
......@@ -31,7 +35,7 @@ Install sshshare
.. code-block:: bash
pip install -e https://gitlab.erc.monash.edu.au/hpc-team/sshshare.git#egg=sshshare
pip3 install -e git+https://gitlab.erc.monash.edu.au/hpc-team/sshshare.git#egg=sshshare
Usage
=====
......@@ -51,7 +55,10 @@ use the link command to generate access tokens
sshshare link --path=<path to file to share>
Aside from a lot of debugging info, sshshare will print out two urls at the bottom of the output, a secret url and a direct download link (which has the secret url embedded in it). You can share these with whoevever you want to share the file with.
Aside from a lot of debugging info, sshshare will print out two urls at the
bottom of the output, a secret url and a direct download link (which has the
secret url embedded in it). You can share these with whoevever you want to
share the file with.
Downloading a file
------------------
......@@ -59,12 +66,14 @@ Downloading a file
Direct link
^^^^^^^^^^^
The easiestway to download a file is to use the direct download link. Simply open the link in a web browser and you should get the file.
The easiestway to download a file is to use the direct download link. Simply open
the link in a web browser and you should get the file.
With sshshare
^^^^^^^^^^^^^
Alternatively, (since the download link is not the fastest way to download a file) you can use sshshare to download the file
Alternatively, (since the download link is not the fastest way to download a file)
you can use sshshare to download the file:
.. code-block :: bash
......@@ -79,7 +88,9 @@ As a third alternative (if you don't trust my code) you can do things manually
curl <secreturl> -o secrets.json
separate the secret key from the cert using an editor and save them in files <somename> and <somename>-cert.pub. Look up the username and hostname from the last part of the json blob
separate the secret key from the cert using an editor and save them in files
``<somename>`` and ``<somename>-cert.pub``. Look up the username and hostname from
the last part of the json blob
.. code-block :: bash
......@@ -92,13 +103,14 @@ Uploading a file
The code for uploading isn't fully tested.
You can create an uploadable secret with
You can create an uploadable secret with:
.. code-block
sshshare link --path=<path to file to share> --writable
but you will need to upload using the equilivent of the manual method for downloading. Use something like
but you will need to upload using the equilivent of the manual method for downloading.
Use something like:
.. code-block :: bash
......@@ -107,16 +119,25 @@ but you will need to upload using the equilivent of the manual method for downlo
How does it work?
=================
sshshare works by creating ssh keys and a matching object called and
ssh-certificate (see man ssh-keygen under the certificates section). sshshare
then manipulates your ~/.ssh/authorized_keys file to accept those certificates
sshshare works by creating ssh keys and a matching object called an
ssh-certificate (see ``man ssh-keygen`` under the certificates section). sshshare
then manipulates your ``~/.ssh/authorized_keys`` file to accept those certificates
(i.e. it adds a certificate authority section).
Each certificate is encoded with an expiry
time and a force-command so that the person with the certificate can only do
one thing. We simply limit the force-command to be catting a file.
Each certificate is encoded with an expiry time and a force-command so that the person
with the certificate can only do one thing. We simply limit the force-command to be
catting a file.
Next we provide a URL to retrieve the keys certificates. This is called the secret url, and you can share the URL with whomever you want to download your file. If you wanted to you could share the certificates and keys directly with your collaborator, but we though the URL would be helpful. You can setup your own secret server if you want (https://gitlab.erc.monash.edu.au/hpc-team/sshshare_ws.git) You can change which secret server us used in the config file (~/.config/sshshare/config.yml)
Next we provide a URL to retrieve the keys certificates. This is called the secret url,
and you can share the URL with whomever you want to download your file. If you wanted to
you could share the certificates and keys directly with your collaborator, but we thought
the URL would be helpful. You can setup your own secret server if you want
(https://gitlab.erc.monash.edu.au/hpc-team/sshshare_ws.git). You can change which secret
server is used in the config file (``~/.config/sshshare/config.yml``)
Finally we provide a direct download link. You don't have to use our direct download server, you can create your own if you like. It simply download the file using the secret url and ssh, then sends you the file via HTTP. Once the file is sent it deletes the copy on the direct download server. The source code for the direct download proxy is included with the source code for the secret server above.
Finally we provide a direct download link. You don't have to use our direct download
server, you can create your own if you like. It simply download the file using the
secret url and ssh, then sends you the file via HTTP. Once the file is sent it deletes
the copy on the direct download server. The source code for the direct download proxy
is included with the source code for the secret server above.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment