diff --git a/docusaurus/docs/_cli-login.md b/docusaurus/docs/_cli-login.md index b252ca7c..c2ea2c00 100644 --- a/docusaurus/docs/_cli-login.md +++ b/docusaurus/docs/_cli-login.md @@ -2,12 +2,12 @@ The `ziti` CLI will help you get an API Session from the controller's management API. You will be prompted to trust any new server certificates. Your login token cache and trust store are managed by the CLI in your home directory. -```text -# implies https://localhost:1280 +```text title="Log in to https://localhost:1280 with the default password" ziti edge login -u admin -p admin ``` -```text -# implies https:// -ziti edge login ctrl.ziti.example.com:8441 -u admin -p admin +```text title="Log in to https://ctrl.ziti.example.com:443 with an identity file" +ziti edge login ctrl.ziti.example.com --file admin2.json ``` + +[Learn how to create an admin identity file](/guides/deployments/50-security.mdx#create-an-admin-identity) \ No newline at end of file diff --git a/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx b/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx index 6989e054..c3a2ea02 100644 --- a/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx +++ b/docusaurus/docs/guides/deployments/10-linux/20-router/10-deploy.mdx @@ -20,7 +20,13 @@ We'll cover the following topics: You must create the router in the controller first with [the web console](/guides/deployments/10-linux/30-console.mdx) or [the CLI](/guides/deployments/10-linux/20-router/40-cli-mgmt.md). -After creating the router, save the enrollment token (JWT) and use it to finish configuring the router deployment. +After creating the router, save the enrollment token (JWT) and provide the file path to the router during the configuration step below. + +```text +ziti edge create edge-router "router1" \ +--jwt-output-file=/tmp/router1.jwt \ +--tunneler-enabled +``` ## Install the Router Package diff --git a/docusaurus/docs/guides/deployments/10-linux/20-router/30-configuration.md b/docusaurus/docs/guides/deployments/10-linux/20-router/30-configuration.md index 8e657c2a..dc34a3ff 100644 --- a/docusaurus/docs/guides/deployments/10-linux/20-router/30-configuration.md +++ b/docusaurus/docs/guides/deployments/10-linux/20-router/30-configuration.md @@ -32,7 +32,7 @@ The [`identity`](/reference/30-configuration/conventions.md#identity) configurat If present, the `server_key` signs the router's server certificate request. Otherwise, the `key` sub-property is used for both client and server certificate. -The private keys' values are assumed to be `file://` URLs if unspecified. Alternatives include `pkcs11://` and `parsec://` URLs for hardware keys. +The private keys' values are assumed to be `file://` URLs if unspecified. Alternatives include `pkcs11://` and `parsec://` URLs for [hardware keys](/guides/hsm/index.md). ## Optional Capabilities diff --git a/docusaurus/docs/guides/deployments/10-linux/20-router/40-cli-mgmt.md b/docusaurus/docs/guides/deployments/10-linux/20-router/40-cli-mgmt.md index db57687e..5b794749 100644 --- a/docusaurus/docs/guides/deployments/10-linux/20-router/40-cli-mgmt.md +++ b/docusaurus/docs/guides/deployments/10-linux/20-router/40-cli-mgmt.md @@ -18,7 +18,7 @@ import CliLogin from '/docs/_cli-login.md' -The tunneler flag must be administratively set when the router is created or updated. There are no administrative flags pertaining to the router's listeners. +The tunneler flag must be administratively set when the router is created or updated or the router will not start.
diff --git a/docusaurus/docs/guides/deployments/10-linux/30-console.mdx b/docusaurus/docs/guides/deployments/10-linux/30-console.mdx index ca1b5bf6..68dce81d 100644 --- a/docusaurus/docs/guides/deployments/10-linux/30-console.mdx +++ b/docusaurus/docs/guides/deployments/10-linux/30-console.mdx @@ -3,30 +3,51 @@ title: Console Deployment sidebar_label: Console --- -The console must be bound to the same web listener as the controller's management API. +## Installation -1. On the controller host, download the latest release of the console from GitHub. You can use any console version >= 3.0.0. +### Install the Package + +The package installs the console files in `/opt/openziti/share/console`. + +```text title="Install the console package" +sudo apt install openziti-console +``` + +Or, configure the package repository and install with this one-liner. + +```text title="Configure the package repository and install openziti-console" +curl -sS https://get.openziti.io/install.bash | sudo bash -s openziti-console +``` + +### Install from GitHub + +Console versions >= 3.0.0 from GitHub may be used. + +1. Download a release. ```text wget https://github.com/openziti/ziti-console/releases/latest/download/ziti-console.zip ``` -1. Unzip the console in the controller's working directory. +1. Unzip in a directory that is mounted the controller's filesystem namespace. ```text - sudo unzip -d /var/lib/ziti-controller/zac ./ziti-console.zip + sudo mkdir -p /opt/openziti/share/console + sudo unzip -d /opt/openziti/share/console ./ziti-console.zip ``` -1. In **/var/lib/ziti-controller/config.yml**, ensure you have an API binding `zac` on the same web listener where `edge-management` is bound. Ensure the `location` matches the path where you unzipped the console. +## Configuration + +1. In **/var/lib/ziti-controller/config.yml**, ensure you have an API binding `zac` on the same web listener where `edge-management` is bound. Ensure the `location` matches the path to the console files. ```text - binding: zac options: - location: /var/lib/ziti-controller/zac + location: /opt/openziti/share/console indexFile: index.html ``` -1. Restart the controller service to apply the changes. +1. Restart the controller service if you edited the configuration. ```text sudo systemctl restart ziti-controller.service diff --git a/docusaurus/docs/guides/deployments/20-docker/30-console.mdx b/docusaurus/docs/guides/deployments/20-docker/30-console.mdx index 4611ebfa..a7c7c38f 100644 --- a/docusaurus/docs/guides/deployments/20-docker/30-console.mdx +++ b/docusaurus/docs/guides/deployments/20-docker/30-console.mdx @@ -3,7 +3,7 @@ title: Deploy the Console sidebar_label: Console --- -This article is about deploying the console as a single-page application (SPA) embedded in the controller's API running in a container. +This article is about enabling the console on a controller that is running in a container. 1. Configure the controller @@ -34,9 +34,9 @@ This article is about deploying the console as a single-page application (SPA) e ## Upgrade -You can mount a different version of the console on the controller container if you don't want to use the version that comes with it. +The controller container includes the latest version of the console. You can instead mount console versions >= 3.0.0. -1. On the Docker host, download the latest release of the console from GitHub. You can use any console version >= 3.0.0. +1. Download a release. ```text wget https://github.com/openziti/ziti-console/releases/latest/download/ziti-console.zip @@ -49,13 +49,13 @@ You can mount a different version of the console on the controller container if chmod -R a+rX ./ziti-console ``` -1. Mount the console directory on the controller container. +1. Mount the console files read-only on the controller container. ```text services: ziti-controller: volumes: - - ./ziti-console:/ziti-console + - ./ziti-console:/ziti-console:ro ``` 1. Restart the controller service to apply the changes. diff --git a/docusaurus/docs/guides/deployments/50-security.mdx b/docusaurus/docs/guides/deployments/50-security.mdx new file mode 100644 index 00000000..cd1c9007 --- /dev/null +++ b/docusaurus/docs/guides/deployments/50-security.mdx @@ -0,0 +1,20 @@ +--- +title: Best Practices for Security +sidebar_label: Security +--- + +## Create an Admin Identity + +The default admin identity is initialized with a password. Store the password in a secure location and create a new admin identity for certificate authentication. + +```text title="Create an admin2 identity for certificate authentication" +ziti edge create identity admin2 --admin --jwt-output-file admin2.jwt +``` + +```text title="Copy token to the admin device and enroll" +ziti edge enroll admin2.jwt +``` + +```text title="Log in to https://ctrl.ziti.example.com:443 with an identity file" +ziti edge login ctrl.ziti.example.com --file admin2.json +```