Changeset 260

Timestamp:

10/10/13 02:06:15 (11 years ago)

Author:

atzm

Message:

update documentation

File:

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

etherws/trunk/README.rst

@@ -1 +1 @@
 Introduction
 ============
-etherws is an implementation of Ethernet over WebSocket tunnel based on Linux
-Universal TUN/TAP device driver.
+etherws is an implementation of software switch with the Ethernet over
+WebSocket tunnel.
 
 Overview
 ========
-*etherws sw* acts as a simple virtual ethernet switch, and it can create TAP
-interface or WebSocket tunnel by *etherws ctl*::
-
-      [tap]
-        |
-  +-----+------+   (control)
+*etherws sw* is a simple virtual ethernet switch.  And this is controlled by
+*etherws ctl*::
+
+   [tap] [netdev]
+     |      |
+  +--+------+--+   (control)
   | etherws sw | <-----------+
   +-----||-----+             |
@@ -19 +19 @@
   +-----||-----+             |
   | etherws sw | <-----------+
-  +-----+------+   (control)
-        |
-      [tap]
+  +--+------+--+   (control)
+     |      |
+   [tap] [netdev]
 
 Basic Usage
@@ -28 +28 @@
 
           (Physical Network)
-  -----+-------   //  -------+-----
+  -----+--------- // --------+-----
        | 10.0.0.10           | 10.0.0.5
   +----+-----+         +-----+----+ 
@@ -39 +39 @@
           (WebSocket Tunnel)
 
-In this case, *WebSocket Tunnel* will be created by following commands.
+In this case, WebSocket Tunnel will be created by following commands.
 
 on NodeA::
@@ -63 +63 @@
 Using SSL/TLS
 -------------
-etherws supports SSL/TLS connection. Tunnels will be encrypted and server will
+etherws supports SSL/TLS connection.  Tunnels will be encrypted and server will
 be verified by using following options.
 
@@ -70 +70 @@
   # etherws sw --sslkey ssl.key --sslcert ssl.crt
 
-*ssl.key* is a server private key, and *ssl.crt* is a server certificate.
+*ssl.key* is a server private key, and *ssl.crt* is a server
+certificate.
 
 On client side::
@@ -79 +80 @@
 certificate was specified.
 
-Client verifies server certificate by default. So, for example, *addport* will
+Client verifies server certificate by default.  So, for example, *addport* will
 fail if your server uses self-signed certificate and client uses another CA
 certificate.
@@ -93 +94 @@
 Client Authentication
 ---------------------
-etherws supports HTTP Basic Authentication. It means you can use etherws as
+etherws supports HTTP Basic Authentication.  This means you can use etherws as
 simple L2-VPN server/client.
 
 On server side, etherws requires user informations in Apache htpasswd format
-(and currently supports SHA-1 digest only). To create this file::
+(and currently supports SHA-1 digest only).  To create this file::
 
   # htpasswd -s -c filename username
@@ -123 +124 @@
 
 Note that you should not use HTTP Basic Authentication without SSL/TLS support,
-because it is insecure in itself.
+because this is insecure in itself.
 
 Advanced Usage
@@ -130 +131 @@
 Remote Control
 --------------
-*etherws ctl* controls *etherws sw* by JSON-RPC over HTTP. It means you can
-control *etherws sw* from remote node. However, allowing remote control without
-careful consideration also allows to attack to your server or network. So
-control URL is bound to localhost by default.
+*etherws ctl* controls *etherws sw* by JSON-RPC over HTTP.  This means you can
+control *etherws sw* from remote nodes.  However, allowing remote control
+without careful consideration also allows to attack to your server or
+network.  So control URL is bound to localhost by default.
 
 If you just want to allow remote control, you can use following options for
@@ -141 +142 @@
 
 This means allowing remote control from any nodes that can access
-10.0.0.10:1234 TCP/IP. Of course it is very dangerous as described above.
+10.0.0.10:1234 TCP/IP.  Of course this is very dangerous as described above.
 
 Here, *etherws ctl* can control remote *etherws sw* using following option::
@@ -164 +165 @@
 Note: *etherws ctl* currently cannot verify SSL certificate on controller.
 
-Connect Virtual Machines
-------------------------
+Virtual Machines Connection
+---------------------------
 For example, consider creating following virtual machine network::
 
@@ -173 +174 @@
   |  | VM  |         |             |         | VM  |  |
   |  +--+--+         |             |         +--+--+  |
-  |     | (vnet0)    |             |    (vnet0) |     |
-  |  +--+--+         |             |         +--+--+  |
-  |  | br0 |         |             |         | br0 |  |
-  |  +--+--+         |             |         +--+--+  |
+  |  (vnet0)         |             |         (vnet0)  |
   |     |            |             |            |     |
-  | (ethws0)  (eth0) |             | (eth0)  (ethws0) |
+  | [etherws] (eth0) |             | (eth0) [etherws] |
   +----||--------+---+             +----+-------||----+
        ||        |                      |       ||
-       ||   -----+--------  //  --------+-----  ||
+       ||   -----+--------- // ---------+-----  ||
        ||           (Physical Network)          ||
        ||                                       ||
@@ -187 +185 @@
                    (WebSocket Tunnel)
 
-In this case, it will be created by following commands.
+Existing network interfaces can also be added to *etherws sw*.
+So in this case, this will be created by following commands.
 
 on HypervisorA::
 
   # etherws sw
-  # etherws ctl addport tap ethws0
-  # brctl addbr br0
-  # brctl addif br0 vnet0
-  # brctl addif br0 ethws0
-  # ifconfig br0 up
+  # etherws ctl addport netdev vnet0
 
 on HypervisorB::
 
   # etherws sw
-  # etherws ctl addport tap ethws0
+  # etherws ctl addport netdev vnet0
   # etherws ctl addport client ws://HypervisorA/
-  # brctl addbr br0
-  # brctl addif br0 vnet0
-  # brctl addif br0 ethws0
-  # ifconfig br0 up
+
+Of course, you can create the TAP port and connect these using the Linux Bridge
+or the like.
 
 History
 =======
+1.1 (2013-10-10 JST)
+  - netdev (existing network interfaces) support
+
 1.0 (2012-08-18 JST)
   - global architecture change