Skip to content

Commit f251d7d

Browse files
HouzuoGuoHouzuoGuo
committed
sync doc with wiki
1 parent 50b3cd5 commit f251d7d

5 files changed

+175
-13
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ software, please file an [issue](https://github.com/HouzuoGuo/laitos/issues).
4646

4747
I'd love to hear from your feedback, feel free to
4848
[Email me](mailto:[email protected]), get in touch on
49-
[Twitter](https://twitter.com/hzguo), and visit my home page
49+
[X (Twitter)](https://x.com/hzguo), and visit my home page
5050
[hz.gl](https://hz.gl).
5151

5252
This is not an officially supported Google product.

‎doc/Home.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ software, please file an [issue](https://github.com/HouzuoGuo/laitos/issues).
4646

4747
I'd love to hear from your feedback, feel free to
4848
[Email me](mailto:[email protected]), get in touch on
49-
[Twitter](https://twitter.com/hzguo), and visit my home page
49+
[X (Twitter)](https://x.com/hzguo), and visit my home page
5050
[hz.gl](https://hz.gl).
5151

5252
This is not an officially supported Google product.

‎doc/[Daemon]-DNS-server.md

+97-3
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ The DNS server daemon simultaneously serves as:
55
- An authoritative DNS server for configured domain names (`MyDomainNames`),
66
responding to SOA, NS, MX, and address queries. MX and address responses point
77
to the server's own public IP.
8+
- An authoritative DNS server for predefined custom records on any domain name.
89
- A stub resolver that blocks advertising and malicious domains for home
910
networks (`AllowQueryFromCidrs`).
1011
- Handle TXT queries as the [carrier of app command invocation](<https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-DNS-server-(invoke-app-commands)>).
@@ -42,9 +43,9 @@ JSON config file:
4243
<td>MyDomainNames</td>
4344
<td>array of strings</td>
4445
<td>
45-
The laitos DNS server's own domain names.
46+
Define the DNS server's own domain names.
4647
<br />
47-
The DNS server gives authoritative responses to SOA, NS, MX, A queries of these domain names.
48+
The DNS server will automatically respond to SOA, NS, MX, and address queries for these domains with its own server IP.
4849
<br />
4950
This is also used by <a href="https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-DNS-server-(invoke-app-commands)">DNS server (invoke app commands)</a>
5051
and <a href="https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-DNS-server-(TCP-over-DNS)">DNS server (TCP over DNS)</a>
@@ -122,13 +123,106 @@ Here is a minimal JSON config file example:
122123
}
123124
</pre>
124125

126+
### Define custom DNS records
127+
128+
In addition to blocking ads, the DNS server also responds to predefined custom
129+
records, which is useful for hosting a personal website.
130+
131+
The custom records may be defined on any domain name regardless of the `MyDomainNames` value.
132+
133+
Under `DNSDaemon`, add a new JSON object `CustomRecords`. Populate the keys with
134+
record names (FQDN e.g. `myhost.example.com`), and define the records for each key:
135+
136+
<table>
137+
<tr>
138+
<th>Property</th>
139+
<th>Type</th>
140+
<th>Meaning</th>
141+
<th>Default value</th>
142+
</tr>
143+
<tr>
144+
<td>A</td>
145+
<td>JSON object {"Addresses": ["1.1.1.1", "2.2.2.2", ...]} or {"CanonicalName": "foo.example.com"}</td>
146+
<td>Respond to the query with the IPv4 addresses or the canonical name.</td>
147+
<td>Empty</td>
148+
</tr>
149+
<tr>
150+
<td>AAAA</td>
151+
<td>JSON object {"Addresses": ["1.1.1.1", "2.2.2.2", ...]} or {"CanonicalName": "foo.example.com"}</td>
152+
<td>Respond to the query with the IPv6 addresses or the canonical name.</td>
153+
<td>Empty</td>
154+
</tr>
155+
<tr>
156+
<td>TXT</td>
157+
<td>JSON object {"Entries": ["text1", "text2", ...]}</td>
158+
<td>
159+
Respond to the query with the text entries.
160+
Do not put extra double quotes in each text, the DNS server will add the
161+
double quotes automatically when needed.
162+
</td>
163+
<td>Empty</td>
164+
</tr>
165+
<tr>
166+
<td>MX</td>
167+
<td>Array of objects [{"Host": "mx1.example.com", "Pref": 1}, {"Host": "mx2.example.com", "Pref": 2}, ...]</td>
168+
<td> Respond to the query with the mail exchange records.</td>
169+
<td>Empty</td>
170+
</tr>
171+
<tr>
172+
<td>NS</td>
173+
<td>JSON object {"Names": ["ns1.example.com", "ns2.example.com", ...]}</td>
174+
<td> Respond to the query with the name server records.</td>
175+
<td>Empty</td>
176+
</tr>
177+
</table>
178+
179+
Here is a minimal example:
180+
181+
<pre>
182+
{
183+
...
184+
185+
"DNSDaemon": {
186+
"AllowQueryFromCidrs": ["35.196.0.0/16", "37.228.0.0/16"],
187+
"CustomRecords": {
188+
"altn.example.com": {
189+
"A": {
190+
"Addresses": ["1.1.1.1", "2.2.2.2"]
191+
},
192+
"TXT": {
193+
"Entries": [
194+
"v=spf1 mx a mx:mx1.altn.example.com mx:mx2.altn.example.com ?all",
195+
"google-site-verification=xxxx_yyyy",
196+
]
197+
},
198+
"MX":[
199+
{"Host":"mx1.altn.example.com", "Pref": 1},
200+
{"Host":"mx2.altn.example.com", "Pref": 2}
201+
],
202+
"NS": {
203+
"Names": ["ns1.altn.example.com", "ns2.altn.example.com"]
204+
}
205+
},
206+
"mx1.altn.example.com": {
207+
"A": {"CanonicalName": "mx2.altn.example.com"}
208+
},
209+
"mx2.altn.example.com": {
210+
"AAAA": ["2900:4b11:d822:4f33:6844:fe55:cb66:6777"]
211+
}
212+
}
213+
},
214+
215+
...
216+
}
217+
</pre>
218+
125219
### Configuration tips
126220

127221
Instead of manually figure out your home public IP and placing it into `AllowQueryFromCidrs`,
128222
run [phone-home telemetry daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-phone-home-telemetry)
129223
on a computer inside that network (e.g. on a laptop or desktop) and configure
130224
the daemon to send reports to this laitos server. All telemetry subjects
131-
are automatically allowed to use the DNS server without restrictions.
225+
are automatically allowed to query the DNS server.
132226

133227
## Run
134228

‎doc/[Daemon]-system-maintenance.md

+51
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ System maintenance tasks comprise:
2323
journal.
2424
- Synchronise system clock.
2525
- On Windows, verify and maintain system files integrity with `DISM` and `SFC`.
26+
- Discard older systemd journal content to conserve disk space.
2627
- Set Linux system time zone (additional configuration required).
2728

2829
(Miscellaneous)
@@ -158,7 +159,57 @@ laitos works with the following system package managers for installing and updat
158159
<td>(Not used)</td>
159160
<td>Universal</td>
160161
</tr>
162+
<tr>
163+
<td>RegisterPrometheusMetrics</td>
164+
<td>true/false</td>
165+
<td>
166+
Record the process statistics (e.g. CPU time & context switches) in promehteus metrics.
167+
<br />
168+
The metrics are served by <a href="https://github.com/HouzuoGuo/laitos/wiki/%5BWeb-service%5D-prometheus-metrics-exporter">prometheus metrics exporter web handler</a>.
169+
</td>
170+
<td>(Not enabled)</td>
171+
<td>Linux</td>
172+
</tr>
173+
<tr>
174+
<td>RegsiterProcessActivityMetrics</td>
175+
<td>true/false</td>
176+
<td>
177+
Record the laitos process file and network activities in prometheus metrics.
178+
This requires "bpftrace" and requires an additional 100 MB of system memory.
179+
<br />
180+
The metrics are served by <a href="https://github.com/HouzuoGuo/laitos/wiki/%5BWeb-service%5D-prometheus-metrics-exporter">prometheus metrics exporter web handler</a>.
181+
</td>
182+
<td>(Not enabled)</td>
183+
<td>Linux</td>
184+
</tr>
185+
<tr>
186+
<td>RegsiterSystemActivityMetrics</td>
187+
<td>true/false</td>
188+
<td>
189+
Record the system-wide file and network activities in prometheus metrics.
190+
This requires "bpftrace" and requires an additional 500 - 1000 MB of system memory.
191+
<br />
192+
The metrics are served by <a href="https://github.com/HouzuoGuo/laitos/wiki/%5BWeb-service%5D-prometheus-metrics-exporter">prometheus metrics exporter web handler</a>.
193+
</td>
194+
<td>(Not enabled)</td>
195+
<td>Linux</td>
196+
</tr>
197+
<tr>
198+
<td>PrometheusScrapeIntervalSec</td>
199+
<td>integer</td>
200+
<td>The scrape interval expected from prometheus, measured in seconds. This is used to determine the sampling period of certain gauges.</td>
201+
<td>60 (seconds)</td>
202+
<td>Universal</td>
203+
</tr>
204+
<tr>
205+
<td>ShrinkSystemdJournalSizeMB</td>
206+
<td>integer</td>
207+
<td>Retain this much system journal (measured in MB) and discard the older content to conserve disk space.</td>
208+
<td>(Not enabled)</td>
209+
<td>Linux</td>
210+
</tr>
161211
</table>
212+
162213
2. Follow [outgoing mail configuration](https://github.com/HouzuoGuo/laitos/wiki/Outgoing-mail-configuration).
163214

164215
Here is an example configuration that keeps system up-to-date, while also checking whether mail(25), DNS(53), and HTTP(80, 443) daemons are online:

‎doc/[Web-service]-prometheus-metrics-exporter.md

+25-8
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,30 @@ information collected from the following sources in the prometheus-exporter form
77
- All web proxy requests: time to first byte, connection duration, size of response.
88

99
## Configuration
10+
1011
Under the JSON key `HTTPHandlers`, add a string property called `PrometheusMetricsEndpoint`, value being the URL location of the service.
12+
Keep the location a secret to yourself and make it difficult to guess.
13+
14+
Check out the additional process and system activity metrics available from the [system maintenance](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-system-maintenance) daemon,
15+
enable them as you wish.
1116

12-
Keep the location a secret to yourself and make it difficult to guess. Here is an example:
17+
Here is an example:
1318
<pre>
1419
{
1520
...
1621

22+
"Maintenance": {
23+
...
24+
"PrometheusScrapeIntervalSec": 60,
25+
"RegsiterSystemActivityMetrics": true,
26+
"RegsiterProcessActivityMetrics": true,
27+
"RegisterPrometheusMetrics": true,
28+
...
29+
},
30+
1731
"HTTPHandlers": {
1832
...
19-
2033
"PrometheusMetricsEndpoint": "/my-precious-metrics",
21-
2234
...
2335
},
2436

@@ -36,13 +48,18 @@ The exporter is hosted by web server, therefore remember to [run web server](htt
3648

3749
## Usage
3850

39-
There are three categories of performance metrics exported by this web service:
51+
The prometheus web handler serves all of these metrics:
52+
4053
- [Web server (httpd and insecurehttpd)](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-web-server) statistics are always included, such as
4154
individual handler's processing duration, response size, time-to-first-byte, etc.
42-
- When you enable the [web proxy daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-web-proxy), the exporter will automatically include
55+
- If [web proxy daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-web-proxy) is enabled, the exporter will automatically include
4356
statistics such as data transfer per proxy destination, number of connections, connection duration, etc.
44-
- When you enable the [maintenance daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-system-maintenance), the exporter will automatically
45-
include laitos program's process statistics such as CPU usage and scheduler performance. These stats rely on Linux (`procfs`).
57+
- If [maintenance daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-system-maintenance) `RegisterPrometheusMetrics` is enabled,
58+
the exporter will automatically include laitos program's process statistics such as CPU usage and scheduler performance. This relies on Linux (`procfs`).
59+
- If [maintenance daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-system-maintenance) `RegsiterProcessActivityMetrics` is enabled,
60+
the exporter will automatically include the file and network activities of the laitos process. This relies on `bpftrace` tool.
61+
- If [maintenance daemon](https://github.com/HouzuoGuo/laitos/wiki/%5BDaemon%5D-system-maintenance) `RegsiterSystemActivityMetrics` is enabled,
62+
the exporter will automatically include the system-wide file and network activities. This relies on `bpftrace` tool.
4663

4764
Next, follow the installation instructions of [prometheus](https://prometheus.io/docs/prometheus/latest/installation/) to install and start the
4865
prometheus daemon. Feel free to run the daemon on a home desktop, a dedicated server, or on the same computer that runs laitos.
@@ -54,7 +71,7 @@ the web service's endpoint:
5471
...
5572
scrape_configs:
5673
- job_name: 'laitos'
57-
scrape_interval: 20s
74+
scrape_interval: 60s # set to the same value as the system maintenance daemon's PrometheusScrapeIntervalSec
5875
scrape_timeout: 5s
5976
scheme: https # or https
6077
metrics_path: '/my-precious-metrics'

0 commit comments

Comments
 (0)