Merge pull request #993 from openziti/clarify-linux-resolver-config

organize and clarify linux tunneler doc

docusaurus/docs/reference/tunnelers/60-linux/10-debian-package.mdx

@@ -5,6 +5,8 @@ sidebar_label: Debian
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import LinuxResolverConfig from '/docs/reference/tunnelers/60-linux/_resolver.mdx'
+import LinuxAddIdentities from '/docs/reference/tunnelers/60-linux/_add_identities.mdx'
 
 ### Installing the Debian Package
 
@@ -86,16 +88,6 @@ curl -sSLf https://get.openziti.io/tun/scripts/install-ubuntu.bash | bash
     sudo apt install ziti-edge-tunnel
     ```
 
-1. Replace resolveconf with systemd-resolved and delegate management of `/etc/resolv.conf` to systemd-resolved.
-
-    Debian ships without systemd-resolved, which is the only resolver that can be automatically configured by the tunnel service. You must choose between installing and enabling systemd-resolved (preferred for security and performance) or run the tunneler as root to enable legacy resolver configurations, e.g., resolveconf.
-
-    ```text
-    sudo apt install systemd-resolved
-    ```
-
-1. Reboot to ensure the new resolver configuration is in full effect.
-
 </TabItem>
 </Tabs>
 
@@ -105,4 +97,11 @@ curl -sSLf https://get.openziti.io/tun/scripts/install-ubuntu.bash | bash
     sudo systemctl enable --now ziti-edge-tunnel.service
     ```
 
-2. [Add an Identity](/reference/tunnelers/60-linux/index.mdx#adding-identities)
+2. Add an Identity.
+
+    <LinuxAddIdentities/>
+
+2. Configure the Resolver.
+
+    <LinuxResolverConfig/>
+

docusaurus/docs/reference/tunnelers/60-linux/20-redhat-package.mdx

@@ -5,6 +5,8 @@ sidebar_label: RedHat
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import LinuxResolverConfig from '/docs/reference/tunnelers/60-linux/_resolver.mdx'
+import LinuxAddIdentities from '/docs/reference/tunnelers/60-linux/_add_identities.mdx'
 
 ### Installing the RPM Package
 
@@ -89,5 +91,10 @@ repo_gpgcheck=1
     sudo systemctl enable --now ziti-edge-tunnel.service
     ```
 
-2. [Add an Identity](/reference/tunnelers/60-linux/index.mdx#adding-identities)
+2. Add an Identity.
 
+    <LinuxAddIdentities/>
+
+2. Configure the Resolver.
+
+    <LinuxResolverConfig/>

docusaurus/docs/reference/tunnelers/60-linux/30-manual-installation.mdx

@@ -3,37 +3,43 @@ title: Manual Installation
 sidebar_label: Manual
 ---
 
-## Manual Installation
+import LinuxResolverConfig from '/docs/reference/tunnelers/60-linux/_resolver.mdx'
+import LinuxAddIdentities from '/docs/reference/tunnelers/60-linux/_add_identities.mdx'
 
-[The latest binary release](https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/) of `ziti-edge-tunnel` is
+[The latest stable release](https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/) of `ziti-edge-tunnel` is
 distributed as an executable binary in GitHub.
 
 
-Unzip the downloaded file and copy the binary to a directory in your PATH, such as `/usr/local/bin`.
+1. Unzip the downloaded file and copy the binary to a directory in your PATH, such as `/usr/local/bin`.
 
-```text
-sudo install -o root -g root ./ziti-edge-tunnel /usr/local/bin/
-```
+    ```text
+    sudo install -o root -g root ./ziti-edge-tunnel /usr/local/bin/
+    ```
 
-Create a POSIX group named `ziti` if it doesn't already exist. Members of this group can access the identity files and send IPC commands to the socket server.
+1. Create a POSIX group named `ziti` if it doesn't already exist. Members of this group can access the identity files and send IPC commands to the socket server.
 
-```text
-grep -q '^ziti:' /etc/group || sudo groupadd --system ziti
-```
+    ```text
+    sudo groupadd --system ziti
+    ```
 
-Create a directory to hold the identity files.
+1. Create a directory to hold the identity files. The tunneler will manage the contents of the identity directory.
 
-```text
-sudo mkdir -pv /opt/openziti/etc/identities
-```
+    ```text
+    sudo mkdir -pv /opt/openziti/etc/identities
+    ```
 
-### Run the Manually Installed Binary
+1. Run the Manually Installed Binary
 
-You must run the manually installed tunneller as root because only the Linux package configures ambient
-kernel capabilities that enable managing DNS and IP routes with reduced privileges.
+    When not using the Linux package, you must run the tunneler as root so it will have permission to manage IP routes and the resolver configuration.
 
-```text
-sudo ziti-edge-tunnel run --identity-dir /opt/openziti/etc/identities
-```
+    ```text
+    sudo ziti-edge-tunnel run --identity-dir /opt/openziti/etc/identities
+    ```
 
-[Learn more about tunneller options and modes](./40-linux-tunnel-options.mdx).
+1. Add an Identity
+
+    <LinuxAddIdentities/>
+
+1. Configure the Resolver
+
+    <LinuxResolverConfig/>

docusaurus/docs/reference/tunnelers/60-linux/40-linux-tunnel-options.mdx

@@ -1,3 +1,4 @@
+import LinuxResolverConfig from '/docs/reference/tunnelers/60-linux/_resolver.mdx'
 
 # Options and Modes
 
@@ -60,13 +61,7 @@ If any interface has a wildcard routing domain configured, `ziti-edge-tunnel` wi
 
 #### How does `run` configure nameservers?
 
-`ziti-edge-tunnel run` provides a built-in nameserver that will answer queries that exactly match authorized OpenZiti services' intercept domain names and will respond with a hard-fail `NXDOMAIN` code if the query does not match an authorized service.
-
-You may enable DNS recursion by specifying an upstream nameserver to answer queries for other domain names that are not services' intercept domain names: `ziti-edge-tunnel run --dns-upstream 208.67.222.222`.
-
-`ziti-edge-tunnel` uses the `libsystemd` D-Bus RPC client and will try to configure the OS's resolvers with `systemd-resolved`. If that's not possible for any reason then `ziti-edge-tunnel run` will fall back to shell commands like `resolvectl`. If `resolvectl` fails then `ziti-edge-tunnel run` will attempt to modify `/etc/resolv.conf` directly to install the built-in nameserver as the primary resolver.
-
-If the DNS record exists it returns the answer and sets query status to `NO_ERROR`. If it does not exist then it sends the query to an upstream DNS server if configured. Otherwise, it sets the query status to `REFUSE`. This implies that the caller *should* keep trying to resolve the domain name with other nameservers.
+<LinuxResolverConfig/>
 
 #### System Requirements for Mode `run`
 

docusaurus/docs/reference/tunnelers/60-linux/50-linux-tunnel-troubleshooting.mdx

@@ -1,6 +1,12 @@
 
+import LinuxResolverConfig from '/docs/reference/tunnelers/60-linux/_resolver.mdx'
+
 # Troubleshooting
 
+## DNS Not Working
+
+<LinuxResolverConfig/>
+
 ## Increase Log Level
 
 Set the log level to DEBUG to identify the activity that is occurring at the same time as the problem.

docusaurus/docs/reference/tunnelers/60-linux/_add_identities.mdx

@@ -0,0 +1,40 @@
+
+The tunneller can run with zero or more identities loaded, and needs at least one to make OpenZiti services available on
+the host. Adding an identity means providing a JWT enrollment token which is used by the tunneller to obtain a client
+certificate from the OpenZiti controller. [Learn more about OpenZiti Identities](/learn/core-concepts/identities/overview.mdx).
+
+### Add a Single Identity
+
+Root and members of group `ziti` may add an identity without restarting. 
+
+```text
+sudo ziti-edge-tunnel add --jwt "$(< ./in-file.jwt)" --identity myIdentityName
+```
+
+[Learn more about enrolling](/learn/core-concepts/identities/20-enrolling.md).
+
+### Load Identities Directory
+
+The tunneller will load all enrolled identities in the `--identity-dir` directory at startup. The default location for
+identities is is `/opt/openziti/etc/identities`. Add enrolled identity files to this directory by copying the JSON file
+into the directory and setting permissions for group `ziti`.
+
+:::note
+Linux package users may place enrollment tokens named `*.jwt` in this directory for automatic enrollment at next
+startup.
+:::
+
+Ensure the identities directory is writable by group `ziti` and not readable by others to protect the confidentiality of
+the identities.
+
+```text
+sudo chown -cR :ziti        /opt/openziti/etc/identities
+sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities
+```
+
+The tunneller process needs to be restarted if the contents of `/opt/openziti/etc/identities` change.
+
+```text
+# package users can restart with systemd
+sudo systemctl restart ziti-edge-tunnel.service
+```

docusaurus/docs/reference/tunnelers/60-linux/_resolver.mdx

@@ -0,0 +1,12 @@
+
+`ziti-edge-tunnel run` provides a built-in nameserver for the services it is authorized to dial. The nameserver is automatically configured by `systemd-resolved`, if enabled.
+
+If `systemd-resolved` is not enabled, you must configure your resolver to query the tunneler's nameserver. Add Ziti's nameserver to the connection manager, e.g., NetworkManager, Netplan, or by directly editing `/etc/resolv.conf`.
+
+You may configure the system resolver to use the tunneler's nameserver as the first or only nameserver.
+
+When the tunneler nameserver is the first of multiple nameservers and the requested DNS record does not match an authorized service's intercept domain name, it sets the query status to `REFUSE`. This implies that the caller *should* keep trying to resolve the domain name with other nameservers.
+
+To use the tunneler nameserver as the only nameserver, you must specify an upstream nameserver for recursion: `ziti-edge-tunnel run --dns-upstream 208.67.222.222`. In this configuration, the query status from the upstream nameserver is returned, e.g., `NXDOMAIN` if the domain name is not found in the tunneler nameserver or the upstream nameserver.
+
+The IP address of the nameserver (default: `100.64.0.2`) is determined by the tunneler's dns-ip-range (default: `100.64.0.1/10`).

docusaurus/docs/reference/tunnelers/60-linux/index.mdx

@@ -16,8 +16,8 @@ Reasons to use the package:
 
 1. Install the tunneller as a systemd service.
 1. Create permissions and policies for the tunneller to run as a non-root user.
-1. Automatically enroll the identity and clean up the enrollment token in identity directory.
-1. Automatically upgrade the tunneller when a new package is available.
+1. Enroll the identity and clean up the enrollment token in identity directory.
+1. Upgrade the tunneller when a new package is available.
 
 Linux DEB packages are currently available for the x86_64 and arm64 platforms and RPM packages are available for x86_64.
 ARM/v7 (32bit) binaries are available from GitHub.
@@ -26,48 +26,6 @@ ARM/v7 (32bit) binaries are available from GitHub.
 - [RedHat](./20-redhat-package.mdx)
 - [GitHub](./30-manual-installation.mdx)
 
-## Adding Identities
-
-The tunneller can run with zero or more identities loaded, and needs at least one to make OpenZiti services available on
-the host. Adding an identity means providing a JWT enrollment token which is used by the tunneller to obtain a client
-certificate from the OpenZiti controller. [Learn more about OpenZiti Identities](/learn/core-concepts/identities/overview.mdx).
-
-### Add a Single Identity
-
-Root and members of group `ziti` may add an identity without restarting. 
-
-```text
-sudo ziti-edge-tunnel add --jwt "$(< ./in-file.jwt)" --identity myIdentityName
-```
-
-[Learn more about enrolling](/learn/core-concepts/identities/20-enrolling.md).
-
-### Load Identities Directory
-
-The tunneller will load all enrolled identities in the `--identity-dir` directory at startup. The default location for
-identities is is `/opt/openziti/etc/identities`. Add enrolled identity files to this directory by copying the JSON file
-into the directory and setting permissions for group `ziti`.
-
-:::note
-Linux package users may place enrollment tokens named `*.jwt` in this directory for automatic enrollment at next
-startup.
-:::
-
-Ensure the identities directory is writable by group `ziti` and not readable by others to protect the confidentiality of
-the identities.
-
-```text
-sudo chown -cR :ziti        /opt/openziti/etc/identities
-sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities
-```
-
-The tunneller process needs to be restarted if the contents of `/opt/openziti/etc/identities` change.
-
-```text
-# package users can restart with systemd
-sudo systemctl restart ziti-edge-tunnel.service
-```
-
 ## Run with Docker
 
 Reference [the article about running the Linux tunneller in a container](/reference/tunnelers/70-docker/readme.mdx) for guidance and