Changeset 152 for etherws

Timestamp:

05/16/12 23:59:10 (13 years ago)

Author:

atzm

Message:

• modify document

File:

• etherws/trunk/README.rst (modified) (4 diffs)

etherws/trunk/README.rst

@@ -4 +4 @@
 based on Linux Universal TUN/TAP device driver.
 
-Usage
-=====
-For example, if you want to make virtual ethernet link for VM1 and VM2
-whose hypervisor's broadcast domains were split by router R::
+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*::
 
   +------------------+            +------------------+
@@ -28 +28 @@
             (Ethernet over WebSocket tunnel)
 
-then you can type following commands.
+then you can use following commands.
 
-on Hypervisor1::
+on *Hypervisor1*::
 
   # etherws server
@@ -38 +38 @@
   # ifconfig br0 up
 
-on Hypervisor2::
+on *Hypervisor2*::
 
   # etherws client --uri ws://<Hypervisor1's IP address>/
@@ -46 +46 @@
   # ifconfig br0 up
 
-If connection through this tunnel is unstable, then you may fix it
-by changing VM's MTU to under 1500.
+If connection through the tunnel is unstable, then you may fix it
+by changing VM's MTU to under 1500, e.g.::
 
-Also etherws supports SSL/TLS connection (but client does not validate
-server certificates and server does not authenticate client yet), so if
-you want to encrypt this tunnel, then you can use following options.
+  # ifconfig eth0 mtu 1400
 
-on Hypervisor1 (options *keyfile* and *certfile* were specified)::
+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*)::
+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