README.md
1Flamethrower [](https://travis-ci.org/DNS-OARC/flamethrower)
2============
3> This project is in [active development](https://github.com/ns1/community/blob/master/project_status/ACTIVE_DEVELOPMENT.md).
4
5A DNS performance and functional testing utility.
6
72017-2020© NSONE, Inc.
8
9Overview
10--------
11
12Flamethrower is a small, fast, configurable tool for functional testing, benchmarking, and stress testing DNS servers and networks. It supports IPv4, IPv6, UDP, TCP, DoT, and DoH and has a modular system for generating queries used in the tests.
13
14Originally built as an alternative to [dnsperf](https://github.com/DNS-OARC/dnsperf), many of the command line options are compatible.
15
16Getting Started
17---------------
18
19The easiest way to get started with Flamethrower is to use the [public docker image](https://hub.docker.com/repository/docker/ns1labs/flame):
20```
21docker pull ns1labs/flame
22docker run ns1labs/flame --help
23```
24
25There are currently no prebuilt operating system packages. If you would like to build your own executable,
26please see the Build section below.
27
28Usage
29-----
30
31Current command line options are described with:
32
33```
34flame --help
35```
36
37Quick Examples
38--------
39
40Flame localhost port 53, UDP, maximum speed:
41```
42flame localhost
43```
44
45Flame target, port 5300, TCP:
46```
47flame -p 5300 -P tcp target.test.com
48```
49
50Flame target, port 443, DoT:
51```
52flame -p 443 -P dot target.test.com
53```
54
55Flame target, DNS over HTTPS GET:
56```
57flame -P doh target.test.com/dns-query
58```
59
60Flame target, DNS over HTTPS POST:
61```
62flame -P doh -M POST target.test.com/dns-query
63```
64
65Flame target with random labels:
66```
67flame target.test.com -g randomlabel lblsize=10 lblcount=4 count=1000
68```
69
70Flame multiple target at once, reading the list from a file:
71```
72flame file --targets myresolvers.txt
73```
74
75Detailed Features
76-----------------
77
78### Query Generators
79
80 Flamethrower uses a modular system for generating queries. Most modules generate all queries before sending begins, for performance reasons.
81 Each module may include its own list of configuration options which can be set via key/value pairs on the command line.
82 See full `--help` for the current list of generators and their options.
83
84### Rate Limiting
85
86 By default, Flamethrower will send traffic as fast as possible. To limit to a specific overall queries per second, use `-Q`
87
88### Dynamic QPS Flow
89
90 Flamethrower can adjust its QPS flow over time. This is useful for generating a "signal" of traffic (e.g. a square wave) for calibrating metrics collection. For example, to send 10 QPS for 120000ms, then 80 QPS for 120000ms, etc use `--qps-flow "10,120000;80,120000;10,120000;"`. Flow change will not loop, you should list as many changes as necessary. Once the flow reaches the final QPS number, it will hold it until program termination.
91
92### Output Metrics
93
94 Flamethrower can generate detailed metrics for each of its concurrent senders. Metrics include send and receive counts, timeouts, min, max and average latency, errors, and the like. The output format is JSON, and is suitable for ingestion into databases such as Elastic for further processing or visualization. See the `-o` flag.
95
96### Concurrency
97
98 Flamethrower is single threaded, async i/o. You specify the amount of concurrent senders with the `-c` option. Each of these senders will send a configurable number of consecutive queries (see `-q`), then enter a configurable delay period (see `-d`) before looping.
99
100 Each concurrent sender will pull the next query from the total queries generated by the Query Generator, looping once it reaches the end of the query list (if the program is configured to continue).
101
102 There is currently no built-in support for multiprocess sending, so the maximum throughput will be reached once a single CPU is saturated. However, you may manually start several concurrent `flame` processes, including up to 1 per CPU available. There is future planned support for builtin multiprocess sending.
103
104Build Dependencies
105------------------
106
107* CMake >= 3.8
108* Linux or OSX
109* libuv >= 1.23.0
110* libldns >= 1.7.0
111* gnutls >= 3.3
112* C++ compiler supporting C++17
113
114Optional DoH support requires:
115* nghttp2
116
117Building
118--------
119
120Building is based on CMake.
121
122Default build:
123```
124mkdir build; cd build
125cmake ..
126make
127```
128
129To build with DoH support:
130```
131mkdir build; cd build
132cmake -DDOH_ENABLE=ON ..
133make
134```
135
136Building the docker image:
137```
138org="myorg"
139image="myflame"
140tag="latest"
141docker build --network host -t ${org}/${image}:${tag} -f Dockerfile .
142docker run --rm -it --net host ${org}/${image}:${tag} --help
143```
144
145Contributions
146---
147Pull Requests and issues are welcome. See the [NS1 Contribution Guidelines](https://github.com/ns1/community) for more information.
148
149License
150-------
151This code is released under Apache License 2.0. You can find terms and conditions in the LICENSE file.
152
153
){kind=link}