Fork project
This commit is contained in:
304
docs/install.md
Normal file
304
docs/install.md
Normal file
@ -0,0 +1,304 @@
|
||||
# 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
|
||||
|
||||
First of all, you should initialize a docker swarm and label the nodes
|
||||
|
||||
names of nodes running linux/windows should begin with `linux/windows-*`
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/CTFd/CTFd --depth=1
|
||||
cd CTFd # the cwd will not change throughout this guide from this line on
|
||||
```
|
||||
|
||||
Change the first line of `docker-compose.yml` to support `attachable` property
|
||||
|
||||
`version '2'` -> `version '3'`
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
take a look at <http://localhost>(or port 8000) and setup CTFd
|
||||
|
||||
### Configure frps
|
||||
|
||||
frps could be started by docker-compose along with CTFd
|
||||
|
||||
define a network for communication between frpc and frps, and create a frps service block
|
||||
|
||||
```yml
|
||||
services:
|
||||
...
|
||||
frps:
|
||||
image: glzjin/frp
|
||||
restart: always
|
||||
volumes:
|
||||
- ./conf/frp:/conf
|
||||
entrypoint:
|
||||
- /usr/local/bin/frps
|
||||
- -c
|
||||
- /conf/frps.ini
|
||||
ports:
|
||||
- 10000-10100:10000-10100 # for "direct" challenges
|
||||
- 8001:8001 # for "http" challenges
|
||||
networks:
|
||||
default: # frps ports should be mapped to host
|
||||
frp_connect:
|
||||
|
||||
networks:
|
||||
...
|
||||
frp_connect:
|
||||
driver: overlay
|
||||
internal: true
|
||||
ipam:
|
||||
config:
|
||||
- subnet: 172.1.0.0/16
|
||||
```
|
||||
|
||||
Create a folder in `conf/` called `frp`
|
||||
|
||||
```bash
|
||||
mkdir ./conf/frp
|
||||
```
|
||||
|
||||
then create a configuration file for frps `./conf/frp/frps.ini`, and fill it with:
|
||||
|
||||
```ini
|
||||
[common]
|
||||
# following ports must not overlap with "direct" port range defined in the compose file
|
||||
bind_port = 7987 # port for frpc to connect to
|
||||
vhost_http_port = 8001 # port for mapping http challenges
|
||||
token = your_token
|
||||
subdomain_host = node3.buuoj.cn
|
||||
# hostname that's mapped to frps by some reverse proxy (or IS frps itself)
|
||||
```
|
||||
|
||||
### Configure frpc
|
||||
|
||||
Likewise, create a network and a service for frpc
|
||||
|
||||
the network allows challenges to be accessed by frpc
|
||||
|
||||
```yml
|
||||
services:
|
||||
...
|
||||
frpc:
|
||||
image: glzjin/frp:latest
|
||||
restart: always
|
||||
volumes:
|
||||
- ./conf/frp:/conf/
|
||||
entrypoint:
|
||||
- /usr/local/bin/frpc
|
||||
- -c
|
||||
- /conf/frpc.ini
|
||||
depends_on:
|
||||
- frps #need frps to run first
|
||||
networks:
|
||||
frp_containers:
|
||||
frp_connect:
|
||||
ipv4_address: 172.1.0.3
|
||||
|
||||
networks:
|
||||
...
|
||||
frp_containers: # challenge containers are attached to this network
|
||||
driver: overlay
|
||||
internal: true
|
||||
# if challenge containers are allowed to access the internet, remove this line
|
||||
attachable: true
|
||||
ipam:
|
||||
config:
|
||||
- subnet: 172.2.0.0/16
|
||||
```
|
||||
|
||||
Likewise, create an frpc config file `./conf/frp/frpc.ini`
|
||||
|
||||
```ini
|
||||
[common]
|
||||
token = your_token
|
||||
server_addr = frps
|
||||
server_port = 7897 # == frps.bind_port
|
||||
admin_addr = 172.1.0.3 # refer to "Security"
|
||||
admin_port = 7400
|
||||
```
|
||||
|
||||
### Verify frp configurations
|
||||
|
||||
update compose stack with `docker-compose up -d`
|
||||
|
||||
by executing `docker-compose logs frpc`, you should see that frpc produced following logs:
|
||||
|
||||
```log
|
||||
[service.go:224] login to server success, get run id [******], server udp port [******]
|
||||
[service.go:109] admin server listen on ******
|
||||
```
|
||||
|
||||
by seeing this, you can confirm that frpc/frps is set up correctly.
|
||||
|
||||
Note: folder layout in this guide:
|
||||
|
||||
```
|
||||
CTFd/
|
||||
conf/
|
||||
nginx/ # included in CTFd 2.5.0+
|
||||
frp/
|
||||
frpc.ini
|
||||
frps.ini
|
||||
serve.py <- this is just an anchor
|
||||
```
|
||||
|
||||
### Configure CTFd
|
||||
|
||||
After finishing everything above:
|
||||
|
||||
* map docker socket into CTFd container
|
||||
* Attach CTFd container to frp_connect
|
||||
|
||||
```yml
|
||||
services:
|
||||
ctfd:
|
||||
...
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
depends_on:
|
||||
- frpc #need frpc to run ahead
|
||||
networks:
|
||||
...
|
||||
frp_connect:
|
||||
```
|
||||
|
||||
and then clone Whale into CTFd plugins directory (yes, finally)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/frankli0324/CTFd-Whale CTFd/plugins/ctfd-whale --depth=1
|
||||
docker-compose build # for pip to find requirements.txt
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
go to the Whale Configuration page (`/plugins/ctfd-whale/admin/settings`)
|
||||
|
||||
#### Docker related configs
|
||||
|
||||
`Auto Connect Network`, if you strictly followed the guide, should be `ctfd_frp_containers`
|
||||
|
||||
If you're not sure about that, this command lists all networks in the current stack
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
Whale should be kinda usable at this moment.
|
||||
|
||||
### Configure nginx
|
||||
|
||||
If you are using CTFd 2.5.0+, you can utilize the included nginx.
|
||||
|
||||
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 following server block to `./conf/nginx/nginx.conf`:
|
||||
|
||||
```conf
|
||||
server {
|
||||
listen 80;
|
||||
server_name *.node3.buuoj.cn;
|
||||
location / {
|
||||
proxy_pass http://frps:8001;
|
||||
proxy_redirect off;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Host $server_name;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Challenge Deployment
|
||||
|
||||
### Standalone Containers
|
||||
|
||||
Take a look at <https://github.com/CTFTraining>
|
||||
|
||||
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
|
||||
|
||||
PLEASE create challenge images with care.
|
||||
|
||||
### Grouped Containers
|
||||
|
||||
"name" the challenge image with a json object, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"hostname": "image",
|
||||
}
|
||||
```
|
||||
|
||||
Whale will keep the order of the keys in the json object, and take the first image as the "main container" of a challenge. The "main container" will be mapped to frp with same rules from standalone containers
|
||||
|
||||
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`
|
||||
|
||||
## Advanced Deployment
|
||||
|
||||
To separate the target server (for lunching instance) and CTFd web server with TLS secured docker API, please refer to [this document](advanced.md)
|
||||
Reference in New Issue
Block a user