source: etherws/trunk/README.rst @ 152

Introduction
============
etherws is an implementation of Ethernet over WebSocket tunnel
based on Linux Universal TUN/TAP device driver.

How to Use
==========
For example, if you want to make virtual ethernet link for *VM1* and *VM2*
whose hypervisor's broadcast domains were split by router *R*::

  +------------------+            +------------------+
  | Hypervisor1      |            |      Hypervisor2 |
  |  +-----+         |            |         +-----+  |
  |  | VM1 |         |            |         | VM2 |  |
  |  +--+--+         |            |         +--+--+  |
  |     | (vnet0)    |            |    (vnet0) |     |
  |  +--+--+         |            |         +--+--+  |
  |  | br0 |         |            |         | br0 |  |
  |  +--+--+         |            |         +--+--+  |
  |     |            |            |            |     |
  | (ethws0)  (eth0) |            | (eth0)  (ethws0) |
  +----||--------+---+            +----+-------||----+
       ||        |        +---+        |       ||
       ||   -----+--------| R |--------+-----  ||
       ||                 +---+                ||
       ||                                      ||
       ``======================================''
            (Ethernet over WebSocket tunnel)

then you can use following commands.

on *Hypervisor1*::

  # etherws server
  # brctl addbr br0
  # brctl addif br0 vnet0
  # brctl addif br0 ethws0
  # ifconfig br0 up

on *Hypervisor2*::

  # etherws client --uri ws://<Hypervisor1's IP address>/
  # brctl addbr br0
  # brctl addif br0 vnet0
  # brctl addif br0 ethws0
  # ifconfig br0 up

If connection through the tunnel is unstable, then you may fix it
by changing VM's MTU to under 1500, e.g.::

  # ifconfig eth0 mtu 1400

Tunnel Encryption
=================
etherws supports SSL/TLS connection (but client does not verify server
certificates).
If you want to encrypt the tunnel, then you can use following options.

on *Hypervisor1* (options *keyfile* and *certfile* were specified)::

  # etherws server --keyfile ssl.key --certfile ssl.crt

on *Hypervisor2* (option *uri*'s scheme was changed to *wss*)::

  # etherws client --uri wss://<Hypervisor1's IP address>/

You also can test by following command::

  # openssl s_client -connect <Hypervisor1's IP address>:443

Client Authentication
=====================
etherws supports HTTP Basic Authentication.
It means you can use etherws as simple L2-VPN server/client.

On server side, etherws requires user information in Apache htpasswd
format (and currently supports SHA-1 digest only). To create this file::

  # htpasswd -s -c filename username

If you do not have htpasswd command, then you can use python one-liner::

  # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))'

To run server with this::

  # etherws server --htpasswd filename

You also can test by following command::

  # telnet <address> 80
  GET / HTTP/1.1

It will return *401 Authorization Required*.

On client side, etherws requires username as option, and password from
stdin::

  # etherws client --uri ws://<address>/ --user username
  Password: 

If authentication did not succeed, then it will die with some error messages.

Note that you should not use HTTP Basic Authentication without SSL/TLS
support, because it is insecure in itself.

History
=======
0.3 (2012-05-17 JST)
  - client authentication support

0.2 (2012-05-16 JST)
  - SSL/TLS connection support

0.1 (2012-05-15 JST)
  - First release