From cca07b1f6eebf244c2d43058855d7330dd8957e5 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 28 Sep 2023 17:52:12 -0400 Subject: [PATCH] clarify adding an identity --- .../docs/reference/tunnelers/linux/index.md | 94 ++++++++++++------- 1 file changed, 58 insertions(+), 36 deletions(-) diff --git a/docusaurus/docs/reference/tunnelers/linux/index.md b/docusaurus/docs/reference/tunnelers/linux/index.md index 084ad9452..3ed483f32 100644 --- a/docusaurus/docs/reference/tunnelers/linux/index.md +++ b/docusaurus/docs/reference/tunnelers/linux/index.md @@ -9,7 +9,9 @@ import TabItem from '@theme/TabItem'; `ziti-edge-tunnel` is the general purpose tunneller CLI and can also run as a systemd daemon. -The purpose of the tunneller is to configure host access. This means all users and all processes on the host will share the same level of access. This is accomplished by configuring the OS to have an on-board OpenZiti DNS nameserver and IP routes for authorized OpenZiti Services. +The purpose of the tunneller is to configure host access. This means all users and all processes on the host will share +the same level of access. This is accomplished by configuring the OS to have an on-board OpenZiti DNS nameserver and IP +routes for authorized OpenZiti Services. ## Install Linux Package @@ -20,10 +22,13 @@ Reasons to use the package: 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. -Linux DEB packages are currently available for the x86_64 and arm64 platforms and RPM packages are available for x86_64. Additionally, there are executable downloads available for arm/v7 (32bit) for [manual installation](#manual-installation). +Linux DEB packages are currently available for the x86_64 and arm64 platforms and RPM packages are available for x86_64. +Additionally, there are executable downloads available for arm/v7 (32bit) for [manual +installation](#manual-installation). :::note -It is not necessary to manually enroll the identity when using the RPM or DEB package. Just install the token in the identities directory with file owner "ziti" and it will be enrolled and cleaned up when you start the service. +It is not necessary to manually enroll the identity when using the RPM or DEB package. Just install the token in the +identities directory with file owner "ziti" and it will be enrolled and cleaned up when you start the service. ::: ### Installing the DEB @@ -70,7 +75,9 @@ curl -sSLf https://get.openziti.io/tun/scripts/install-ubuntu.bash | bash | 10 Buster | Bionic 18.04 | x86_64 | | 9 Stretch | Xenial 16.04 | x86_64 | -This example subscribes you to the Ubuntu `focal` repo which will work well in most cases. Alternatively, you may refer to the table to find the Ubuntu release name that is the contemporary of your Debian release. Then, substitute the Ubuntu release name for `focal` in the `/etc/apt/sources.list.d/openziti.list` file. +This example subscribes you to the Ubuntu `focal` repo which will work well in most cases. Alternatively, you may refer +to the table to find the Ubuntu release name that is the contemporary of your Debian release. Then, substitute the +Ubuntu release name for `focal` in the `/etc/apt/sources.list.d/openziti.list` file. ```text ( @@ -92,23 +99,13 @@ sudo apt install ziti-edge-tunnel 2. Place a copy of the enrollment token JWT file in the `/opt/openziti/etc/identities` directory. 2. Set the filemode and owner so that members of group `ziti` will be able to read and delete the token file. - - ```text - sudo chown -cR :ziti /opt/openziti/etc/identities - sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities - ``` - 2. Enable and start the service ```text sudo systemctl enable --now ziti-edge-tunnel.service ``` -2. The process needs to be restarted if the contents of `/opt/openziti/etc/identities` change. - - ```text - sudo systemctl restart ziti-edge-tunnel.service - ``` +2. [Add an Identity](#adding-an-identity) ### Installing the RPM @@ -187,34 +184,55 @@ repo_gpgcheck=1 2. Run `sudo yum update` to refresh your repo data cache. Optionally, you may wish to also install all available updates. 2. Run `sudo yum install ziti-edge-tunnel` to install the RPM. -2. Place a copy of the enrollment token JWT file in the `/opt/openziti/etc/identities` directory. -2. Set the filemode and owner so that members of group `ziti` will be able to read and delete the token file. - - ```text - sudo chown -cR :ziti /opt/openziti/etc/identities - sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities - ``` - 2. Enable and start the service ```text sudo systemctl enable --now ziti-edge-tunnel.service ``` -2. The process needs to be restarted if the contents of `/opt/openziti/etc/identities` change. +2. Add an Identity - ```text - sudo systemctl restart ziti-edge-tunnel.service - ``` +## Adding an Identity + +### Restart to Load All in Identity Directory + +The tunneler will load all identities in the `--identity-dir` directory. The identities directory created by the package +installation is `/opt/openziti/etc/identities`. You may add identity files to this directory by copying the identity +file into the directory and setting permissions for group `ziti`. + +``` +sudo chown -cR :ziti /opt/openziti/etc/identities +sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities +``` + +The tunneler process needs to be restarted if the contents of `/opt/openziti/etc/identities` change. + +```text +sudo systemctl restart ziti-edge-tunnel.service +``` + +### Load a Single Identity Without Restarting + +This sends an IPC command to the running tunneler. You must have write permission on the IPC socket +(`/tmp/.ziti/ziti-edge-tunnel.sock`). You may run this command as yourself instead of user `ziti` if you are a member of +group `ziti`. + +``` +sudo -u ziti \ + ziti-edge-tunnel add --jwt "$(< ./in-file.jwt)" --identity myIdentityName +``` ## Manual Installation -[The latest binary release](https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/) of `ziti-edge-tunnel` is distributed as an executable for amd64, arm, arm64 architectures. The upgrade procedure is identical to the installation procedure. +[The latest binary release](https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/) of `ziti-edge-tunnel` is +distributed as an executable for amd64, arm, arm64 architectures. The upgrade procedure is identical to the installation +procedure. You'll need to install the `wget` and `unzip` commands to use this example. ```text -wget -q "https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/download/ziti-edge-tunnel-Linux_$(uname -p).zip" \ +wget -q \ + "https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/download/ziti-edge-tunnel-Linux_$(uname -p).zip" \ && unzip ./ziti-edge-tunnel-Linux_$(uname -p).zip \ && rm ./ziti-edge-tunnel-Linux_$(uname -p).zip \ && chmod -c +x ./ziti-edge-tunnel \ @@ -223,23 +241,27 @@ wget -q "https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/download/ ### Enroll Before You Run -You will need the token file or its contents to enroll. Enrollment is the act of exchanging the token for an identity that is to be permanently installed in the filesystem. +You will need the token file or its contents to enroll. + +``` +ziti-edge-tunnel enroll --jwt ./in-file.jwt --identity ./out-file.json +``` -[Learn more about enrolling](/docs/learn/core-concepts/identities/enrolling). +[Learn more about enrolling](/learn/core-concepts/identities/20-enrolling.md). ### Run the Manually Installed Binary ```text -ziti-edge-tunnel run \ - --identity-dir /opt/openziti/etc/identities +ziti-edge-tunnel run --identity-dir /opt/openziti/etc/identities ``` -[Learn more about tunneler options and modes](./linux-tunnel-options). +[Learn more about tunneler options and modes](./linux-tunnel-options.md). ## Run with Docker -Please reference [the article about running the Linux tunneler in a container](./container/readme.mdx) for guidance and examples! +Please reference [the article about running the Linux tunneler in a container](./container/readme.mdx) for guidance and +examples! ## Troubleshooting -Please refer to [the troubleshooting guide](./linux-tunnel-troubleshooting) +Please refer to [the troubleshooting guide](./linux-tunnel-troubleshooting.md)