diff --git a/docusaurus/docs/reference/tunnelers/60-linux/10-debian-package.mdx b/docusaurus/docs/reference/tunnelers/60-linux/10-debian-package.mdx index bf0413c6..95d0c418 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/10-debian-package.mdx +++ b/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. - @@ -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. + + + +2. Configure the Resolver. + + + diff --git a/docusaurus/docs/reference/tunnelers/60-linux/20-redhat-package.mdx b/docusaurus/docs/reference/tunnelers/60-linux/20-redhat-package.mdx index 768eb8ad..617855be 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/20-redhat-package.mdx +++ b/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. + + +2. Configure the Resolver. + + diff --git a/docusaurus/docs/reference/tunnelers/60-linux/30-manual-installation.mdx b/docusaurus/docs/reference/tunnelers/60-linux/30-manual-installation.mdx index e106e593..f00f8354 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/30-manual-installation.mdx +++ b/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 + + + +1. Configure the Resolver + + diff --git a/docusaurus/docs/reference/tunnelers/60-linux/40-linux-tunnel-options.mdx b/docusaurus/docs/reference/tunnelers/60-linux/40-linux-tunnel-options.mdx index 17cb023a..fd044f54 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/40-linux-tunnel-options.mdx +++ b/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. + #### System Requirements for Mode `run` diff --git a/docusaurus/docs/reference/tunnelers/60-linux/50-linux-tunnel-troubleshooting.mdx b/docusaurus/docs/reference/tunnelers/60-linux/50-linux-tunnel-troubleshooting.mdx index f577c99e..555a62aa 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/50-linux-tunnel-troubleshooting.mdx +++ b/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 + + + ## Increase Log Level Set the log level to DEBUG to identify the activity that is occurring at the same time as the problem. diff --git a/docusaurus/docs/reference/tunnelers/60-linux/_add_identities.mdx b/docusaurus/docs/reference/tunnelers/60-linux/_add_identities.mdx new file mode 100644 index 00000000..4337015f --- /dev/null +++ b/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 +``` diff --git a/docusaurus/docs/reference/tunnelers/60-linux/_resolver.mdx b/docusaurus/docs/reference/tunnelers/60-linux/_resolver.mdx new file mode 100644 index 00000000..ef6e6470 --- /dev/null +++ b/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`). diff --git a/docusaurus/docs/reference/tunnelers/60-linux/index.mdx b/docusaurus/docs/reference/tunnelers/60-linux/index.mdx index 81a6d998..b78a3fc2 100644 --- a/docusaurus/docs/reference/tunnelers/60-linux/index.mdx +++ b/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