dns.mitm: add documentation

docs/components/modules/ams_mitm.md

@@ -25,6 +25,12 @@ set_mitm enables intercepting requests to the system settings service. It curren
 + `ns` system module and games (to allow for overriding game locales)
 + All firmware debug settings requests (to allow modification of system settings not directly exposed to the user)
 
+## dns_mitm
+
+dns_mitm enables intercepting requests to dns resolution services, to enable redirecting requests for specified hostnames.
+
+For documentation, see [here](../../features/dns_mitm.md).
+
 ### Firmware Version
 set_mitm intercepts the `GetFirmwareVersion` command, if the requester is `qlaunch` or `maintenance`.
 It modifies the `display_version` field of the returned system version, causing the version to display

docs/features/dns_mitm.md

@@ -0,0 +1,51 @@
+# DNS.mitm
+As of 0.18.0, atmosphère provides a mechanism for redirecting DNS resolution requests.
+
+By default, atmosphère redirects resolution requests for official telemetry servers, redirecting them to a loopback address.
+
+## Hosts files
+
+DNS.mitm can be configured through the usage of a slightly-extended `hosts` file format, which is parsed only once on system startup.
+
+In particular, hosts files parsed by DNS.mitm have the following extensions to the usual format:
++ `*` is treated as a wildcard character.
++ `%` is treated as a stand-in for the value of `nsd!environment_identifier`. This is always `lp1`, on production devices.
+
+Please note that homebrew may trigger a hosts file re-parse by sending the extension IPC command 65000 ("AtmosphereReloadHostsFile") to a connected `sfdnsres` session.
+
+### Hosts file selection
+
+Atmosphère will try to read hosts from the following file paths, in order, stopping once it successfully performs a file read:
+
++ (emummc only) `/atmosphere/hosts/emummc_%04lx.txt`, formatted with the emummc's id number (see `emummc.ini`).
++ (emummc only) `/atmosphere/hosts/emummc.txt`.
++ (sysmmc only) `/atmosphere/hosts/sysmmc.txt`.
++ `/atmosphere/hosts/default.txt`
+
+If `/atmosphere/hosts/default.txt` does not exist, atmosphère will create it to contain the defaults.
+
+### Atmosphère defaults
+
+By default, atmosphère's default redirections are parsed **in addition to** the contents of the loaded hosts file.
+
+This is equivalent to thinking of the loaded hosts file as having the atmosphère defaults prepended to it.
+
+This setting is considered desirable, because it minimizes the telemetry risks if a user forgets to update a custom hosts file on a system update which changes the telemetry servers.
+
+This behavior can be opted-out from by setting `atmosphere!add_defaults_to_dns_hosts = u8!0x0` in `system_settings.ini`.
+
+The current default redirections are:
+
+```
+# Nintendo telemetry servers
+127.0.0.1 receive-%.dg.srv.nintendo.net receive-%.er.srv.nintendo.net
+```
+
+## Debugging
+
+On startup (or on hosts file re-parse), DNS.mitm will log both what hosts file it selected and the contents of all redirections it parses to `/atmosphere/logs/dns_mitm_startup.log`.
+
+In addition, if the user sets `atmosphere!enable_dns_mitm_debug_log = u8!0x1` in `system_settings.ini`, DNS.mitm will log all requests to GetHostByName/GetAddrInfo to `/atmosphere/logs/dns_mitm_debug.log`. All redirections will be noted when they occur.
+
+## Opting-out of DNS.mitm entirely
+If you wish to disable DNS.mitm entirely, `system_settings.ini` can be edited to set `atmosphere!enable_dns_mitm = u8!0x0`.

stratosphere/ams_mitm/source/dns_mitm/dnsmitm_debug.cpp

@@ -39,11 +39,14 @@ namespace ams::mitm::socket::resolver {
             g_log_enabled = enable_log;
 
             if (g_log_enabled) {
+                /* Create the logs directory. */
+                mitm::fs::CreateAtmosphereSdDirectory("/logs");
+
                 /* Create the log file. */
-                mitm::fs::CreateAtmosphereSdFile("dns_log.txt", 0, ams::fs::CreateOption_None);
+                mitm::fs::CreateAtmosphereSdFile("/logs/dns_mitm_debug.log", 0, ams::fs::CreateOption_None);
 
                 /* Open the log file. */
-                R_ABORT_UNLESS(mitm::fs::OpenAtmosphereSdFile(std::addressof(g_log_file), "dns_log.txt", ams::fs::OpenMode_ReadWrite | ams::fs::OpenMode_AllowAppend));
+                R_ABORT_UNLESS(mitm::fs::OpenAtmosphereSdFile(std::addressof(g_log_file), "/logs/dns_mitm_debug.log", ams::fs::OpenMode_ReadWrite | ams::fs::OpenMode_AllowAppend));
 
                 /* Get the current log offset. */
                 R_ABORT_UNLESS(::fsFileGetSize(std::addressof(g_log_file), std::addressof(g_log_ofs)));

stratosphere/ams_mitm/source/dns_mitm/dnsmitm_host_redirection.cpp

@@ -297,9 +297,10 @@ namespace ams::mitm::socket::resolver {
 
         /* Open log file. */
         ::FsFile log_file;
-        mitm::fs::DeleteAtmosphereSdFile("/dns_mitm_startup.log");
-        R_ABORT_UNLESS(mitm::fs::CreateAtmosphereSdFile("/dns_mitm_startup.log", 0, ams::fs::CreateOption_None));
-        R_ABORT_UNLESS(mitm::fs::OpenAtmosphereSdFile(std::addressof(log_file), "/dns_mitm_startup.log", ams::fs::OpenMode_ReadWrite | ams::fs::OpenMode_AllowAppend));
+        mitm::fs::DeleteAtmosphereSdFile("/logs/dns_mitm_startup.log");
+        mitm::fs::CreateAtmosphereSdDirectory("/logs");
+        R_ABORT_UNLESS(mitm::fs::CreateAtmosphereSdFile("/logs/dns_mitm_startup.log", 0, ams::fs::CreateOption_None));
+        R_ABORT_UNLESS(mitm::fs::OpenAtmosphereSdFile(std::addressof(log_file), "/logs/dns_mitm_startup.log", ams::fs::OpenMode_ReadWrite | ams::fs::OpenMode_AllowAppend));
         ON_SCOPE_EXIT { ::fsFileClose(std::addressof(log_file)); };
 
         Log(log_file, "DNS Mitm:\n");