update README.md

2024-11-08 00:13:59 +01:00 · 2021-08-30 14:24:46 +08:00 · 2021-08-30 14:24:46 +08:00 · 0cff923ed6
commit 0cff923ed6
parent c27695063d
8 changed files with 178 additions and 43 deletions
--- a/README.md
+++ b/README.md
@ -1,37 +1,142 @@
 # Etherguard
-[中文](README_zh.md)

-WIP
+[中文版README](README_zh.md)
+
+A Full Mesh Layer2 VPN based on wireguard-go  
+
+OSPF can find best route based on it's cost.  
+But sometimes the lentancy are different in the packet goes and back.  
+I'am thinking, is it possible to find the best route based on the **single-way latency**?  
+For example, I have two routes A and B at node N1, both of them can reach my node N2. A goes fast, but B backs fast.  
+My VPN can automatically send packet through route A at node N1, and the packet backsfrom route B.
+
+Here is the solution. This VPN `Etherguard` can collect all the single-way lentancy from all nodes, and calculate the best route using [Floyd–Warshall algorithm](https://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm).
+
+## Usage
+
+```bash
+Usage of ./etherguard-go:
+  -config string
+        Config path.
+  -example
+        Print example config
+  -help
+        Show this help
+  -mode string
+        Running mode. [super|edge|solve]
+  -no-uapi
+        Do not use UAPI
+  -version
+        Show version
+```
+
+## Mode
+
+1. Static Mode: Similar to origional wireguard. [Introduction](example_config/static_mode/README.md).
+2. Super Mode: Inspired by[n2n](https://github.com/ntop/n2n). [Introduction](example_config/super_mode/README.md).
+3. P2P Mode: Inspired by[tinc](https://github.com/gsliepen/tinc). [Introduction](example_config/p2p_mode/README.md).
+
+## Common Config Paramater
+
+### Edge Config
+
+1. `interface`
+    1. `itype`: Interface type.
+        1. `dummy`: Dymmy interface, drop any packet received. You need this if you want to setup it as a relay node.
+        2. `stdio`: Wrtie to stdout，read from stdin.  
+           Paramaters: `macaddrprefix`,`l2headermode`
+        3. `udpsock`: Write to an udp socket, and read from an net assress.  
+           Paramaters: `macaddrprefix`,`recvaddr`,`sendaddr`
+        4. `vpp`: Integrate to VPP by libmemif.  
+           Paramaters: `name`,`vppifaceid`,`vppbridgeid`,`macaddrprefix`,`mtu`
+        5. `tap`: Read/Write to tap device from linux.  
+           Paramaters: `name`,`macaddrprefix`,`vppifaceid`,`mtu`
+    2. `name` : Device name
+    3. `vppifaceid`: Interface ID。Muse be unique in same VPP runtime
+    4. `vppbridgeid`: VPP Bridge ID. Fill 0 if you don't use it.
+    5. `macaddrprefix`: Mac address Prefix。Real Mac address=[Prefix]:[vppifaceid]。  
+    6. `recvaddr`: Listen address for `udpsock` mode
+    7. `sendaddr`: Packet send address for `udpsock` mode
+    8. `l2headermode`: For debug usage, `stdio` and `udpsock` mode only
+        1. `nochg`: Do not change anything.
+        2. `kbdbg`: Keyboard debug mode.  
+                    Let me construct Layer 2 header by ascii character only.  
+                    So that I can track the packet flow with `loglevel` option.
+        3. `noL2`: Remove all Layer 2 header
+2. `nodeid`: NodeID. Must be unique in the whole Etherguard network.
+3. `nodename`: Node Name.
+4. `privkey`: Private key. Same spec as wireguard.
+5. `listenport`: UDP lesten port
+6. `loglevel`: Log Level
+    1. `loglevel`: wireguard原本的log紀錄器的loglevel。  
+       有`debug`,`error`,`slient`三種程度
+    2. `logtransit`: Log packets that neither the source or distenation is self.
+    3. `logcontrol`: Log for all Control Message.
+    4. `lognormal`: Log packets that either the source or distenation is self.
+    5. `logntp`: NTP related logs.
+7. `dynamicroute`: Log for dynamic route.
+    1. `sendpinginterval`: Send `Ping` interval
+    2. `dupchecktimeout`: Duplication chack timeout.
+    3. `conntimeout`: Connection timeout.
+    4. `savenewpeers`: Save peer info to local file.
+    5. `supernode`: See [Super Mode](example_config/super_mode/README_zh.md)
+    6. `p2p` See [P2P Mode](example_config/p2p_mode/README_zh.md)
+    7. `ntpconfig`: NTP related settings
+        1. `usentp`: USE NTP or not.
+        2. `maxserveruse`: How many NTP servers should we use at once.  
+           First time we will measure lentancy for all NTP server, next time it will use only fastest server.
+        3. `synctimeinterval`: NTP sync interval.
+        4. `ntptimeout`: NTP timeout
+        5. `servers`: NTP server list
+8. `nexthoptable`: Nexthop table。Only static mode use it. See [Static Mㄍㄟ](example_config/super_mode/README_zh.md)
+9. `resetconninterval`: Reset the endpoint for peers. You may need this if that peer use DDNS.
+10. `peers`: Peer info.
+    1. `nodeid`: Node ID.
+    2. `pubkey`: Public key.
+    3. `pskey`: Preshared key. Not implement yet.
+    4. `endpoint`: Peer enddpoint. Will be overwrite if the peer roaming unless static=true.
+    5. `static`: Do not overwrite by roaming and reset the connection every `resetconninterval` seconds.
+
+### Super config
+
+See [Super Mode](example_config/super_mode/README.md).

 ## Build

 ### No-vpp version

-#### Dependency
-Go 1.16
+Build Etherguard.  
+
+Install Go 1.16
+
 ```bash
 add-apt-repository ppa:longsleep/golang-backports
 apt-get -y update
 apt-install -y wireguard-tools golang-go build-essential
 ```
-#### Build
+
+Build
+
 ```bash
 make
 ```

 ### VPP version

-#### Dependency
+Build Etherguard with VPP integrated.  
+You need libmemif.so installed to run this version.

-VPP and libemif is requires
+Install VPP and libemif

-```
+```bash
 echo "deb [trusted=yes] https://packagecloud.io/fdio/release/ubuntu focal main" > /etc/apt/sources.list.d/99fd.io.list
 curl -L https://packagecloud.io/fdio/release/gpgkey | sudo apt-key add -
 apt-get -y update
 apt-get install -y vpp vpp-plugin-core python3-vpp-api vpp-dbg vpp-dev libmemif libmemif-dev
 ```
-#### Build
+
+Build
+
 ```bash
 make vpp
-```
+```
--- a/README_zh.md
+++ b/README_zh.md
@ -1,5 +1,8 @@

 # Etherguard
+
+[English](README.md)
+
 一個從wireguard-go改來的Full Mesh Layer2 VPN.  

 OSPF能夠根據cost自動選路  
@ -14,7 +17,8 @@ OSPF能夠根據cost自動選路
 沒問題的，證明可以看這邊: [https://www.kskb.eu.org/2021/08/rootless-routerpart-3-etherguard.html](https://www.kskb.eu.org/2021/08/rootless-routerpart-3-etherguard.html)

 ## Usage
-```
+
+```bash
 Usage of ./etherguard-go-vpp:
  -config string
        設定檔路徑
@ -33,41 +37,44 @@ Usage of ./etherguard-go-vpp:

 ## Mode

-1. Static 模式: 類似於原本的wireguard。  
-    *  沒有自動選路，沒有握手伺服器  
-        一切都要提前配置好
-    * 參見: [example_config/static_mode/README_zh.md](example_config/static_mode/README_zh.md)
-2. Super 模式: 受到[n2n](https://github.com/ntop/n2n)的啟發，分為super node和edge node兩種節點  
-    * 全部節點會和supernode建立連線  
-      藉由supernode交換其他節點的資訊，以及udp打洞  
-      由supernode執行[Floyd-Warshall演算法](https://zh.wikipedia.org/zh-tw/Floyd-Warshall算法)，並把計算結果分發給全部edge node
-    * 參見: [example_config/super_mode/README_zh.md](example_config/super_mode/README_zh.md)
-3. P2P 模式: 受到[tinc](https://github.com/gsliepen/tinc)的啟發
-    * 每個節點都類似super node  
-      會定期廣播自己所有已連線節點的連線ip:port，公鑰和preshared key  
-      每個節點都自己執行[Floyd-Warshall演算法](https://zh.wikipedia.org/zh-tw/Floyd-Warshall算法)  
-      並且廣播收到的單向延遲資訊讓其他節點也能計算
-    * 參見: [example_config/p2p_mode/README_zh.md](example_config/p2p_mode/README_zh.md)
+1. Static 模式: 類似於原本的wireguard的模式。 [詳細介紹](example_config/static_mode/README_zh.md)
+2. Super 模式: 受到[n2n](https://github.com/ntop/n2n)的啟發寫的模式。 [詳細介紹](example_config/super_mode/README_zh.md)
+3. P2P 模式: 受到[tinc](https://github.com/gsliepen/tinc)的啟發寫的模式。 [詳細介紹](example_config/p2p_mode/README_zh.md)
+
 ## Common Config Paramater
+
 有些設定檔對應某些運作模式，這邊針對共同部分的設定做說明
+
 ### Edge config
+
 邊緣節點是實際執行VPN的節點

 1. `interface`
-    1. `itype`: 裝置類型，意味著收到的封包要丟去哪
-        1. `dummy`: 收到的封包直接丟棄，也不發出任何封包。作為中繼節點可以用
+    1. `itype`: 裝置類型，意味著從VPN網路收到的封包要丟去哪個硬體
+        1. `dummy`: 收到的封包直接丟棄，也不發出任何封包。作為中繼節點使用
        2. `stdio`: 收到的封包丟stdout，stdin進來的資料丟入vpn網路  
           需要參數: `macaddrprefix`,`l2headermode`
-        2. `udpsock`: 收到的封包用udp丟到某個網路位置，監聽port進來的資料丟去vpn網路  
+        3. `udpsock`: 收到的封包用udp丟到某個網路位置，監聽port進來的資料丟去vpn網路  
           需要參數: `macaddrprefix`,`recvaddr`,`sendaddr`
-        2. `vpp`: 使用libmemif使vpp加入VPN網路  
+        4. `vpp`: 使用libmemif使vpp加入VPN網路  
           需要參數: `name`,`vppifaceid`,`vppbridgeid`,`macaddrprefix`,`mtu`
-        2. `tap`: Linux的tap設備。讓linux加入VPN網路  
+        5. `tap`: Linux的tap設備。讓linux加入VPN網路  
           需要參數: `name`,`macaddrprefix`,`mtu`
    2. `name` : 裝置名稱
    3. `vppifaceid`: VPP 的 interface ID。一個VPP runtime內不能重複
    4. `vppbridgeid`: VPP 的網橋ID。不使用VPP網橋功能的話填0
-    5. `macaddrprefix`: MAC地址前綴。真正的MAC地址=[前綴]:[vppifaceid]。如果填了6格長度就忽略`vppifaceid`
+    5. `macaddrprefix`: MA C地址前綴。真正的 MAC 地址=[前綴]:[vppifaceid]。  
+        如果填了6格長度就忽略`vppifaceid`
+    6. `recvaddr`: 僅限`udpsock`生效。收到的東西丟去 VPN 網路
+    7. `sendaddr`: 僅限`udpsock`生效。VPN網路收到的東西丟去這個 udp 地址
+    8. `l2headermode`: 僅限 `stdio` 和 `udpsock` 生效。debug用途，有三種模式:
+        1. `nochg`: 從 VPN 網路收到什麼，就往tap裝置發送什麼。不對封包作任何更動
+        2. `kbdbg`: 鍵盤bebug模式。搭配 `stdio` 模式，讓我 debug 用  
+            因為前 12 byte 會用來做選路判斷，但是只是要debug，構造完整的封包就不是很方便  
+            這個模式下，如果輸入b2content，就會幫你把b轉換成`FF:FF:FF:FF:FF:FF`， `2` 轉換成 `AA:BB:CC:DD:EE:02` 。封包內容變成 `b"0xffffffffffffaabbccddee02content"`。
+            用鍵盤就能輕鬆產生L2 header，查看選路的行為
+        3. `noL2`: 拔掉L2 Header的模式。  
+           但是本VPN會查詢L2用作選路，所以會變成一律廣播
 2. `nodeid`: 節點ID。節點之間辨識身分用的，同一網路內節點ID不能重複
 3. `nodename`: 節點名稱
 4. `privkey`: 私鑰，和wireguard規格一樣
@ -84,8 +91,8 @@ Usage of ./etherguard-go-vpp:
    2. `dupchecktimeout`: 重複封包檢查的timeout。完全相同的封包收第二次會被丟棄
    3. `conntimeout`: 鄰居應該要發Ping過來，超過就視為鄰居掛了
    4. `savenewpeers`: 是否把下載來的鄰居資訊存到本地設定檔裡面
-    5. `supernode`: Super模式相關的設定，參見[example_config/super_mode/README_zh.md](example_config/super_mode/README_zh.md)
-    6. `p2p` P2P模式相關的設定，參見 [example_config/p2p_mode/README_zh.md](example_config/p2p_mode/README_zh.md)
+    5. `supernode`: 參見[Super模式](example_config/super_mode/README_zh.md)
+    6. `p2p` 參見 [P2P模式](example_config/p2p_mode/README_zh.md)
    7. `ntpconfig`: NTP 相關的設定
        1. `usentp`: 是否使用ntp同步時鐘
        2. `maxserveruse`: 一次對多連線幾個NTP伺服器  
@ -93,7 +100,7 @@ Usage of ./etherguard-go-vpp:
        3. `synctimeinterval`: 多久同步一次
        4. `ntptimeout`: 多久算是超時
        5. `servers`: NTP伺服器列表
-8. `nexthoptable`: 轉發表。只有Static模式會用到，參見 [example_config/super_mode/README_zh.md](example_config/super_mode/README_zh.md)
+8. `nexthoptable`: 轉發表。只有Static模式會用到，參見 [Static模式](example_config/super_mode/README_zh.md)
 9. `resetconninterval`: 如果對方是動態ip就要用這個。每隔一段時間就會重新解析domain。
 10. `peers`: 和wireguard一樣的peer資訊
    1. `nodeid`: 對方的節點ID
@ -103,41 +110,46 @@ Usage of ./etherguard-go-vpp:
    5. `static`: 設定成true的話，每隔`resetconninterval`秒就會重新解析一次domain，與此同時也不會被roaming覆寫

 ### Super config
-  參見 [example_config/super_mode/README_zh.md](example_config/super_mode/README_zh.md)

+  參見 [example_config/super_mode/README_zh.md](example_config/super_mode/README_zh.md)

 ## Build

 ### No-vpp version
+
 編譯沒有VPP libmemif的版本。可以在一般linux電腦上使用

-#### Dependency
 安裝 Go 1.16
+
 ```bash
 add-apt-repository ppa:longsleep/golang-backports
 apt-get -y update
 apt-install -y wireguard-tools golang-go build-essential
 ```
-#### Build
+
+Build
+
 ```bash
 make
 ```

 ### VPP version
+
 編譯有VPP libmemif的版本。

 用這個版本的話你的電腦要有libmemif.so才能run起來

-#### Dependency
-
 安裝 VPP 和 libemif
-```
+
+```bash
 echo "deb [trusted=yes] https://packagecloud.io/fdio/release/ubuntu focal main" > /etc/apt/sources.list.d/99fd.io.list
 curl -L https://packagecloud.io/fdio/release/gpgkey | sudo apt-key add -
 apt-get -y update
 apt-get install -y vpp vpp-plugin-core python3-vpp-api vpp-dbg vpp-dev libmemif libmemif-dev
 ```
-#### Build
+
+Build
+
 ```bash
 make vpp
-```
+```
--- a/example_config/p2p_mode/README.md
+++ b/example_config/p2p_mode/README.md
@ -0,0 +1,4 @@
+# Etherguard
+[中文版](README_zh.md)
+
+WIP
--- a/example_config/p2p_mode/README_zh.md
+++ b/example_config/p2p_mode/README_zh.md
@ -1,4 +1,6 @@
 # Etherguard
+[English](README.md)
+
 P2P Mode的[範例配置檔](./)的說明文件
 在了解Super Mode的運作之前，建議您先閱讀[Super Mode的運作](../super_mode/README_zh.md)方法，再閱讀本篇會比較好

--- a/example_config/static_mode/README.md
+++ b/example_config/static_mode/README.md
@ -0,0 +1,4 @@
+# Etherguard
+[中文版](README_zh.md)
+
+WIP
--- a/example_config/static_mode/README_zh.md
+++ b/example_config/static_mode/README_zh.md
@ -1,4 +1,6 @@
 # Etherguard
+[English](README.md)
+
 Static Mode的[範例配置檔](./)的說明文件

 ## Static Mode
--- a/example_config/super_mode/README.md
+++ b/example_config/super_mode/README.md
@ -0,0 +1,4 @@
+# Etherguard
+[中文版](README_zh.md)
+
+WIP
--- a/example_config/super_mode/README_zh.md
+++ b/example_config/super_mode/README_zh.md
@ -1,4 +1,6 @@
 # Etherguard
+[English](README.md)
+
 Super Mode的[範例配置檔](./)的說明文件
 在了解Super Mode的運作之前，建議您先閱讀[Static Mode的運作](../static_mode/README_zh.md)方法，再閱讀本篇會比較好