README

nbd-proxy
=========

Prototype javascript+websocket NBD server; this code demonstrates a javascript
NBD implementation connected to the kernel nbd device over a websocket.

There are two components here:

  nbd-proxy: a little binary to initialise a nbd client, connected to a
             unix domain socket, then proxy data between that socket and
             stdio. This can be used with a websocket proxy to expose
             that stdio as a websocket.

  nbd.js:    a javascript implementation of a NBD server.

Running
-------

You'll need a websocket proxy This connects the nbd-proxy
component to a websocket endpoint.

For experimentation, I use the `websocketd` infrastrcture to expose the
websocket endpoint, plus serve the static HTML+js client:

    git clone https://github.com/joewalnes/websocketd
    (cd websocketd && make)

    sudo websocketd/websocketd --port=8000 --staticdir=web --binary ./nbd-proxy <config>

- where <config> is a name of a configuration in the config.json file.

Note that this type of invocation is very insecure, and intended just for
experimentation. See the Security section below.

For real deployments, you want your websocket-enabled service to run
nbd-proxy, and connect its stdio to a websocket, running in binary mode. Your
web interface will interact with this using an instance of the NBDServer object
(defined in web/js/nbd.js):

    var server = NBDServer(endpoint, file);
    server.start();

- where endpoint is the websocket URL (ws://...) and file is a File object. See
web/index.html for an example.

Security
--------

This code allows potentially-untrusted clients to export arbitrary block
device data to your kernel. Therefore, you should ensure that only trusted
clients can connect as NBD servers.

There is no authentication or authorisation implemented in the nbd proxy. Your
websocket proxy should implement proper authentication before nbd-proxy is
connected to the websocket endpoint.

State hooks
-----------

The nbd-proxy has a facility to run hooks on state change. When a
nbd session is established or shut down, the proxy will run any executables
found under the hook path (by default, /etc/nbd-proxy/state.d/).

These hooks are called with two arguments: the action ("start" or "stop"),
and the name of the configuration (as specified in the config.json file).