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 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 from option, and password from option or stdin:

# etherws client --uri ws://<address>/ --user username --passwd password
# 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.5 (2012-05-20 JST)

• added passwd option to client mode
• fixed bug: basic authentication password cannot contain colon
• fixed bug: client loops meaninglessly even if server stops

0.4 (2012-05-19 JST)

• server certificate verification support

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