Commit f7b36a60 authored by Chris Hines's avatar Chris Hines
Browse files

initial docs

parent aae207fb
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = sshshare
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
set SPHINXPROJ=sshshare
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# sshshare documentation build configuration file, created by
# sphinx-quickstart on Mon Feb 12 09:09:01 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'sshshare'
copyright = '2018, Chris Hines'
author = 'Chris Hines'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.0.1'
# The full version, including alpha/beta/rc tags.
release = '0.0.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# 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
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'sshsharedoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'sshshare.tex', 'sshshare Documentation',
'Chris Hines', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'sshshare', 'sshshare Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'sshshare', 'sshshare Documentation',
author, 'sshshare', 'One line description of project.',
'Miscellaneous'),
]
.. sshshare documentation master file, created by
sphinx-quickstart on Mon Feb 12 09:09:01 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to sshshare's documentation!
====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
main
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
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:
- 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.
Installation
============
Create a python3 based virtual environement
.. code-block :: bash
python3 -m venv ~/sshshare_venv
Activate the virtual environement
.. code-block :: bash
. ~/sshshare_venv/bin/activate
Install sshshare
.. code-block:: bash
pip install -e https://gitlab.erc.monash.edu.au/hpc-team/sshshare.git#egg=sshshare
Usage
=====
Activate the virtual environment created during installation
.. code-block :: bash
. ~/sshshare_venv/bin/activate
Allowing others to download a file
----------------------------------
use the link command to generate access tokens
.. code-block :: bash
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.
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.
With sshshare
^^^^^^^^^^^^^
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
sshshare get --url=<secret url link>
Manually
^^^^^^^^
As a third alternative (if you don't trust my code) you can do things manually
.. code-block :: bash
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
.. code-block :: bash
eval `ssh-agent`
ssh-add <somename>
ssh <username>@<hostname> > filename
Uploading a file
----------------
The code for uploading isn't fully tested.
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
.. code-block :: bash
cat <localfile> > ssh <username>@<hostname>
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
(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.
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)
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