Changeset 216 for etherws/trunk
- Timestamp:
- 08/17/12 01:33:46 (12 years ago)
- File:
-
- 1 edited
-
etherws/trunk/README.rst (modified) (3 diffs)
Legend:
- Unmodified
- Added
- Removed
-
etherws/trunk/README.rst
r170 r216 1 1 Introduction 2 2 ============ 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 3 etherws is an implementation of Ethernet over WebSocket tunnel based on Linux 4 Universal TUN/TAP device driver. 5 6 Overview 7 ======== 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) 14 | etherws sw | <-----------+ 15 +-----||-----+ | 16 || +-------------+ 17 (WebSocket) | etherws ctl | 18 || +-------------+ 19 +-----||-----+ | 20 | etherws sw | <-----------+ 21 +-----+------+ (control) 22 | 23 [tap] 24 25 Basic Usage 26 =========== 27 For 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 41 In this case, *WebSocket Tunnel* will be created by following commands. 42 43 on 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 49 on 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, 57 interface list, or forwarding database entries:: 58 59 # etherws ctl listport 60 # etherws ctl listif 61 # etherws ctl listfdb 62 63 Using SSL/TLS 64 ------------- 65 etherws supports SSL/TLS connection. Tunnels will be encrypted and server will 66 be verified by using following options. 67 68 On 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 74 On client side:: 75 76 # etherws ctl addport client --cacerts ssl.crt wss://10.0.0.10/ 77 78 URL scheme was just changed to *wss*, and CA certificate to verify server 79 certificate was specified. 80 81 Client verifies server certificate by default. So, for example, *addport* will 82 fail if your server uses self-signed certificate and client uses another CA 83 certificate. 84 85 If you want to just encrypt tunnels and do not need to verify server 86 certificate, then you can use *--insecure* option:: 87 88 # etherws ctl addport client --insecure wss://10.0.0.10/ 89 90 Note: see http://docs.python.org/library/ssl.html for more information about 91 certificates. 92 93 Client Authentication 94 --------------------- 95 etherws supports HTTP Basic Authentication. It means you can use etherws as 96 simple L2-VPN server/client. 97 98 On 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 103 If you do not have htpasswd command, then you can use python one-liner 104 instead:: 105 106 # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))' 107 108 To run server with this file:: 109 110 # etherws sw --htpasswd filename 111 112 On 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 117 Or, password can be input from stdin:: 118 119 # etherws ctl addport client --user username ws://10.0.0.10/ 120 Client Password: 121 122 If authentication did not succeed, then *addport* will fail. 123 124 Note that you should not use HTTP Basic Authentication without SSL/TLS support, 125 because it is insecure in itself. 126 127 Advanced Usage 128 ============== 129 130 Remote Control 131 -------------- 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. 136 137 If you just want to allow remote control, you can use following options for 138 example:: 139 140 # etherws sw --ctlhost 10.0.0.10 --ctlport 1234 141 142 This 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. 144 145 Here, *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 150 as well as WebSocket tunnel service. 151 152 On server side:: 153 154 # etherws sw --ctlhost 10.0.0.10 --ctlport 443 \ 155 --ctlhtpasswd htpasswd --ctlsslkey ssl.key --ctlsslcert ssl.crt 156 157 On client side:: 158 159 # etherws ctl --ctlurl https://10.0.0.10/ctl \ 160 --ctluser username --ctlpasswd password ... 161 162 Password can be input from stdin as well as WebSocket tunnel creation. 163 164 Note: *etherws ctl* currently cannot verify SSL certificate on controller. 165 166 Connect Virtual Machines 167 ------------------------ 168 For 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 189 In this case, it will be created by following commands. 190 191 on HypervisorA:: 192 193 # etherws sw 194 # etherws ctl addport tap ethws0 35 195 # brctl addbr br0 36 196 # brctl addif br0 vnet0 … … 38 198 # ifconfig br0 up 39 199 40 on *Hypervisor2*:: 41 42 # etherws --device ethws0 client --uri ws://<Hypervisor1's IP address>/ 200 on HypervisorB:: 201 202 # etherws sw 203 # etherws ctl addport tap ethws0 204 # etherws ctl addport client ws://HypervisorA/ 43 205 # brctl addbr br0 44 206 # brctl addif br0 vnet0 … … 46 208 # ifconfig br0 up 47 209 48 Additionally, you may improve performance by increasing MTU.49 For example,50 51 on each hypervisor::52 53 # ifconfig vnet0 mtu 1643654 # ifconfig ethws0 mtu 1643655 56 on each VM::57 58 # ifconfig eth0 mtu 1643659 60 Using SSL/TLS61 =============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.crt68 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>:44374 75 on *Hypervisor2*::76 77 # etherws --device ethws0 client --uri wss://<Hypervisor1's IP address>/ --cacerts ssl.crt78 79 Here, URI scheme was just changed to *wss*, and CA certificate to verify80 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 uses84 self-signed certificate and client uses another CA certificate.85 86 If you want to just encrypt tunnels and do not need to verify87 certificate, then you can use following option::88 89 # etherws --device ethws0 client --uri wss://<Hypervisor1's IP address>/ --insecure90 91 Note: see `<http://docs.python.org/library/ssl.html>`_92 for more information about certificates.93 94 Client Authentication95 =====================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 htpasswd100 format (and currently supports SHA-1 digest only). To create this file::101 102 # htpasswd -s -c filename username103 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 filename111 112 You also can test by following command::113 114 # telnet <address> 80115 GET / HTTP/1.1116 117 It will return *401 Authorization Required*.118 119 On client side, etherws requires username from option, and password from120 option or stdin::121 122 # etherws --device ethws0 client --uri ws://<address>/ --user username --passwd password123 # etherws --device ethws0 client --uri ws://<address>/ --user username124 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/TLS129 support, because it is insecure in itself.130 131 Complex Examples132 ================133 etherws has simple virtual Ethernet switch in itself and it can handle multiple134 TAP interfaces or WebSocket connections as virtual switch port::135 136 (A)# etherws --device ethws0 --device ethws1 --device ethws2 server137 (B)# etherws --device ethws0 server138 (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 VLAN159 interface using vconfig command and so on.160 161 210 History 162 211 ======= 212 1.0 (2012-XX-XX JST) 213 - global architecture change 214 163 215 0.7 (2012-06-29 JST) 164 216 - switching support
Note: See TracChangeset
for help on using the changeset viewer.
