From cf6631d84a8c26e660345884579f27f6d736d6c5 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 16 Sep 2024 08:25:46 -0400 Subject: [PATCH 1/6] organize self-service invitation doc --- docs/getting-started.mdx | 45 +--------------- .../self-hosting/self-service-invite.mdx | 54 +++++++++++++++++++ 2 files changed, 55 insertions(+), 44 deletions(-) create mode 100644 docs/guides/self-hosting/self-service-invite.mdx diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 70cba0ef..d520e83e 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -96,49 +96,6 @@ If [sharing privately](./concepts/sharing-private.md), only users with the share -## Generating an Invitation - -:::note -If not using `zrok.io` (zrok-as-a-service), you must configure the `zrok` command to use your instance. See the [instance configuration guide](/guides/self-hosting/instance-configuration.mdx) in the self-hosting section for details. -::: - -Invite yourself to `zrok` by running the `zrok invite` command: - -```text -zrok invite -``` - -```buttonless title="Output" -enter and confirm your email address... - -> user@domain.com -> user@domain.com - -[ Submit ] - -invitation sent to 'user@domain.com'! -``` - -The `zrok invite` command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the `[ Submit ]` button will send the request to your configured `zrok` service. - -Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your `zrok` account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account: - -![Enter a Password](images/zrok_verify.png) - -Enter a password and its confirmation, and click the `Register Account` button. You'll see the following: - -![Successful Registration](images/zrok_registration_success.png) - -For now, we'll ignore the "enable your shell for zrok" section. Just click the `zrok web portal` link: - -![Web Login](images/zrok_web_login.png) - -After clicking the `Log In` button, you'll be brought into the `zrok` _web console_: - -![Web Console; Empty](images/zrok_web_console_empty.png) - -Congratulations! Your `zrok` account is ready to go! - ## Enabling Your zrok Environment A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator. @@ -371,7 +328,7 @@ Here's a quick review of the `zrok` mental model and the vocabulary. You create an _account_ with a `zrok` _instance_. Your account is identified by a username and a password, which you use to log into the _web console_. Your account also has a _secret token_, which you will use to authenticate from the `zrok` command-line to interact with the _instance_. -You create a new _account_ with a `zrok` _instance_ through the `zrok invite` command. +You create a new _account_ with NetFoundry's `zrok` _instance_ by subscribing in [myzrok.io](https://myzrok.io) or in a self-hosted `zrok` _instance_ by running [the `zrok invite` command](/guides/self-hosting/self-service-invite.mdx). ### Environment diff --git a/docs/guides/self-hosting/self-service-invite.mdx b/docs/guides/self-hosting/self-service-invite.mdx new file mode 100644 index 00000000..a04c0cbc --- /dev/null +++ b/docs/guides/self-hosting/self-service-invite.mdx @@ -0,0 +1,54 @@ +--- +title: Invitations +--- + +This is how to set up self-service invitations for your users to get an account on your self-hosted zrok instance. + +## Overview + +- You can create user accounts directly with the `zrok admin` CLI or API. +- You can welcome users to invite themselves via email. +- You can generate invitation tokens if you want to restrict self-service invitations. +- To enable self-service invitations you must also configure the controller to send email. + +## The Self-Service User Experience + +This is what your users will do. + +```bash +zrok invite +``` + +```buttonless title="Output" +enter and confirm your email address... + +> user@domain.com +> user@domain.com + +[ Submit ] + +invitation sent to 'user@domain.com'! +``` + +## How it Works + +The `zrok invite` command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the `[ Submit ]` button will start the invitation process. + +Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your `zrok` account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account. + +![Enter a Password](/zrok_verify.png) + +Enter a password and its confirmation, and click the `Register Account` button. You'll see the following: + +![Successful Registration](/zrok_registration_success.png) + +For now, we'll ignore the "enable your shell for zrok" section. Just click the `zrok web portal` link: + +![Web Login](/zrok_web_login.png) + +After clicking the `Log In` button, you'll be brought into the `zrok` _web console_: + +![Web Console; Empty](/zrok_web_console_empty.png) + +Congratulations! Your `zrok` account is ready to go! + From dd21a4edc8ed48da26baf80dfb840b4854286324 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 16 Sep 2024 10:45:52 -0400 Subject: [PATCH 2/6] clarify getting an account is necessary before enabling --- docs/getting-started.mdx | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index d520e83e..b29cb326 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -9,24 +9,9 @@ import DownloadCard from '@site/src/components/download-card'; import DownloadCardStyles from '@site/src/css/download-card.module.css'; -## Choose Your Path +## Get an Account - - - -

Self-Hosted zrok

- - - Run a zrok instance on Linux, Docker, or Kubernetes. - - - - - - - - @@ -42,6 +27,21 @@ import DownloadCardStyles from '@site/src/css/download-card.module.css'; + + + +

Self-Hosted zrok

+ + + Run a zrok instance on Linux, Docker, or Kubernetes. + + + + + + + + @@ -98,6 +98,8 @@ If [sharing privately](./concepts/sharing-private.md), only users with the share ## Enabling Your zrok Environment +After you have [an account](#get-an-account), you can enable your `zrok` environment. + A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator. When your `zrok` account was created, the service generated a _secret token_ that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a _secret_, protect it. From 9f3006d331d8b6de2eca4ad5be2037170f5d07ca Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Sat, 21 Sep 2024 10:45:39 -0400 Subject: [PATCH 3/6] do not exit after warning --- nfpm/zrok-share.bash | 1 - 1 file changed, 1 deletion(-) diff --git a/nfpm/zrok-share.bash b/nfpm/zrok-share.bash index d245b9fb..0296f87e 100644 --- a/nfpm/zrok-share.bash +++ b/nfpm/zrok-share.bash @@ -174,7 +174,6 @@ if [[ "${ZROK_FRONTEND_MODE:-}" =~ -private$ && "${ZROK_PERMISSION_MODE:-}" == c done else echo "WARNING: ZROK_PERMISSION_MODE='${ZROK_PERMISSION_MODE}' and no additional ZROK_ACCESS_GRANTS; will be granted access" >&2 - exit 1 fi elif [[ "${ZROK_FRONTEND_MODE:-}" =~ -private$ && -n "${ZROK_PERMISSION_MODE:-}" && "${ZROK_PERMISSION_MODE}" != open ]]; then echo "WARNING: ZROK_PERMISSION_MODE='${ZROK_PERMISSION_MODE}' is not a recognized value'" >&2 From 92eaac43a02f12abd6aa9afb9c0fe0b7c111c320 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Sat, 21 Sep 2024 11:51:49 -0400 Subject: [PATCH 4/6] tidy examples --- docs/guides/docker-share/docker_private_share_guide.md | 2 +- nfpm/zrok-share.env | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/docker-share/docker_private_share_guide.md b/docs/guides/docker-share/docker_private_share_guide.md index d9005f5f..1d7eda86 100644 --- a/docs/guides/docker-share/docker_private_share_guide.md +++ b/docs/guides/docker-share/docker_private_share_guide.md @@ -108,7 +108,7 @@ You must set the permission mode before you reserve the share. Only your own account can access the private share. ```bash -ZROK_PERMISSION_MODE=closed +ZROK_PERMISSION_MODE="closed" ``` Grant access to additional zrok accounts. diff --git a/nfpm/zrok-share.env b/nfpm/zrok-share.env index c54e13a2..c1b0b8f4 100644 --- a/nfpm/zrok-share.env +++ b/nfpm/zrok-share.env @@ -108,7 +108,7 @@ ZROK_TARGET="" # e.g., http://127.0.0.1:3000 #ZROK_FRONTEND_MODE="reserved-public" # you MAY restrict access to a private share allowing only your own zrok account -#ZROK_PERMISSION_MODE=closed +#ZROK_PERMISSION_MODE="closed" # if permission mode "closed" - space-separated list of additional zrok account emails to grant access with the share token #ZROK_ACCESS_GRANTS="" From c5ed090883d1ff5cf60ab1e7fe9ecc928b67bcad Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Thu, 26 Sep 2024 16:14:30 -0400 Subject: [PATCH 5/6] announce fix --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f59151a..7e89470d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ FIX: Fixed crash when invoking `zrok share reserved` with no arguments (https://github.com/openziti/zrok/issues/740) +FIX: zrok-share.service on Linux failed to start with a private share in closed permission mode + ## v0.4.40 FEATURE: New endpoint for synchronizing grants for an account (https://github.com/openziti/zrok/pull/744). Useful for updating the `zrok.proxy.v1` config objects containing interstitial setting when the `skip_interstitial_grants` table has been updated. From bc8120bbda4327127c2e9f4626fe49ade970d8d2 Mon Sep 17 00:00:00 2001 From: Michael Quigley Date: Mon, 30 Sep 2024 11:11:56 -0400 Subject: [PATCH 6/6] removing until someone has time to fix this --- .github/workflows/zhook.yml | 45 ------------------------------------- 1 file changed, 45 deletions(-) delete mode 100644 .github/workflows/zhook.yml diff --git a/.github/workflows/zhook.yml b/.github/workflows/zhook.yml deleted file mode 100644 index 72218584..00000000 --- a/.github/workflows/zhook.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: mattermost-ziti-webhook -on: - create: - delete: - issues: - issue_comment: - pull_request_review: - types: [submitted] - pull_request_review_comment: - pull_request: - types: [opened, reopened] - push: - fork: - release: - types: [released] - workflow_dispatch: - watch: - types: [started] - -jobs: - mattermost-ziti-webhook: - runs-on: ubuntu-latest - name: POST Webhook - steps: - - uses: openziti/ziti-mattermost-action-py@main - if: | - env.ZHOOK_URL != null - && !( - github.event_name == 'issue_comment' - && github.event.sender.login == 'vercel[bot]' - && (contains(github.event.comment.body, 'Building') || contains(github.event.comment.body, 'Ignored')) - ) - && ( - github.event_name != 'pull_request_review' - || (github.event_name == 'pull_request_review' && github.event.review.state == 'approved') - ) - env: - ZHOOK_URL: ${{ secrets.ZHOOK_URL }} - with: - zitiId: ${{ secrets.ZITI_MATTERMOST_IDENTITY }} - webhookUrl: ${{ secrets.ZHOOK_URL }} - eventJson: ${{ toJson(github.event) }} - senderUsername: "GitHubZ" - destChannel: "dev-notifications" -