[141] | 1 | Introduction |
---|
| 2 | ============ |
---|
[260] | 3 | etherws is an implementation of software switch with the Ethernet over |
---|
| 4 | WebSocket tunnel. |
---|
[141] | 5 | |
---|
[216] | 6 | Overview |
---|
| 7 | ======== |
---|
[260] | 8 | *etherws sw* is a simple virtual ethernet switch. And this is controlled by |
---|
| 9 | *etherws ctl*:: |
---|
[141] | 10 | |
---|
[260] | 11 | [tap] [netdev] |
---|
| 12 | | | |
---|
| 13 | +--+------+--+ (control) |
---|
[216] | 14 | | etherws sw | <-----------+ |
---|
| 15 | +-----||-----+ | |
---|
| 16 | || +-------------+ |
---|
| 17 | (WebSocket) | etherws ctl | |
---|
| 18 | || +-------------+ |
---|
| 19 | +-----||-----+ | |
---|
| 20 | | etherws sw | <-----------+ |
---|
[260] | 21 | +--+------+--+ (control) |
---|
| 22 | | | |
---|
| 23 | [tap] [netdev] |
---|
[141] | 24 | |
---|
[216] | 25 | Basic Usage |
---|
| 26 | =========== |
---|
| 27 | For example, consider creating following simple network:: |
---|
[141] | 28 | |
---|
[216] | 29 | (Physical Network) |
---|
[260] | 30 | -----+--------- // --------+----- |
---|
[216] | 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 | |
---|
[260] | 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 | ------------- |
---|
[260] | 65 | etherws supports SSL/TLS connection. Tunnels will be encrypted and server will |
---|
[216] | 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 | |
---|
[260] | 72 | *ssl.key* is a server private key, and *ssl.crt* is a server |
---|
| 73 | certificate. |
---|
[144] | 74 | |
---|
[216] | 75 | On client side:: |
---|
[144] | 76 | |
---|
[216] | 77 | # etherws ctl addport client --cacerts ssl.crt wss://10.0.0.10/ |
---|
[152] | 78 | |
---|
[216] | 79 | URL scheme was just changed to *wss*, and CA certificate to verify server |
---|
| 80 | certificate was specified. |
---|
[156] | 81 | |
---|
[260] | 82 | Client verifies server certificate by default. So, for example, *addport* will |
---|
[216] | 83 | fail if your server uses self-signed certificate and client uses another CA |
---|
| 84 | certificate. |
---|
[156] | 85 | |
---|
[216] | 86 | If you want to just encrypt tunnels and do not need to verify server |
---|
| 87 | certificate, then you can use *--insecure* option:: |
---|
[156] | 88 | |
---|
[216] | 89 | # etherws ctl addport client --insecure wss://10.0.0.10/ |
---|
[156] | 90 | |
---|
[216] | 91 | Note: see http://docs.python.org/library/ssl.html for more information about |
---|
| 92 | certificates. |
---|
[156] | 93 | |
---|
[152] | 94 | Client Authentication |
---|
[216] | 95 | --------------------- |
---|
[260] | 96 | etherws supports HTTP Basic Authentication. This means you can use etherws as |
---|
[216] | 97 | simple L2-VPN server/client. |
---|
[152] | 98 | |
---|
[216] | 99 | On server side, etherws requires user informations in Apache htpasswd format |
---|
[260] | 100 | (and currently supports SHA-1 digest only). To create this file:: |
---|
[152] | 101 | |
---|
| 102 | # htpasswd -s -c filename username |
---|
| 103 | |
---|
[216] | 104 | If you do not have htpasswd command, then you can use python one-liner |
---|
| 105 | instead:: |
---|
[152] | 106 | |
---|
| 107 | # python -c 'import hashlib; print("username:{SHA}" + hashlib.sha1("password").digest().encode("base64"))' |
---|
| 108 | |
---|
[216] | 109 | To run server with this file:: |
---|
[152] | 110 | |
---|
[216] | 111 | # etherws sw --htpasswd filename |
---|
[152] | 112 | |
---|
[216] | 113 | On client side, etherws requires username and password from option with |
---|
| 114 | *addport* command:: |
---|
[152] | 115 | |
---|
[216] | 116 | # etherws ctl addport client --user username --passwd password ws://10.0.0.10/ |
---|
[152] | 117 | |
---|
[216] | 118 | Or, password can be input from stdin:: |
---|
[152] | 119 | |
---|
[216] | 120 | # etherws ctl addport client --user username ws://10.0.0.10/ |
---|
| 121 | Client Password: |
---|
[152] | 122 | |
---|
[216] | 123 | If authentication did not succeed, then *addport* will fail. |
---|
[152] | 124 | |
---|
[216] | 125 | Note that you should not use HTTP Basic Authentication without SSL/TLS support, |
---|
[260] | 126 | because this is insecure in itself. |
---|
[152] | 127 | |
---|
[216] | 128 | Advanced Usage |
---|
| 129 | ============== |
---|
[152] | 130 | |
---|
[216] | 131 | Remote Control |
---|
| 132 | -------------- |
---|
[260] | 133 | *etherws ctl* controls *etherws sw* by JSON-RPC over HTTP. This means you can |
---|
| 134 | control *etherws sw* from remote nodes. However, allowing remote control |
---|
| 135 | without careful consideration also allows to attack to your server or |
---|
| 136 | network. So control URL is bound to localhost by default. |
---|
[170] | 137 | |
---|
[216] | 138 | If you just want to allow remote control, you can use following options for |
---|
| 139 | example:: |
---|
[170] | 140 | |
---|
[216] | 141 | # etherws sw --ctlhost 10.0.0.10 --ctlport 1234 |
---|
[170] | 142 | |
---|
[216] | 143 | This means allowing remote control from any nodes that can access |
---|
[260] | 144 | 10.0.0.10:1234 TCP/IP. Of course this is very dangerous as described above. |
---|
[170] | 145 | |
---|
[216] | 146 | Here, *etherws ctl* can control remote *etherws sw* using following option:: |
---|
[170] | 147 | |
---|
[216] | 148 | # etherws ctl --ctlurl http://10.0.0.10:1234/ctl ... |
---|
| 149 | |
---|
| 150 | *etherws sw* controller supports SSL/TLS connection and client authentication |
---|
| 151 | as well as WebSocket tunnel service. |
---|
| 152 | |
---|
| 153 | On server side:: |
---|
| 154 | |
---|
| 155 | # etherws sw --ctlhost 10.0.0.10 --ctlport 443 \ |
---|
| 156 | --ctlhtpasswd htpasswd --ctlsslkey ssl.key --ctlsslcert ssl.crt |
---|
| 157 | |
---|
| 158 | On client side:: |
---|
| 159 | |
---|
| 160 | # etherws ctl --ctlurl https://10.0.0.10/ctl \ |
---|
| 161 | --ctluser username --ctlpasswd password ... |
---|
| 162 | |
---|
| 163 | Password can be input from stdin as well as WebSocket tunnel creation. |
---|
| 164 | |
---|
[260] | 165 | Virtual Machines Connection |
---|
| 166 | --------------------------- |
---|
[216] | 167 | For example, consider creating following virtual machine network:: |
---|
| 168 | |
---|
| 169 | +------------------+ +------------------+ |
---|
| 170 | | HypervisorA | | HypervisorB | |
---|
| 171 | | +-----+ | | +-----+ | |
---|
| 172 | | | VM | | | | VM | | |
---|
| 173 | | +--+--+ | | +--+--+ | |
---|
[260] | 174 | | (vnet0) | | (vnet0) | |
---|
[216] | 175 | | | | | | | |
---|
[260] | 176 | | [etherws] (eth0) | | (eth0) [etherws] | |
---|
[216] | 177 | +----||--------+---+ +----+-------||----+ |
---|
| 178 | || | | || |
---|
[260] | 179 | || -----+--------- // ---------+----- || |
---|
[216] | 180 | || (Physical Network) || |
---|
| 181 | || || |
---|
| 182 | ``======================================='' |
---|
| 183 | (WebSocket Tunnel) |
---|
| 184 | |
---|
[260] | 185 | Existing network interfaces can also be added to *etherws sw*. |
---|
| 186 | So in this case, this will be created by following commands. |
---|
[216] | 187 | |
---|
| 188 | on HypervisorA:: |
---|
| 189 | |
---|
| 190 | # etherws sw |
---|
[260] | 191 | # etherws ctl addport netdev vnet0 |
---|
[216] | 192 | |
---|
| 193 | on HypervisorB:: |
---|
| 194 | |
---|
| 195 | # etherws sw |
---|
[260] | 196 | # etherws ctl addport netdev vnet0 |
---|
[216] | 197 | # etherws ctl addport client ws://HypervisorA/ |
---|
| 198 | |
---|
[260] | 199 | Of course, you can create the TAP port and connect these using the Linux Bridge |
---|
| 200 | or the like. |
---|
| 201 | |
---|
[141] | 202 | History |
---|
| 203 | ======= |
---|
[276] | 204 | 1.3 |
---|
[279] | 205 | - http proxy support on client connection |
---|
[276] | 206 | - fix listport bug on tornado 4.0.x |
---|
| 207 | |
---|
[274] | 208 | 1.2 (2014-12-29 JST) |
---|
| 209 | - verification of controller SSL certificate support |
---|
| 210 | - correspond to some library updates |
---|
| 211 | |
---|
[260] | 212 | 1.1 (2013-10-10 JST) |
---|
| 213 | - netdev (existing network interfaces) support |
---|
| 214 | |
---|
[220] | 215 | 1.0 (2012-08-18 JST) |
---|
[216] | 216 | - global architecture change |
---|
| 217 | |
---|
[170] | 218 | 0.7 (2012-06-29 JST) |
---|
| 219 | - switching support |
---|
| 220 | - multiple ports support |
---|
| 221 | |
---|
[162] | 222 | 0.6 (2012-06-16 JST) |
---|
| 223 | - improve performance |
---|
| 224 | |
---|
[160] | 225 | 0.5 (2012-05-20 JST) |
---|
| 226 | - added passwd option to client mode |
---|
| 227 | - fixed bug: basic authentication password cannot contain colon |
---|
| 228 | - fixed bug: client loops meaninglessly even if server stops |
---|
| 229 | |
---|
[158] | 230 | 0.4 (2012-05-19 JST) |
---|
| 231 | - server certificate verification support |
---|
| 232 | |
---|
[152] | 233 | 0.3 (2012-05-17 JST) |
---|
| 234 | - client authentication support |
---|
| 235 | |
---|
[144] | 236 | 0.2 (2012-05-16 JST) |
---|
| 237 | - SSL/TLS connection support |
---|
| 238 | |
---|
| 239 | 0.1 (2012-05-15 JST) |
---|
[141] | 240 | - First release |
---|