Rename README to README.md
Since the CI will check markdown format files, the README files will
be updated to `.md` suffix.
In addition, markdownlint also automatically formats the header and
content of the README.md file.
Signed-off-by: George Liu <liuxiwei@ieisystem.com>
Change-Id: I604d6bbdb907cc9fdf94a411a587e6053fbf5e05
diff --git a/README b/README.md
similarity index 64%
rename from README
rename to README.md
index d7e1ec7..d6b7e08 100644
--- a/README
+++ b/README.md
@@ -1,23 +1,20 @@
-nbd-proxy
-=========
+# 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-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.
+nbd.js: a javascript implementation of a NBD server.
-Running
--------
+## Running
-You'll need a websocket proxy This connects the nbd-proxy
-component to a websocket endpoint.
+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:
@@ -32,30 +29,28 @@
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):
+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.
+ web/index.html for an example.
-Security
---------
+## 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.
+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 hook
-----------
+## State hook
The nbd-proxy has a facility to run an program on state change. When a nbd
session is established or shut down, the proxy will run the executable at