Metadata-Version: 1.0
Name: etherws
Version: 0.3
Summary: Ethernet over WebSocket tunneling server/client
Home-page: UNKNOWN
Author: Atzm WATANABE
Author-email: atzm@atzm.org
License: BSD-2
Description: 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
        
Keywords: http,websocket,ethernet,network
Platform: Linux
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: System :: Networking
