change theme to classic for docs

docs/source/conf.py

@@ -83,7 +83,7 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'classic'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/main.rst

@@ -45,13 +45,13 @@ Activate the virtual environment created during installation
 Allowing others to download a file
 ----------------------------------
 
-use the link command to generate access tokens
+use the share command to generate access tokens
 
 .. code-block :: bash
 
-  sshshare link --path=<path to file to share>
+  sshshare share <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 credential url and a direct download link (which has the credentials url embedded in it). You can share these with whoevever you want to share the file with.
 
 Downloading a file
 ------------------
@@ -59,7 +59,7 @@ 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 easiest way to download a file is to use the direct download link. Simply open the direct download link in a web browser and you should get the file.
 
 With sshshare
 ^^^^^^^^^^^^^
@@ -68,7 +68,7 @@ Alternatively, (since the download link is not the fastest way to download a fil
 
 .. code-block :: bash
 
-   sshshare get --url=<secret url link>
+   sshshare get <secret url link>
 
 Manually
 ^^^^^^^^
@@ -96,7 +96,7 @@ You can create an uploadable secret with
 
 .. code-block
 
-  sshshare link --path=<path to file to share> --writable
+  sshshare share <path to file to share> --writable
 
 but you will need to upload using the equilivent of the manual method for downloading. Use something like
 
@@ -116,7 +116,43 @@ 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 credentials 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 credentials server if you want (https://gitlab.erc.monash.edu.au/hpc-team/sshshare_ws.git) You can change which credentials server us 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 credentials 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 credentials server above.
+
+You can also get the indiviual credential components directly from the credential server.
+If you have a credential URL of the form 
+.. code-block 
+
+  https://cw-vm-d034.sa.nectar.org.au/sshshare/share/XXXXX
+
+you can retrieve the key with a command like
+
+.. code-block :: bash
+
+  curl https://cw-vm-d034.sa.nectar.org.au/sshshare/sharecomp/key/XXXXX | python3 -c "import sys, json; print(json.load(sys.stdin))" > key
+
+and the certificate with
+
+.. code-block :: bash
+
+  curl https://cw-vm-d034.sa.nectar.org.au/sshshare/sharecomp/cert/XXXXX | python3 -c "import sys, json; print(json.load(sys.stdin))" > key-cert.pub
+
+you can examine the contents of the certificate with
+
+.. code-block :: bash
+
+  ssh-keygen -L -f key-cert.pub
+
+Help it doesn't work!
+=====================
+
+The most likely reason someone can't download your file is because your ssh server is not contactable
+sshshare does some tricky things trying to get the IP address of the computer where you ran sshshare. You can verify the IP address it found with
+
+.. code-block :: bash
+
+  curl https://cw-vm-d034.sa.nectar.org.au/sshshare/sharecomp/uri/XXXXX
+
+Where XXXX is replaced by the secret in the credential url. The person downloading the file should be able to SSH to the IP address returned by this command. If they can't there may be an issue with firewalls or networking and you could consider sharing the file from another computer.