Ignore:
Timestamp:
10/10/13 02:06:15 (11 years ago)
Author:
atzm
Message:

update documentation

File:
1 edited

Legend:

Unmodified
Added
Removed
  • etherws/trunk/README.rst

    r220 r260  
    11Introduction 
    22============ 
    3 etherws is an implementation of Ethernet over WebSocket tunnel based on Linux 
    4 Universal TUN/TAP device driver. 
     3etherws is an implementation of software switch with the Ethernet over 
     4WebSocket tunnel. 
    55 
    66Overview 
    77======== 
    8 *etherws sw* acts as a simple virtual ethernet switch, and it can create TAP 
    9 interface or WebSocket tunnel by *etherws ctl*:: 
    10  
    11       [tap] 
    12         | 
    13   +-----+------+   (control) 
     8*etherws sw* is a simple virtual ethernet switch.  And this is controlled by 
     9*etherws ctl*:: 
     10 
     11   [tap] [netdev] 
     12     |      | 
     13  +--+------+--+   (control) 
    1414  | etherws sw | <-----------+ 
    1515  +-----||-----+             | 
     
    1919  +-----||-----+             | 
    2020  | etherws sw | <-----------+ 
    21   +-----+------+   (control) 
    22         | 
    23       [tap] 
     21  +--+------+--+   (control) 
     22     |      | 
     23   [tap] [netdev] 
    2424 
    2525Basic Usage 
     
    2828 
    2929          (Physical Network) 
    30   -----+-------   //  -------+----- 
     30  -----+--------- // --------+----- 
    3131       | 10.0.0.10           | 10.0.0.5 
    3232  +----+-----+         +-----+----+  
     
    3939          (WebSocket Tunnel) 
    4040 
    41 In this case, *WebSocket Tunnel* will be created by following commands. 
     41In this case, WebSocket Tunnel will be created by following commands. 
    4242 
    4343on NodeA:: 
     
    6363Using SSL/TLS 
    6464------------- 
    65 etherws supports SSL/TLS connection. Tunnels will be encrypted and server will 
     65etherws supports SSL/TLS connection.  Tunnels will be encrypted and server will 
    6666be verified by using following options. 
    6767 
     
    7070  # etherws sw --sslkey ssl.key --sslcert ssl.crt 
    7171 
    72 *ssl.key* is a server private key, and *ssl.crt* is a server certificate. 
     72*ssl.key* is a server private key, and *ssl.crt* is a server 
     73certificate. 
    7374 
    7475On client side:: 
     
    7980certificate was specified. 
    8081 
    81 Client verifies server certificate by default. So, for example, *addport* will 
     82Client verifies server certificate by default.  So, for example, *addport* will 
    8283fail if your server uses self-signed certificate and client uses another CA 
    8384certificate. 
     
    9394Client Authentication 
    9495--------------------- 
    95 etherws supports HTTP Basic Authentication. It means you can use etherws as 
     96etherws supports HTTP Basic Authentication.  This means you can use etherws as 
    9697simple L2-VPN server/client. 
    9798 
    9899On server side, etherws requires user informations in Apache htpasswd format 
    99 (and currently supports SHA-1 digest only). To create this file:: 
     100(and currently supports SHA-1 digest only).  To create this file:: 
    100101 
    101102  # htpasswd -s -c filename username 
     
    123124 
    124125Note that you should not use HTTP Basic Authentication without SSL/TLS support, 
    125 because it is insecure in itself. 
     126because this is insecure in itself. 
    126127 
    127128Advanced Usage 
     
    130131Remote Control 
    131132-------------- 
    132 *etherws ctl* controls *etherws sw* by JSON-RPC over HTTP. It means you can 
    133 control *etherws sw* from remote node. However, allowing remote control without 
    134 careful consideration also allows to attack to your server or network. So 
    135 control URL is bound to localhost by default. 
     133*etherws ctl* controls *etherws sw* by JSON-RPC over HTTP.  This means you can 
     134control *etherws sw* from remote nodes.  However, allowing remote control 
     135without careful consideration also allows to attack to your server or 
     136network.  So control URL is bound to localhost by default. 
    136137 
    137138If you just want to allow remote control, you can use following options for 
     
    141142 
    142143This means allowing remote control from any nodes that can access 
    143 10.0.0.10:1234 TCP/IP. Of course it is very dangerous as described above. 
     14410.0.0.10:1234 TCP/IP.  Of course this is very dangerous as described above. 
    144145 
    145146Here, *etherws ctl* can control remote *etherws sw* using following option:: 
     
    164165Note: *etherws ctl* currently cannot verify SSL certificate on controller. 
    165166 
    166 Connect Virtual Machines 
    167 ------------------------ 
     167Virtual Machines Connection 
     168--------------------------- 
    168169For example, consider creating following virtual machine network:: 
    169170 
     
    173174  |  | VM  |         |             |         | VM  |  | 
    174175  |  +--+--+         |             |         +--+--+  | 
    175   |     | (vnet0)    |             |    (vnet0) |     | 
    176   |  +--+--+         |             |         +--+--+  | 
    177   |  | br0 |         |             |         | br0 |  | 
    178   |  +--+--+         |             |         +--+--+  | 
     176  |  (vnet0)         |             |         (vnet0)  | 
    179177  |     |            |             |            |     | 
    180   | (ethws0)  (eth0) |             | (eth0)  (ethws0) | 
     178  | [etherws] (eth0) |             | (eth0) [etherws] | 
    181179  +----||--------+---+             +----+-------||----+ 
    182180       ||        |                      |       || 
    183        ||   -----+--------  //  --------+-----  || 
     181       ||   -----+--------- // ---------+-----  || 
    184182       ||           (Physical Network)          || 
    185183       ||                                       || 
     
    187185                   (WebSocket Tunnel) 
    188186 
    189 In this case, it will be created by following commands. 
     187Existing network interfaces can also be added to *etherws sw*. 
     188So in this case, this will be created by following commands. 
    190189 
    191190on HypervisorA:: 
    192191 
    193192  # etherws sw 
    194   # etherws ctl addport tap ethws0 
    195   # brctl addbr br0 
    196   # brctl addif br0 vnet0 
    197   # brctl addif br0 ethws0 
    198   # ifconfig br0 up 
     193  # etherws ctl addport netdev vnet0 
    199194 
    200195on HypervisorB:: 
    201196 
    202197  # etherws sw 
    203   # etherws ctl addport tap ethws0 
     198  # etherws ctl addport netdev vnet0 
    204199  # etherws ctl addport client ws://HypervisorA/ 
    205   # brctl addbr br0 
    206   # brctl addif br0 vnet0 
    207   # brctl addif br0 ethws0 
    208   # ifconfig br0 up 
     200 
     201Of course, you can create the TAP port and connect these using the Linux Bridge 
     202or the like. 
    209203 
    210204History 
    211205======= 
     2061.1 (2013-10-10 JST) 
     207  - netdev (existing network interfaces) support 
     208 
    2122091.0 (2012-08-18 JST) 
    213210  - global architecture change 
Note: See TracChangeset for help on using the changeset viewer.