Changeset 216 for etherws/trunk


Ignore:
Timestamp:
08/17/12 01:33:46 (12 years ago)
Author:
atzm
Message:
  • update document
File:
1 edited

Legend:

Unmodified
Added
Removed
  • etherws/trunk/README.rst

    r170 r216  
    11Introduction 
    22============ 
    3 etherws is an implementation of Ethernet over WebSocket tunnel 
    4 based on Linux Universal TUN/TAP device driver. 
    5  
    6 How to Use 
    7 ========== 
    8 For example, if you want to make virtual ethernet link for *VM1* and *VM2* 
    9 whose hypervisor's broadcast domains were isolated by router *R*:: 
    10  
    11   +------------------+            +------------------+ 
    12   | Hypervisor1      |            |      Hypervisor2 | 
    13   |  +-----+         |            |         +-----+  | 
    14   |  | VM1 |         |            |         | VM2 |  | 
    15   |  +--+--+         |            |         +--+--+  | 
    16   |     | (vnet0)    |            |    (vnet0) |     | 
    17   |  +--+--+         |            |         +--+--+  | 
    18   |  | br0 |         |            |         | br0 |  | 
    19   |  +--+--+         |            |         +--+--+  | 
    20   |     |            |            |            |     | 
    21   | (ethws0)  (eth0) |            | (eth0)  (ethws0) | 
    22   +----||--------+---+            +----+-------||----+ 
    23        ||        |        +---+        |       || 
    24        ||   -----+--------| R |--------+-----  || 
    25        ||                 +---+                || 
    26        ||                                      || 
    27        ``======================================'' 
    28             (Ethernet over WebSocket tunnel) 
    29  
    30 then you can use following commands. 
    31  
    32 on *Hypervisor1*:: 
    33  
    34   # etherws --device ethws0 server 
     3etherws is an implementation of Ethernet over WebSocket tunnel based on Linux 
     4Universal TUN/TAP device driver. 
     5 
     6Overview 
     7======== 
     8*etherws sw* acts as a simple virtual ethernet switch, and it can create TAP 
     9interface or WebSocket tunnel by *etherws ctl*:: 
     10 
     11      [tap] 
     12        | 
     13  +-----+------+   (control) 
     14  | etherws sw | <-----------+ 
     15  +-----||-----+             | 
     16        ||            +-------------+ 
     17    (WebSocket)       | etherws ctl | 
     18        ||            +-------------+ 
     19  +-----||-----+             | 
     20  | etherws sw | <-----------+ 
     21  +-----+------+   (control) 
     22        | 
     23      [tap] 
     24 
     25Basic Usage 
     26=========== 
     27For example, consider creating following simple network:: 
     28 
     29          (Physical Network) 
     30  -----+-------   //  -------+----- 
     31       | 10.0.0.10           | 10.0.0.5 
     32  +----+-----+         +-----+----+  
     33  | NodeA    |         | NodeB    | 
     34  |          |         |          | 
     35  | [ethws0] |         | [ethws0] | 
     36  +----||----+         +----||----+ 
     37       || 192.0.2.10/24     || 192.0.2.5/24 
     38       ``==================='' 
     39          (WebSocket Tunnel) 
     40 
     41In this case, *WebSocket Tunnel* will be created by following commands. 
     42 
     43on NodeA:: 
     44 
     45  # etherws sw 
     46  # etherws ctl addport tap ethws0 
     47  # etherws ctl setif --address 192.168.0.10 --netmask 255.255.255.0 1 
     48 
     49on NodeB:: 
     50 
     51  # etherws sw 
     52  # etherws ctl addport tap ethws0 
     53  # etherws ctl setif --address 192.168.0.5 --netmask 255.255.255.0 1 
     54  # etherws ctl addport client ws://10.0.0.10/ 
     55 
     56*listport*, *listif* or *listfdb* commands will show you current port list, 
     57interface list, or forwarding database entries:: 
     58 
     59  # etherws ctl listport 
     60  # etherws ctl listif 
     61  # etherws ctl listfdb 
     62 
     63Using SSL/TLS 
     64------------- 
     65etherws supports SSL/TLS connection. Tunnels will be encrypted and server will 
     66be verified by using following options. 
     67 
     68On server side:: 
     69 
     70  # etherws sw --sslkey ssl.key --sslcert ssl.crt 
     71 
     72*ssl.key* is a server private key, and *ssl.crt* is a server certificate. 
     73 
     74On client side:: 
     75 
     76  # etherws ctl addport client --cacerts ssl.crt wss://10.0.0.10/ 
     77 
     78URL scheme was just changed to *wss*, and CA certificate to verify server 
     79certificate was specified. 
     80 
     81Client verifies server certificate by default. So, for example, *addport* will 
     82fail if your server uses self-signed certificate and client uses another CA 
     83certificate. 
     84 
     85If you want to just encrypt tunnels and do not need to verify server 
     86certificate, then you can use *--insecure* option:: 
     87 
     88  # etherws ctl addport client --insecure wss://10.0.0.10/ 
     89 
     90Note: see http://docs.python.org/library/ssl.html for more information about 
     91certificates. 
     92 
     93Client Authentication 
     94--------------------- 
     95etherws supports HTTP Basic Authentication. It means you can use etherws as 
     96simple L2-VPN server/client. 
     97 
     98On server side, etherws requires user informations in Apache htpasswd format 
     99(and currently supports SHA-1 digest only). To create this file:: 
     100 
     101  # htpasswd -s -c filename username 
     102 
     103If you do not have htpasswd command, then you can use python one-liner 
     104instead:: 
     105 
     106  # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))' 
     107 
     108To run server with this file:: 
     109 
     110  # etherws sw --htpasswd filename 
     111 
     112On client side, etherws requires username and password from option with 
     113*addport* command:: 
     114 
     115  # etherws ctl addport client --user username --passwd password ws://10.0.0.10/ 
     116 
     117Or, password can be input from stdin:: 
     118 
     119  # etherws ctl addport client --user username ws://10.0.0.10/ 
     120  Client Password: 
     121 
     122If authentication did not succeed, then *addport* will fail. 
     123 
     124Note that you should not use HTTP Basic Authentication without SSL/TLS support, 
     125because it is insecure in itself. 
     126 
     127Advanced Usage 
     128============== 
     129 
     130Remote Control 
     131-------------- 
     132*etherws ctl* controls *etherws sw* by JSON-RPC over HTTP. It means you can 
     133control *etherws sw* from remote node. However, allowing remote control without 
     134careful consideration also allows to attack to your server or network. So 
     135control URL is bound to localhost by default. 
     136 
     137If you just want to allow remote control, you can use following options for 
     138example:: 
     139 
     140  # etherws sw --ctlhost 10.0.0.10 --ctlport 1234 
     141 
     142This means allowing remote control from any nodes that can access 
     14310.0.0.10:1234 TCP/IP. Of course it is very dangerous as described above. 
     144 
     145Here, *etherws ctl* can control remote *etherws sw* using following option:: 
     146 
     147  # etherws ctl --ctlurl http://10.0.0.10:1234/ctl ... 
     148 
     149*etherws sw* controller supports SSL/TLS connection and client authentication 
     150as well as WebSocket tunnel service. 
     151 
     152On server side:: 
     153 
     154  # etherws sw --ctlhost 10.0.0.10 --ctlport 443 \ 
     155               --ctlhtpasswd htpasswd --ctlsslkey ssl.key --ctlsslcert ssl.crt 
     156 
     157On client side:: 
     158 
     159  # etherws ctl --ctlurl https://10.0.0.10/ctl \ 
     160                --ctluser username --ctlpasswd password ... 
     161 
     162Password can be input from stdin as well as WebSocket tunnel creation. 
     163 
     164Note: *etherws ctl* currently cannot verify SSL certificate on controller. 
     165 
     166Connect Virtual Machines 
     167------------------------ 
     168For example, consider creating following virtual machine network:: 
     169 
     170  +------------------+             +------------------+ 
     171  | HypervisorA      |             |      HypervisorB | 
     172  |  +-----+         |             |         +-----+  | 
     173  |  | VM  |         |             |         | VM  |  | 
     174  |  +--+--+         |             |         +--+--+  | 
     175  |     | (vnet0)    |             |    (vnet0) |     | 
     176  |  +--+--+         |             |         +--+--+  | 
     177  |  | br0 |         |             |         | br0 |  | 
     178  |  +--+--+         |             |         +--+--+  | 
     179  |     |            |             |            |     | 
     180  | (ethws0)  (eth0) |             | (eth0)  (ethws0) | 
     181  +----||--------+---+             +----+-------||----+ 
     182       ||        |                      |       || 
     183       ||   -----+--------  //  --------+-----  || 
     184       ||           (Physical Network)          || 
     185       ||                                       || 
     186       ``======================================='' 
     187                   (WebSocket Tunnel) 
     188 
     189In this case, it will be created by following commands. 
     190 
     191on HypervisorA:: 
     192 
     193  # etherws sw 
     194  # etherws ctl addport tap ethws0 
    35195  # brctl addbr br0 
    36196  # brctl addif br0 vnet0 
     
    38198  # ifconfig br0 up 
    39199 
    40 on *Hypervisor2*:: 
    41  
    42   # etherws --device ethws0 client --uri ws://<Hypervisor1's IP address>/ 
     200on HypervisorB:: 
     201 
     202  # etherws sw 
     203  # etherws ctl addport tap ethws0 
     204  # etherws ctl addport client ws://HypervisorA/ 
    43205  # brctl addbr br0 
    44206  # brctl addif br0 vnet0 
     
    46208  # ifconfig br0 up 
    47209 
    48 Additionally, you may improve performance by increasing MTU. 
    49 For example, 
    50  
    51 on each hypervisor:: 
    52  
    53  # ifconfig vnet0 mtu 16436 
    54  # ifconfig ethws0 mtu 16436 
    55  
    56 on each VM:: 
    57  
    58  # ifconfig eth0 mtu 16436 
    59  
    60 Using SSL/TLS 
    61 ============= 
    62 etherws supports SSL/TLS connection. 
    63 If you want to encrypt tunnels, then you can use following options. 
    64  
    65 on *Hypervisor1*:: 
    66  
    67   # etherws --device ethws0 server --keyfile ssl.key --certfile ssl.crt 
    68  
    69 *ssl.key* is a server private key, and *ssl.crt* is a server certificate. 
    70  
    71 Now you also can test SSL/TLS connection by following command:: 
    72  
    73   # openssl s_client -connect <Hypervisor1's IP address>:443 
    74  
    75 on *Hypervisor2*:: 
    76  
    77   # etherws --device ethws0 client --uri wss://<Hypervisor1's IP address>/ --cacerts ssl.crt 
    78  
    79 Here, URI scheme was just changed to *wss*, and CA certificate to verify 
    80 server certificate was specified. 
    81  
    82 By the way, client verifies server certificate by default. 
    83 So, for example, client will die with error messages if your server uses 
    84 self-signed certificate and client uses another CA certificate. 
    85  
    86 If you want to just encrypt tunnels and do not need to verify 
    87 certificate, then you can use following option:: 
    88  
    89   # etherws --device ethws0 client --uri wss://<Hypervisor1's IP address>/ --insecure 
    90  
    91 Note: see `<http://docs.python.org/library/ssl.html>`_ 
    92 for more information about certificates. 
    93  
    94 Client Authentication 
    95 ===================== 
    96 etherws supports HTTP Basic Authentication. 
    97 It means you can use etherws as simple L2-VPN server/client. 
    98  
    99 On server side, etherws requires user information in Apache htpasswd 
    100 format (and currently supports SHA-1 digest only). To create this file:: 
    101  
    102   # htpasswd -s -c filename username 
    103  
    104 If you do not have htpasswd command, then you can use python one-liner:: 
    105  
    106   # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))' 
    107  
    108 To run server with this:: 
    109  
    110   # etherws --device ethws0 server --htpasswd filename 
    111  
    112 You also can test by following command:: 
    113  
    114   # telnet <address> 80 
    115   GET / HTTP/1.1 
    116  
    117 It will return *401 Authorization Required*. 
    118  
    119 On client side, etherws requires username from option, and password from 
    120 option or stdin:: 
    121  
    122   # etherws --device ethws0 client --uri ws://<address>/ --user username --passwd password 
    123   # etherws --device ethws0 client --uri ws://<address>/ --user username 
    124   Password:  
    125  
    126 If authentication did not succeed, then it will die with some error messages. 
    127  
    128 Note that you should not use HTTP Basic Authentication without SSL/TLS 
    129 support, because it is insecure in itself. 
    130  
    131 Complex Examples 
    132 ================ 
    133 etherws has simple virtual Ethernet switch in itself and it can handle multiple 
    134 TAP interfaces or WebSocket connections as virtual switch port:: 
    135  
    136   (A)# etherws --device ethws0 --device ethws1 --device ethws2 server 
    137   (B)# etherws --device ethws0 server 
    138   (C)# etherws --device ethws0 --device ethws1 client --uri ws://x.x.x.x/ 
    139   (D)# etherws --device ethws0 client --uri ws://x.x.x.x/ --uri ws://y.y.y.y/ 
    140  
    141 This will create following network:: 
    142  
    143        (ethws0)  (ethws1)  (ethws2)             (ethws0) 
    144            |        |         |                    | 
    145      +-----+--------+---------+-----+     +--------+--------+ 
    146      |           server (A)         |     |   server (B)    | 
    147      |        (ws://x.x.x.x/)       |     | (ws://y.y.y.y/) | 
    148      +-----+------------------+-----+     +-----+-----------+ 
    149            |                  |                 | 
    150            |    (WebSocket)   |    +------------+ 
    151            |                  |    | 
    152    +-------+------+   +-------+----+--+ 
    153    |  client (C)  |   |   client (D)  | 
    154    +--+--------+--+   +-------+-------+ 
    155       |        |              | 
    156   (ethws0)  (ethws1)      (ethws0) 
    157  
    158 Also you can use TAP interface which is created by etherws as 802.1Q VLAN 
    159 interface using vconfig command and so on. 
    160  
    161210History 
    162211======= 
     2121.0 (2012-XX-XX JST) 
     213  - global architecture change 
     214 
    1632150.7 (2012-06-29 JST) 
    164216  - switching support 
Note: See TracChangeset for help on using the changeset viewer.