Deploy the Console

This article is about enabling the console on a controller that is running in a container.

1. Configure the controller

   The console's zac binding must be on the same web listener as the controller's management API, i.e., the edge-management binding.

   
   

         - binding: zac
           options:
             location: /ziti-console
             indexFile: index.html
   • location is the filesystem path to the static files of the console. In the controller container, the usual path is /ziti-console.
   • indexFile property is the entry point to the console.

2. To apply the changes, the controller must be restarted.

3. Visit the console at /zac/ on the controller's address.

   The console is now available at https://<fqdn>:<port>/zac/.

4. Log in to the console.

   The only available authentication method for the console SPA is username and password.

5. Console certificate option - The console is served from the controller's API and can be used with the default API certificate. The controller can be configured to present a different certificate for the console when the API is accessed by a distinct URL for the console. For more information about using alternative server certs with the controller, see: the configuration reference for the identity property.

Upgrade

The controller container includes the latest version of the console. You can instead mount console versions >= 3.0.0.

1. Download a release.

   wget https://github.com/openziti/ziti-console/releases/latest/download/ziti-console.zip

2. Unzip the static files and set read and list permission.

   unzip -d ./ziti-console ./ziti-console.zip
   chmod -R a+rX ./ziti-console

3. Mount the console files read-only on the controller container.

   services:
     ziti-controller:
       volumes:
         - ./ziti-console:/ziti-console:ro

4. Restart the controller service to apply the changes.

   docker compose up ziti-controller --force-recreate

Authenticate with an Admin Client Certificate

1. Enroll an admin identity. Link to instructions

2. Unwrap the JSON file to obtain the certificate and private key.

   ziti ops unwrap admin2.json

3. Compose a keystore from the certificate and private key. The -legacy flag is necessary when importing the keystore into some versions of macOS Keychain Access.

   openssl pkcs12 -export -in admin2.cert -inkey admin2.key -out admin2.p12 -name "admin2" -legacy -password 'pass:mypassword'

4. Import the keystore:

   • macOS: Import into System Keychain via Keychain Access application for Google Chrome. You can run a terminal command or double-click the keystore file or drag it onto the login keychain to import it.

     security import admin2.p12 -k ~/Library/Keychains/login.keychain -T /Applications/Google\ Chrome.app -P 'mypass'

   • Windows: Import into the Windows Certificate Store (Personal store) via certmgr.msc.

   • Linux: Import into your browser's certificate store or system certificate store (e.g., Chrome Settings > Privacy and Security > Security > Manage certificates).

5. Visit the console in your web browser. The browser will prompt with a list of imported client certificates. Select the one you imported in the previous step.

6. Press the "LOGIN" button without entering a password.