diff --git a/INSTALL.md b/INSTALL.md index 165d5e4..8a33a00 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,32 @@ # Installation & Usage Guide +## TLDR + +If you never deployed a CTFd instance before: + +```sh +curl -fsSL https://get.docker.com -o get-docker.sh +sh get-docker.sh +docker swarm init +docker node update --label-add='name=linux-1' $(docker node ls -q) + +git clone https://github.com/CTFd/CTFd --depth=1 +git clone https://github.com/frankli0324/ctfd-whale CTFd/CTFd/plugins/ctfd-whale --depth=1 +curl -fsSL https://cdn.jsdelivr.net/gh/frankli0324/ctfd-whale/docker-compose.example.yml -o CTFd/docker-compose.yml + +# make sure you have pip3 installed on your rig +pip3 install docker-compose +docker-compose -f CTFd/docker-compose.yml up -d +# wait till the containers are ready +docker-compose -f CTFd/docker-compose.yml exec ctfd python manage.py set_config whale:auto_connect_network +``` + +The commands above tries to install `docker-ce`,`python3-pip` and `docker-compose`. Make sure the following requirements are satisfied before you execute them: + +* have `curl`, `git`, `python3` and `pip` installed +* GitHub is reachable +* Docker Registry is reachable + ## Installation ### Start from scratch @@ -13,6 +40,8 @@ docker swarm init docker node update --label-add "name=linux-1" $(docker node ls -q) ``` +Taken advantage of the orchestration ability of `docker swarm`, `ctfd-whale` is able to distribute challenge containers to different nodes(machines). Each time a user request for a challenge container, `ctfd-whale` will randomly pick a suitable node for running the container. + After initializing a swarm, make sure that CTFd runs as expected on your PC/server Note that the included compose file in CTFd 2.5.0+ starts an nginx container by default, which takes the http/80 port. make sure there's no conflicts. @@ -65,6 +94,7 @@ networks: ipam: config: - subnet: 172.1.0.0/16 +``` Create a folder in `conf/` called `frp` @@ -161,9 +191,8 @@ CTFd/ After finishing everything above: - -- map docker socket into CTFd container -- Attach CTFd container to frp_connect +* map docker socket into CTFd container +* Attach CTFd container to frp_connect ```yml services: @@ -200,12 +229,12 @@ docker network ls -f "label=com.docker.compose.project=ctfd" --format "{{.Name}} #### frp related configs -- `HTTP Domain Suffix` should be consistent with `subdomain_host` in frps -- `HTTP Port` with `vhost_http_port` in frps -- `Direct IP Address` should be a hostname/ip address that can be used to access frps -- `Direct Minimum Port` and `Direct Maximum Port`, you know what to do -- as long as `API URL` is filled in correctly, Whale will read the config of the connected frpc into `Frpc config template` -- setting `Frpc config template` will override contents in `frpc.ini` +* `HTTP Domain Suffix` should be consistent with `subdomain_host` in frps +* `HTTP Port` with `vhost_http_port` in frps +* `Direct IP Address` should be a hostname/ip address that can be used to access frps +* `Direct Minimum Port` and `Direct Maximum Port`, you know what to do +* as long as `API URL` is filled in correctly, Whale will read the config of the connected frpc into `Frpc config template` +* setting `Frpc config template` will override contents in `frpc.ini` Whale should be kinda usable at this moment. @@ -217,8 +246,8 @@ remove the port mapping rule for frps vhost http port(8001) in the compose file If you wnat to go deeper: -- add nginx to `default` and `internal` network -- remove CTFd from `default` and remove the mapped 8000 port +* add nginx to `default` and `internal` network +* remove CTFd from `default` and remove the mapped 8000 port add following server block to `./conf/nginx/nginx.conf`: @@ -245,8 +274,8 @@ Take a look at In one word, a `FLAG` variable will be passed into the container when it's started. You should write your own startup script (usually with bash and sed) to: -- replace your flag with the generated flag -- remove or override the `FLAG` variable +* replace your flag with the generated flag +* remove or override the `FLAG` variable PLEASE create challenge images with care. @@ -266,6 +295,6 @@ see how grouped containers are created in the [code](utils/docker.py#L58) ## Security -- Please do not allow untrusted people to access the admin account. Theoretically there's an SSTI vulnerability in the config page. -- Do not set bind_addr of the frpc to `0.0.0.0` if you are following this guide. This may enable contestants to override frpc configurations. -- If you are annoyed by the complicated configuration, and you just want to set bind_addr = 0.0.0.0, remember to enable Basic Auth included in frpc, and set API URL accordingly, for example, `http://username:password@frpc:7400` +* Please do not allow untrusted people to access the admin account. Theoretically there's an SSTI vulnerability in the config page. +* Do not set bind_addr of the frpc to `0.0.0.0` if you are following this guide. This may enable contestants to override frpc configurations. +* If you are annoyed by the complicated configuration, and you just want to set bind_addr = 0.0.0.0, remember to enable Basic Auth included in frpc, and set API URL accordingly, for example, `http://username:password@frpc:7400` diff --git a/INSTALL.zh-cn.md b/INSTALL.zh-cn.md index 401cff9..cb2bd67 100644 --- a/INSTALL.zh-cn.md +++ b/INSTALL.zh-cn.md @@ -1,6 +1,34 @@ # 使用指南 -## 安装 +## TLDR + +如果你从未部署过CTFd,你可以通过执行: + +```sh +curl -fsSL https://get.docker.com -o get-docker.sh +sh get-docker.sh --mirror Aliyun +docker swarm init +docker node update --label-add='name=linux-1' $(docker node ls -q) + +git clone https://github.com/CTFd/CTFd --depth=1 +git clone https://github.com/frankli0324/ctfd-whale CTFd/CTFd/plugins/ctfd-whale --depth=1 +curl -fsSL https://cdn.jsdelivr.net/gh/frankli0324/ctfd-whale/docker-compose.example.yml -o CTFd/docker-compose.yml + +# make sure you have pip3 installed on your rig +pip3 install docker-compose +docker-compose -f CTFd/docker-compose.yml up -d +docker-compose -f CTFd/docker-compose.yml exec ctfd python manage.py +``` + +脚本会在一台Linux机器上安装 ***docker.com版本的*** `docker-ce`,`python3-pip` 以及 `docker-compose`,请确保执行上述代码之前: + +* 安装好curl,git,python3以及pip +* 网络环境良好,能正常从GitHub克隆仓库 +* 网络环境良好,能正常从Docker Registry拖取镜像 + +## 手动安装 + +为了更好地理解ctfd-whale各个组件的作用,更充分地利用ctfd-whale,在真实使用ctfd-whale时建议用户手动、完整地从空白CTFd开始搭建一个实例。下面本文将引导你完成整个流程。 ### 从零开始 @@ -13,7 +41,9 @@ docker swarm init docker node update --label-add "name=linux-1" $(docker node ls -q) ``` -然后先确保CTFd可以正常运行。 +`ctfd-whale`利用`docker swarm`的集群管理能力,能够将题目容器分发到不同的节点上运行。选手每次请求启动题目容器时,`ctfd-whale`都将随机选择一个合适的节点运行这个题目容器。 + +然后,我们需要确保CTFd可以正常运行。 注意,2.5.0+版本CTFd的 `docker-compose.yml` 中包含了一个 `nginx` 反代,占用了80端口 @@ -195,12 +225,12 @@ docker network ls -f "label=com.docker.compose.project=ctfd" --format "{{.Name}} 然后检查frp配置项是否正确 -- `HTTP Domain Suffix` 与 frps 的 `subdomain_host` 保持一致 -- `HTTP Port` 与 frps 的 `vhost_http_port` 保持一致 -- `Direct IP Address` 为能访问到 frps 相应端口(例子中为10000-10100) 的IP -- `Direct Minimum Port` 与 `Direct Maximum Port` 显然可得 -- 只要正确填写了 `API URL` ,Whale 会自动获取 frpc 的配置文件作为 `Frpc config template` -- 通过设置 `Frpc config template` 可以覆盖原有 `frpc.ini` 文件 +* `HTTP Domain Suffix` 与 frps 的 `subdomain_host` 保持一致 +* `HTTP Port` 与 frps 的 `vhost_http_port` 保持一致 +* `Direct IP Address` 为能访问到 frps 相应端口(例子中为10000-10100) 的IP +* `Direct Minimum Port` 与 `Direct Maximum Port` 显然可得 +* 只要正确填写了 `API URL` ,Whale 会自动获取 frpc 的配置文件作为 `Frpc config template` +* 通过设置 `Frpc config template` 可以覆盖原有 `frpc.ini` 文件 至此,CTFd-Whale 已经马马虎虎可以正常使用了。 @@ -211,8 +241,8 @@ docker network ls -f "label=com.docker.compose.project=ctfd" --format "{{.Name}} 首先去除docker-compose.yml中对frps http端口的映射(8001) 如果想贯彻到底的话,可以 -- 为nginx添加internal与default两个network -- 去除CTFd的default network,并去除ports项 +* 为nginx添加internal与default两个network +* 去除CTFd的default network,并去除ports项 在 `./conf/nginx/nginx.conf` 的http block中添加以下server block @@ -272,6 +302,6 @@ ENV METHOD=aes-256-cfb ## 安全事项 -- 后台配置中flag与domain模版理论上存在ssti(feature),请不要将管理员账号给不可信第三方 -- 由于例子中frpc并没有开启鉴权,请不要将frpc的bind_addr设置为`0.0.0.0`。这样会导致利用任何一道能发起http请求的题目都能修改frpc配置。 -- 如果出于配置复杂性考虑,题目容器能够访问frpc,请开启frpc的Basic Auth,并以 `http://username:password@frpc:7400` 的格式设置frpc API URL +* 后台配置中flag与domain模版理论上存在ssti(feature),请不要将管理员账号给不可信第三方 +* 由于例子中frpc并没有开启鉴权,请不要将frpc的bind_addr设置为`0.0.0.0`。这样会导致利用任何一道能发起http请求的题目都能修改frpc配置。 +* 如果出于配置复杂性考虑,题目容器能够访问frpc,请开启frpc的Basic Auth,并以 `http://username:password@frpc:7400` 的格式设置frpc API URL