source: etherws/trunk/README.rst @ 156

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

Using SSL/TLS
=============
etherws supports SSL/TLS connection.
If you want to encrypt the tunnel, then you can use following options.

on *Hypervisor1*::

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

*ssl.key* is a server private key, and *ssl.crt* is a server certificate.

Now you also can test SSL/TLS connection by following command::

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

on *Hypervisor2*::

  # etherws client --uri wss://<Hypervisor1's IP address>/ --cacerts ssl.crt

Here, URI scheme was just changed to *wss*, and CA certificate to verify
server certificate was specified.

By the way, client verifies server certificate by default.
So, for example, client will die with error messages if your server uses
self-signed certificate and client uses another CA certificate.

If you want to just encrypt the tunnel and do not need to verify
certificate, then you can use following option::

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

Note: see `<http://docs.python.org/library/ssl.html#certificates>`_
for more information about certificates.

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