From e13eaeff163f71156759eb564edb255b48bc0d0c Mon Sep 17 00:00:00 2001 From: Yegor S Date: Tue, 11 Mar 2025 17:55:58 -0400 Subject: [PATCH] Updated Troubleshooting Guide (markdown) --- Troubleshooting-Guide.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/Troubleshooting-Guide.md b/Troubleshooting-Guide.md index 22a6e26..9644e29 100644 --- a/Troubleshooting-Guide.md +++ b/Troubleshooting-Guide.md @@ -207,13 +207,31 @@ nvram show | grep dnsmasq_ ``` ## Debug launch -If the service doesn't start, or hangs, try running it in debug mode and collect a log. This can be done using the following command: +If the service doesn't start, or hangs, or not enforcing your rules as you'd expect - try running it in debug mode and collect a log. This can be done using the following command: ``` ctrld start --log /tmp/ctrld.log -vv ``` -The log file will contain verbose debug level data. Alternatively, if you're using v1.4.0 or higher you can simply run `ctrld log send` command which will send the runtime log from the application directly to us, assuming you are running ctrld in default mode. +The log file will contain verbose debug level data. Alternatively, if you're using v1.4.0 or higher you can simply run `ctrld log send` command which will send the runtime log from the application directly to us, assuming you are running ctrld in default mode. You can also run `ctrld log view` command to view the logs in your console. -Open an issue with this data, and everything you collected above. +### Rule Matching +If you're troubleshooting issues related to enforcing, or rather not enforcing your policies, run the app in debug mode and look for logs like this: + +``` +{"level":"info","time":"2025-03-11T17:47:58-04:00.479","message":"[01021f] QUERY: 172.17.15.216:52805 (Not-Home) -> listener.0: A popads.net"} +{"level":"debug","time":"2025-03-11T17:47:58-04:00.479","message":"[01021f] no explicit policy matched, using default routing -> [upstream.0]"} +{"level":"debug","time":"2025-03-11T17:47:58-04:00.479","message":"[01021f] including client info with the request"} +{"level":"debug","time":"2025-03-11T17:47:58-04:00.479","message":"[01021f] sending query to upstream.0: "} +{"level":"debug","time":"2025-03-11T17:47:58-04:00.479","message":"[01021f] sending request header: map[X-Cd-Host:[Not-Home] X-Cd-Ip:[172.17.15.216] X-Cd-Mac:[00:15:5d:f9:b3:10] X-Cd-Os:[3-1-Ubuntu 22.04.4 LTS]]"} +{"level":"info","time":"2025-03-11T17:47:58-04:00.541","message":"[01021f] REPLY: upstream.0 -> 172.17.15.216:52805 (Not-Home): NOERROR"} +{"level":"debug","time":"2025-03-11T17:47:58-04:00.541","message":"[01021f] received response of 67 bytes in 61.8454ms"} +``` + +Let's break it down line by line: +- First line shows that a query arrived from `172.17.15.216` and this host wanted to resolve `popads.net` using `listener.0` +- Second line shows what policy, if any, was matched. In this case, no rule was matched so we used default routing and sent the request to a matching upstream number (`listener.0` -> `upstream.0`). +- Third and fourth line mention that metadata is included with the request, which is sent to `upstream.0` +- Fifth line shows you what the included metadata was, as discovered by `ctrld` +- Sixth and seventh line shows that a valid response was received (`NOERROR`), how much data it was, and how long it took