From dabae7a13076f661d0354fccc32ad0fe36dd2d93 Mon Sep 17 00:00:00 2001 From: Mike Kazantsev Date: Tue, 23 Apr 2013 01:44:17 +0600 Subject: [PATCH] Update docs wrt zerobinpaste tool --- README.rst | 5 +- docs/en/intro.rst | 6 +- docs/en/zerobinpaste_tool.rst | 100 ++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +- 4 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 docs/en/zerobinpaste_tool.rst diff --git a/README.rst b/README.rst index 4ed7b20..e1bbb3a 100644 --- a/README.rst +++ b/README.rst @@ -57,7 +57,8 @@ Other features - copy paste to clipboard in a click; - get paste short URL in a click; - own previous pastes history; -- visual hash of a paste to easily tell it apart from others in a list. +- visual hash of a paste to easily tell it apart from others in a list; +- optional command-line tool to encrypt and paste data from shell or scripts. Technologies used ================== @@ -69,6 +70,7 @@ Technologies used - Bootstrap_, the Twitter HTML5/CSS3 framework - VizHash.js_ to create visual hashes from pastes - Cherrypy_ (server only) +- `node.js`_ (for optional command-line tool only) Known issues @@ -96,5 +98,6 @@ What does 0bin not implement? .. _Bootstrap: http://twitter.github.com/bootstrap/ .. _VizHash.js: https://github.com/sametmax/VizHash.js .. _Cherrypy: http://www.cherrypy.org/ (server only) +.. _node.js: http://nodejs.org/ .. _is not worth it: http://stackoverflow.com/questions/201705/how-many-random-elements-before-md5-produces-collisions .. _WTF licence: http://en.wikipedia.org/wiki/WTFPL diff --git a/docs/en/intro.rst b/docs/en/intro.rst index 7b45cae..9653a63 100644 --- a/docs/en/intro.rst +++ b/docs/en/intro.rst @@ -45,7 +45,8 @@ Other features - copy paste to clipboard in a click; - get paste short URL in a click; - own previous pastes history; -- visual hash of a paste to easily tell it apart from others in a list. +- visual hash of a paste to easily tell it apart from others in a list; +- `optional command-line tool`_ to encrypt and paste data from shell or scripts. Technologies used ================== @@ -57,6 +58,7 @@ Technologies used - Bootstrap_, the Twitter HTML5/CSS3 framework - VizHash.js_ to create visual hashes from pastes - Cherrypy_ (server only) +- `node.js`_ (for optional command-line tool only) Known issues @@ -84,4 +86,6 @@ What does 0bin not implement? .. _Bootstrap: http://twitter.github.com/bootstrap/ .. _VizHash.js: https://github.com/sametmax/VizHash.js .. _Cherrypy: http://www.cherrypy.org/ (server only) +.. _node.js: http://nodejs.org/ +.. _optional command-line tool: ./zerobinpaste_tool .. _is not worth it: http://stackoverflow.com/questions/201705/how-many-random-elements-before-md5-produces-collisions diff --git a/docs/en/zerobinpaste_tool.rst b/docs/en/zerobinpaste_tool.rst new file mode 100644 index 0000000..ba3d410 --- /dev/null +++ b/docs/en/zerobinpaste_tool.rst @@ -0,0 +1,100 @@ +============================== +zerobinpaste command-line tool +============================== + +zerobinpaste is a simple CLI tool (analogous to pastebinit or wgetpaste) to use +with files or shell redirection in terminal or simple scripts. + +Example use-cases might look like:: + + % zerobinpaste README.rst + http://some.0bin.site/paste/0cc3d8a8... + + % grep error /var/log/syslog | zerobinpaste + http://some.0bin.site/paste/81fd1324... + + % zerobinpaste docs/en/*.rst + easy_install.rst http://some.0bin.site/paste/9adc576a... + apache_install.rst http://some.0bin.site/paste/01408cbd... + options.rst http://some.0bin.site/paste/921b2768... + ... + + + % ps axlf | zerobinpaste | mail -s "Process tree on $(date)" root + +Produced links can then be copy-pasted to some IRC channel or used in whatever +other conceivable way. + +Tool does encryption by itself on the client machine and key (after hashmark) is +never sent to server or anywhere but the tool's stdout stream (e.g. terminal). + +Tool has to be built with `node.js`_ separately (see below). + + +Usage +===== + +At least the pastebin site (main URL where you'd paste stuff with the browser) +has to be specified for the tool to use either via -u (--url) option (can be +simplified with shell alias - e.g. ``alias zp='zerobinpaste -u http://some.0bin.site``) +or in the "~/.zerobinpasterc" configuration file (json format). + +| Non-option arguments are interpreted as files to upload/paste contents of. +| If no arguments are specified, data to paste will be read from stdin stream. + +Simple configuration file may look like this: + + {"url": "http://some.0bin.site"} + +Any options (in the long form, e.g. "url" for --url above) that are allowed on +the command-line can be specified there. + +Run the tool with -h or --help option to see full list of supported parameters. + + +Build / Installation +==================== + +In essence: + + 0bin% cd tools + 0bin/tools% make + ... + 0bin/tools% cp zerobinpaste ~/bin # install to PATH + +"npm" binary (packaged and installed with node.js) is required to pull in build +dependencies, if necessary, and "node" binary is required for produced binary to +run. + +Use "make" in "tools" path to produce non-minified runnable "zerobinpaste" +script there. + +``make ugly`` command can be used instead of ``make`` to create "minified" +version (using/installing uglifyjs_, about 25% smaller in size). + +Resulting "zerobinpaste" script requires only node.js ("node" binary) installed +to run and can be placed in any of the PATH dirs (e.g. "~/bin", +"/usr/local/bin") to be run just as "zerobinpaste". + + +Why node.js and not python +========================== + +Unfortunately, it's fairly complex and unreliable to replicate non-trivial and +undocumented encryption protocol that SJCL_ convenience methods employ, and any +mistake in encryption is guaranteed to produce unreadable paste. + +Current implementation uses same JavaScript code (and V8 node.js engine) that +browsers do, hence can be fairly simple and robust. + +Future development plans include supporting configurable, less complex and more +widespread encryption schemas, allowing for simplier non-javascript client as +well. + +See `related pull request`_ for more details. + + +.. _node.js: http://nodejs.org/ +.. _uglifyjs: https://github.com/mishoo/UglifyJS +.. _SJCL: http://crypto.stanford.edu/sjcl/ +.. _related pull request: https://github.com/sametmax/0bin/pull/39 diff --git a/docs/index.rst b/docs/index.rst index 9c65518..50c8992 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,10 +22,11 @@ | en/using_supervisor | fr/using_supervisor | | en/theming | fr/theming | | en/options | fr/options | +| en/zerobinpaste_tool | | | | | |`Report a bug`_ |`Signaler un bug`_ | +-------------------------+--------------------------------+ .. _Signaler un bug: https://github.com/sametmax/0bin/issues -.. _Report a bug: https://github.com/sametmax/0bin/issues \ No newline at end of file +.. _Report a bug: https://github.com/sametmax/0bin/issues