Skip to content

README_cn.md

Latest commit

 

History

History
440 lines (273 loc) · 12.3 KB

README_cn.md

File metadata and controls

440 lines (273 loc) · 12.3 KB

Meepo

Telegram PRs Welcome

Meepo的目标是以便捷的, 去中心化的形式发布服务.

本项目还处于初期版本, 接口变动会相对频繁, 请留意.

由于接口变动, v0.6或更高版本无法向下兼容, 请升级到最新版本.

安装

Linux

$ sudo snap install meepo

如果发行版不支持snap, 需要从release下载对应版本并手动安装.

macOS

$ brew install PeerXu/tap/meepo

Windows

暂时不支持从chocolatey安装, 需要从release下载对应版本并手动安装.

快速入门

初始化

Meepo采用ED25519算法作为身份标识算法.

运行meepo serve命令, 启动Meepo服务.

$ meepo serve

运行meepo whoami命令, 可以获得Meepo服务的MeepoID.

$ meepo whoami
# OUTPUT:
61pwmvz1lpm038xwku3njzj21h9na71clie4wv9px1kcxfk49z4

运行meepo shutdown命令, 可以关闭Meepo服务.

$ meepo shutdown
# OUTPUT:
Meepo shutting down

由于未指定身份标识文件, meepo serve运行时, 会生成随机身份, 方便将要启动的Meepo服务能够正常接入Meepo网络.

可以通过meepo keygen或ssh-keygen生成身份标识文件.

采用ssh-keygen生成身份识别文件会同时产生私钥和公钥文件, 忽略公钥文件即可.

暂时不支持带passphrase的OpenSSH私钥.

$ meepo keygen -f meepo.pem
# OR
$ ssh-keygen -t ed25519 -f meepo.pem

生成身份识别文件成功之后, 启动Meepo服务指定身份标识文件.

$ meepo serve -i meepo.pem

Meepo服务启动成功后, 再通过meepo whoami获取当前的MeepoID.

$ meepo whoami
# OUTPUT:
63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey

发布一个服务到Meepo网络

假如, 现在alice需要发布一个HelloWorld服务到Meepo网络.

先来实现一个简单的HelloWorld服务.

# alice:terminal:1
alice$ cat << EOF > index.html
<h1>Hello World!</h1>
EOF
alice$ cat index.html
# OUTPUT:
<h1>Hello World!</h1>

alice$ python3 -m http.server 8080

# alice:terminal:2
alice$ curl http://127.0.0.1:8080
# OUTPUT:
<h1>Hello World!</h1>

这样我们就为alice实现了一个HelloWorld服务.

接着启动Meepo服务和获取MeepoID.

# alice:terminal:2
alice$ meepo serve
alice: meepo whoami
# OUTPUT:
63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey

这时候, 已经完成整个发布流程.

访问已经发布到Meepo网络的服务

接下来, 我们将讲解bob如何访问alice的HelloWorld服务.

首先, bob也需要运行一个Meepo服务, 但是由于bob并不需要发布服务, 所以使用随机身份即可.

# bob:terminal:1
bob$ meepo serve

然后, 运行meepo teleport命令, 使bob的Meepo服务生成一条Teleportation通往alice的HelloWorld服务.

# bob:terminal:1
bob$ meepo teleport -n alice:http:8080 -l 127.0.0.1:8080 63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey 127.0.0.1:8080
# Wait a few minutes...
# OUTPUT:
Teleport SUCCESS
Enjoy your teleportation with 127.0.0.1:8080

bob$ meepo teleportation list
# OUTPUT:
+-----------------+-----------------------------------------------------+--------+--------------------+--------------------+----------+
|      NAME       |                      TRANSPORT                      | PORTAL |       SOURCE       |        SINK        | CHANNELS |
+-----------------+-----------------------------------------------------+--------+--------------------+--------------------+----------+
| alice:http:8080 | 63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey | source | tcp:127.0.0.1:8080 | tcp:127.0.0.1:8080 |        0 |
+-----------------+-----------------------------------------------------+--------+--------------------+--------------------+----------+
bob$ curl http://127.0.0.1:8080
# OUTPUT:
<h1>Hello World!</h1>

当bob不再需要访问该服务时, 可以通过meepo teleportation close命令关闭Teleportation.

# bob:terminal:1
bob$ meepo teleportation close alice:http:8080
# OUTPUT:
Teleportation is closing

原理

TBD

特性

自组网 (Selfmesh)

自组网是Meepo的特性, 允许Meepo服务成为Signaling Server(WebRTC建立连接需要交换信令, Signaling Server提供交换的服务).

举个简单的例子:

比如现在有三个节点, 分别为alice, bob和eve.

alice与bob建立了Transport.

eve与bob建立了Transport.

当自组网特性未启用时, 如果需要为alice和eve的创建Transport时, 使用的是默认的Signaling Server.

未启用自组网时, 交换Signaling示意图:

alice --- Default Signaling Server --- eve

但是, 当自组网特性启用后, 会采用bob做为Signaling Server, 而不需要使用默认的Signaling Server.

启用自组网后, 交换Signaling示意图:

alice --- bob(Signaling Server) --- eve

默认参数下, 已经启动自组网功能.

SOCKS5代理

SOCKS5是我们常用的网络代理协议之一.

Meepo允许用户使用SOCKS5代理访问由Meepo服务发布的服务.

假如alice的MeepoID为63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey, 并且发布了HTTP服务, 端口为80.

在完成配置后, 可以直接在浏览器上访问http://63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.mpo/访问alice发布的HTTP服务.

域名是采用简单的定义规则, 是<id>.mpo.

默认参数下, SOCKS5代理监听地址为127.0.0.1:12341.

接下来介绍一下使用方法.

现在有两个节点, 分别为alice和bob.

在alice上, 发布两个服务, 分别是SSH服务(22端口)和HTTP服务(80端口).

在bob上, 通过SOCKS5代理访问alice发布的SSH服务和HTTP服务.

下面用curl举例子.

bob$ curl -x socks5h://127.0.0.1:12341 http://63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.mpo/
# ...

通过bob的Socks5代理访问alice节点的ssh服务.

bob$ ssh -o ProxyCommand='nc -X 5 -x 127.0.0.1:12341 %h %p' bob@63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.mpo

SOCKS5配置请参考各个系统的配置方法.

安全

认证

在默认配置下, Meepo服务之间创建Teleportation是不需要认证的. 这样带来了一定的便捷性, 同时也引入了安全问题.

所以Meepo支持以密钥(secret)的形式增加安全认证机制.

例子:

假如存在alice和bob.

alice的MeepoID为63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.

alice发布HTTP服务(80端口)和SSH服务(22端口), 并且配置secret为AliceAndBob.

alice$ cat << EOF > meepo.yaml
meepo:
  auth:
    name: secret
    secret: AliceAndBob
EOF

alice$ meepo shutdown
# ...

alice$ meepo serve --config meepo.yaml --identity-file meepo.pem

配置secret的工作已经完成.

这时候, bob需要访问alice发布的HTTP服务.

那么bob在创建Teleportation时, 需要带上参数--secret, 指定secret.

bob$ meepo teleport -n alice-http-80 -s AliceAndBob -l 127.0.0.1:8080 63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey 127.0.0.1:80
# wait a few minutes
# OUTPUT:
Teleport SUCCESS
Enjoy your teleportation with 127.0.0.1:8080

bob$ meepo teleportation list
# OUTPUT:
+---------------+-----------------------------------------------------+--------+--------------------+------------------+----------+
|     NAME      |                      TRANSPORT                      | PORTAL |       SOURCE       |       SINK       | CHANNELS |
+---------------+-----------------------------------------------------+--------+--------------------+------------------+----------+
| alice-http-80 | 63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey | source | tcp:127.0.0.1:8080 | tcp:127.0.0.1:80 |        0 |
+---------------+-----------------------------------------------------+--------+--------------------+------------------+----------+

bob$ curl http://127.0.0.1:8080/
# ...

当然, SOCKS5代理也是支持secret的.

bob通过SOCKS5代理访问alice发布的HTTP服务.

bob$ curl -X socks5h://meepo:AliceAndBob@127.0.0.1:12341 http://63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.mpo

bob通过SOCKS5代理访问alice发布的SSH服务.

bob$ ssh -o ProxyCommand='meepo ncat --proxy-type socks5 --proxy 127.0.0.1:12341 --proxy-auth meepo:AliceAndBob %h %p' bob@63eql8p54qpe1jfp1fmuumzge8y6y4ar5uml7nrrf8amqzmutey.mpo

访问控制列表

ACL是一种常用的控制访问权限的手段.

Meepo使用ACL控制其他Meepo Service调用NewTeleportation的权限.

配置的meepo.acl项可以控制ACL的行为.

$ cat meepo.yaml
meepo:
  acl:
    allows:
    - "127.0.0.1:*"
    blocks:
    - "127.0.0.1:22"

例如上面这个配置, 意思是除了端口22之外, 可以在127.0.0.1上面任意端口创建Teleportation.

ACL行为由两个列表影响, allows和blocks.

allows是允许通过的规则(AclPolicy).

blocks是不允许通过的规则.

ACL运行逻辑顺序如下:

  1. 如果触发blocks规则, 则不允许创建Teleportation.
  2. 如果触发allows规则, 则允许创建Teleportation.
  3. 不允许创建Teleportation.

下面我们来讨论一下规则.

AclPolicy的格式是source-acl-entity,destination-acl-entity.

通常情况下, source-acl-entity是可以省略的.

source-acl-entity和destination-acl-entity都是AclEntity.

AclEntity的格式是<meepo-id>:<addr-network>:<addr-host>:<addr-port>.

addr-network暂时只支持tcp, socks5和*.

通常情况下source-acl-entity.addr-network可选tcp, socks5和*, destination-acl-entity.addr-network可选tcp和*.

addr-host暂时只支持IPv4格式的IP和CIDR和*.

addr-port支持正常网络支持的端口和*.

例子:

  1. * => *:*:*:*,*:*:*:*

匹配所有Challenge.

  1. 127.0.0.1:22 => *:*:*:*,*:*:127.0.0.1:22

匹配Destination.Host为127.0.0.1, Destination.Port为22.

  1. *:socks5:*:*,* => *:socks5:*:*,*:*:*:*

匹配Source.Network为socks5.

  1. 192.168.1.0/24:* => *:*:*:*,*:*:192.168.1.0/24:*

匹配Destination.Host为192.168.1.0/24.

常见问题

Transport无法创建

由于Transport是采用WebRTC协议, 所以在创建Transport会受到WebRTC条件限制.

所以暂时有些网络情况是无法正常使用Meepo服务. 后期会提供其他解决方案来解决这个问题.

Windows平台下, Daemon模式无法正常工作

Windows平台暂时不支持Daemon模式. --daemon参数会被忽略.

为Meepo做贡献

Meepo是一个免费且开源的项目, 欢迎任何人为其开发和进步贡献力量.

  • 如果有不错的想法, 不妨通过Telegram或issues联系.
  • 在使用过程中出现任何问题, 可以通过issues来反馈.
  • 在使用过程中出现任何问题, 也可以通过Telegram来沟通使用心得.
  • 如果还有其他方面的问题与合作, 欢迎联系 pppeerxu@gmail.com .

代码提交

  • main分支仅作用于稳定版本的发布, PRs请提交到dev分支.
  • Bug修复可以直接提交PR到dev分支.
  • 如果有新增功能的想法, 可以先到issues描述想法与对应的实现, 然后fork修改, 最后提交PR到dev分支进行合并.

捐赠

如果觉得Meepo能够帮助到你, 欢迎提供适当的捐助来维持项目的长期发展.

Telegram

https://t.me/meepoDiscussion

BTC

BTC

36PnaXCMCtKLbkzVyfrkudhU6u8vjbfax4

ETH

ETH

0xa4f00EdD5fA66EEC124ab0529cF35a64Ee94BFDE

贡献者

PeerXu (pppeerxu@gmail.com)

License

MIT