Skip to content

Commit

Permalink
clarify adding an identity
Browse files Browse the repository at this point in the history
  • Loading branch information
@qrkourier
qrkourier committed Sep 30, 2023
1 parent 7f26f1a commit cca07b1
Showing 1 changed file with 58 additions and 36 deletions.
94 changes: 58 additions & 36 deletions docusaurus/docs/reference/tunnelers/linux/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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
(
Expand All @@ -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
Expand Down Expand Up @@ -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 \
Expand All @@ -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)

0 comments on commit cca07b1

Please sign in to comment.