[141] | 1 | Introduction |
---|
| 2 | ============ |
---|
[216] | 3 | etherws is an implementation of Ethernet over WebSocket tunnel based on Linux |
---|
| 4 | Universal TUN/TAP device driver. |
---|
[141] | 5 | |
---|
[216] | 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*:: |
---|
[141] | 10 | |
---|
[216] | 11 | [tap] |
---|
| 12 | | |
---|
| 13 | +-----+------+ (control) |
---|
| 14 | | etherws sw | <-----------+ |
---|
| 15 | +-----||-----+ | |
---|
| 16 | || +-------------+ |
---|
| 17 | (WebSocket) | etherws ctl | |
---|
| 18 | || +-------------+ |
---|
| 19 | +-----||-----+ | |
---|
| 20 | | etherws sw | <-----------+ |
---|
| 21 | +-----+------+ (control) |
---|
| 22 | | |
---|
| 23 | [tap] |
---|
[141] | 24 | |
---|
[216] | 25 | Basic Usage |
---|
| 26 | =========== |
---|
| 27 | For example, consider creating following simple network:: |
---|
[141] | 28 | |
---|
[216] | 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) |
---|
[141] | 40 | |
---|
[216] | 41 | In this case, *WebSocket Tunnel* will be created by following commands. |
---|
[141] | 42 | |
---|
[216] | 43 | on NodeA:: |
---|
[141] | 44 | |
---|
[216] | 45 | # etherws sw |
---|
| 46 | # etherws ctl addport tap ethws0 |
---|
[218] | 47 | # etherws ctl setif --address 192.0.2.10 --netmask 255.255.255.0 1 |
---|
[141] | 48 | |
---|
[216] | 49 | on NodeB:: |
---|
[146] | 50 | |
---|
[216] | 51 | # etherws sw |
---|
| 52 | # etherws ctl addport tap ethws0 |
---|
[218] | 53 | # etherws ctl setif --address 192.0.2.5 --netmask 255.255.255.0 1 |
---|
[216] | 54 | # etherws ctl addport client ws://10.0.0.10/ |
---|
[144] | 55 | |
---|
[216] | 56 | *listport*, *listif* or *listfdb* commands will show you current port list, |
---|
| 57 | interface list, or forwarding database entries:: |
---|
[162] | 58 | |
---|
[216] | 59 | # etherws ctl listport |
---|
| 60 | # etherws ctl listif |
---|
| 61 | # etherws ctl listfdb |
---|
[162] | 62 | |
---|
[156] | 63 | Using SSL/TLS |
---|
[216] | 64 | ------------- |
---|
| 65 | etherws supports SSL/TLS connection. Tunnels will be encrypted and server will |
---|
| 66 | be verified by using following options. |
---|
[144] | 67 | |
---|
[216] | 68 | On server side:: |
---|
[152] | 69 | |
---|
[216] | 70 | # etherws sw --sslkey ssl.key --sslcert ssl.crt |
---|
[144] | 71 | |
---|
[156] | 72 | *ssl.key* is a server private key, and *ssl.crt* is a server certificate. |
---|
[144] | 73 | |
---|
[216] | 74 | On client side:: |
---|
[144] | 75 | |
---|
[216] | 76 | # etherws ctl addport client --cacerts ssl.crt wss://10.0.0.10/ |
---|
[152] | 77 | |
---|
[216] | 78 | URL scheme was just changed to *wss*, and CA certificate to verify server |
---|
| 79 | certificate was specified. |
---|
[156] | 80 | |
---|
[216] | 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. |
---|
[156] | 84 | |
---|
[216] | 85 | If you want to just encrypt tunnels and do not need to verify server |
---|
| 86 | certificate, then you can use *--insecure* option:: |
---|
[156] | 87 | |
---|
[216] | 88 | # etherws ctl addport client --insecure wss://10.0.0.10/ |
---|
[156] | 89 | |
---|
[216] | 90 | Note: see http://docs.python.org/library/ssl.html for more information about |
---|
| 91 | certificates. |
---|
[156] | 92 | |
---|
[152] | 93 | Client Authentication |
---|
[216] | 94 | --------------------- |
---|
| 95 | etherws supports HTTP Basic Authentication. It means you can use etherws as |
---|
| 96 | simple L2-VPN server/client. |
---|
[152] | 97 | |
---|
[216] | 98 | On server side, etherws requires user informations in Apache htpasswd format |
---|
| 99 | (and currently supports SHA-1 digest only). To create this file:: |
---|
[152] | 100 | |
---|
| 101 | # htpasswd -s -c filename username |
---|
| 102 | |
---|
[216] | 103 | If you do not have htpasswd command, then you can use python one-liner |
---|
| 104 | instead:: |
---|
[152] | 105 | |
---|
| 106 | # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))' |
---|
| 107 | |
---|
[216] | 108 | To run server with this file:: |
---|
[152] | 109 | |
---|
[216] | 110 | # etherws sw --htpasswd filename |
---|
[152] | 111 | |
---|
[216] | 112 | On client side, etherws requires username and password from option with |
---|
| 113 | *addport* command:: |
---|
[152] | 114 | |
---|
[216] | 115 | # etherws ctl addport client --user username --passwd password ws://10.0.0.10/ |
---|
[152] | 116 | |
---|
[216] | 117 | Or, password can be input from stdin:: |
---|
[152] | 118 | |
---|
[216] | 119 | # etherws ctl addport client --user username ws://10.0.0.10/ |
---|
| 120 | Client Password: |
---|
[152] | 121 | |
---|
[216] | 122 | If authentication did not succeed, then *addport* will fail. |
---|
[152] | 123 | |
---|
[216] | 124 | Note that you should not use HTTP Basic Authentication without SSL/TLS support, |
---|
| 125 | because it is insecure in itself. |
---|
[152] | 126 | |
---|
[216] | 127 | Advanced Usage |
---|
| 128 | ============== |
---|
[152] | 129 | |
---|
[216] | 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. |
---|
[170] | 136 | |
---|
[216] | 137 | If you just want to allow remote control, you can use following options for |
---|
| 138 | example:: |
---|
[170] | 139 | |
---|
[216] | 140 | # etherws sw --ctlhost 10.0.0.10 --ctlport 1234 |
---|
[170] | 141 | |
---|
[216] | 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. |
---|
[170] | 144 | |
---|
[216] | 145 | Here, *etherws ctl* can control remote *etherws sw* using following option:: |
---|
[170] | 146 | |
---|
[216] | 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 |
---|
| 195 | # brctl addbr br0 |
---|
| 196 | # brctl addif br0 vnet0 |
---|
| 197 | # brctl addif br0 ethws0 |
---|
| 198 | # ifconfig br0 up |
---|
| 199 | |
---|
| 200 | on HypervisorB:: |
---|
| 201 | |
---|
| 202 | # etherws sw |
---|
| 203 | # etherws ctl addport tap ethws0 |
---|
| 204 | # etherws ctl addport client ws://HypervisorA/ |
---|
| 205 | # brctl addbr br0 |
---|
| 206 | # brctl addif br0 vnet0 |
---|
| 207 | # brctl addif br0 ethws0 |
---|
| 208 | # ifconfig br0 up |
---|
| 209 | |
---|
[141] | 210 | History |
---|
| 211 | ======= |
---|
[220] | 212 | 1.0 (2012-08-18 JST) |
---|
[216] | 213 | - global architecture change |
---|
| 214 | |
---|
[170] | 215 | 0.7 (2012-06-29 JST) |
---|
| 216 | - switching support |
---|
| 217 | - multiple ports support |
---|
| 218 | |
---|
[162] | 219 | 0.6 (2012-06-16 JST) |
---|
| 220 | - improve performance |
---|
| 221 | |
---|
[160] | 222 | 0.5 (2012-05-20 JST) |
---|
| 223 | - added passwd option to client mode |
---|
| 224 | - fixed bug: basic authentication password cannot contain colon |
---|
| 225 | - fixed bug: client loops meaninglessly even if server stops |
---|
| 226 | |
---|
[158] | 227 | 0.4 (2012-05-19 JST) |
---|
| 228 | - server certificate verification support |
---|
| 229 | |
---|
[152] | 230 | 0.3 (2012-05-17 JST) |
---|
| 231 | - client authentication support |
---|
| 232 | |
---|
[144] | 233 | 0.2 (2012-05-16 JST) |
---|
| 234 | - SSL/TLS connection support |
---|
| 235 | |
---|
| 236 | 0.1 (2012-05-15 JST) |
---|
[141] | 237 | - First release |
---|