diff --git a/docs/how-to-guides/iot-for-devices/configure-the-snap.md b/docs/how-to-guides/iot-for-devices/configure-the-snap.md index 1f1284eb..2cf01c94 100644 --- a/docs/how-to-guides/iot-for-devices/configure-the-snap.md +++ b/docs/how-to-guides/iot-for-devices/configure-the-snap.md @@ -61,10 +61,10 @@ To use this feature in the Landscape web portal: When this feature is enabled, new devices must be enrolled using the key that’s defined in the **Registration key** field. You can’t auto-register new computers if there is no registration key provided. -Once you’ve defined a registration key and enabled the auto-registration feature, you can auto-register new computers by passing the `--registration-key` argument into `landscape-client.config`. For example, the following code registers a new Landscape Client computer with a registration key. The `{ACCOUNT_NAME}`, `{COMPUTER_TITLE}` and `{REGISTRATION_KEY}` placeholders must be changed to the appropriate values for your configuration. +Once you’ve defined a registration key and enabled the auto-registration feature, you can auto-register new computers by passing the `--registration-key` argument into `landscape-client.config`. For example, the following code registers a new Landscape Client computer with a registration key. The `{LANDSCAPE_ACCOUNT_NAME}`, `{LANDSCAPE_COMPUTER_TITLE}` and `{REGISTRATION_KEY}` placeholders must be changed to the appropriate values for your configuration. ```bash -sudo landscape-client.config --account-name={ACCOUNT_NAME} --computer-title={COMPUTER_TITLE} --registration-key={REGISTRATION_KEY} +sudo landscape-client.config --account-name={LANDSCAPE_ACCOUNT_NAME} --computer-title={LANDSCAPE_COMPUTER_TITLE} --registration-key={REGISTRATION_KEY} ``` ## Manage script execution diff --git a/docs/how-to-guides/iot-for-devices/create-a-core-image.md b/docs/how-to-guides/iot-for-devices/create-a-core-image.md index 9cc53d6f..83e48b67 100644 --- a/docs/how-to-guides/iot-for-devices/create-a-core-image.md +++ b/docs/how-to-guides/iot-for-devices/create-a-core-image.md @@ -117,8 +117,9 @@ To create and configure your gadget snap: defaults: # landscape client ffnH0sJpX3NFAclH777M8BdXIWpo93af: - landscape-url: {LANDSCAPE_ACCOUNT_URL} - account-name: {ACCOUNT_NAME} + url: https://{LANDSCAPE_FQDN}/message-system + ping-url: http://{LANDSCAPE_FQDN}/ping + account-name: {LANDSCAPE_ACCOUNT_NAME} registration-key: "{REGISTRATION_KEY}" auto-register: enabled: true @@ -128,8 +129,8 @@ To create and configure your gadget snap: Replacing the following values with the relevant configuration values: - - `{LANDSCAPE_ACCOUNT_URL}`: The full URL of your Landscape account. Canonical’s Landscape URL is [https://landscape.canonical.com](https://landscape.canonical.com). - - `{ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. + - `{LANDSCAPE_FQDN}`: The FQDN of your Landscape server. For Canonical’s Landscape, use `landscape.canonical.com`. + - `{LANDSCAPE_ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. - `{REGISTRATION_KEY}`: Your registration key. Now, you’ve finished configuring the details of your Landscape server instance. In the `auto-register` section, you’ll likely want to change `computer-title-pattern` to your preferred method of identifying devices. For more information on these parameters, see {ref}`header-explanation-auto-reg-process-gadget-snap` located in this guide. @@ -143,7 +144,7 @@ These details will be the same for all devices that run this image. To build the gadget snap, you just need to run the following in your terminal: ```bash -snapcraft +snapcraft pack ``` Now, you have your snap. This is the snap you want to include in your model assertion. @@ -227,8 +228,9 @@ The `gadget.yaml` file contains a configuration that is similar to the following defaults: # landscape client ffnH0sJpX3NFAclH777M8BdXIWpo93af: - landscape-url: {LANDSCAPE_ACCOUNT_URL} - account-name: {ACCOUNT_NAME} + url: https://{LANDSCAPE_FQDN}/message-system + ping-url: http://{LANDSCAPE_FQDN}/ping + account-name: {LANDSCAPE_ACCOUNT_NAME} registration-key: "{REGISTRATION_KEY}" auto-register: enabled: true diff --git a/docs/how-to-guides/iot-for-devices/install-the-snap.md b/docs/how-to-guides/iot-for-devices/install-the-snap.md index 05f9c8df..3666e6b4 100644 --- a/docs/how-to-guides/iot-for-devices/install-the-snap.md +++ b/docs/how-to-guides/iot-for-devices/install-the-snap.md @@ -59,13 +59,14 @@ Replacing the placeholder variables with their appropriate values. When the configuration is complete, you’ll receive confirmation that the client was registered successfully or if an error occurred. -**Method #3: Use `set` to set individual configuration values** +**Method #3: Use `snap set` to set individual configuration values** -You can use the snap `set` command to set individual configuration values. For example: +You can use the `snap set` command to set individual configuration values. For example: ```bash snap set landscape-client computer-title {LANDSCAPE_COMPUTER_TITLE} -snap set landscape-client url {LANDSCAPE_URL} +snap set landscape-client url https://{LANDSCAPE_FQDN}/message-system +snap set landscape-client ping-url http://{LANDSCAPE_FQDN}/ping ``` After setting any configuration variables using `set`, you’ll need to restart the client snap for the new configuration to be applied: @@ -78,7 +79,8 @@ The options you can set with snap `set` are: - `account-name` - `computer-title` -- `landscape-url` +- `url` +- `ping-url` - `log-level` - `script-users` - `manager-plugins` @@ -86,6 +88,14 @@ The options you can set with snap `set` are: - `access-group` - `registration-key` +```{note} +When you run `snap set`, the value is written to snap options and then applied to `landscape-client.conf` by the `configure` hook. Only the keys listed above are recognized and applied. If you set an unrecognized key, it will not be written to the configuration file but will persist in snap options, which can be misleading. Use `snap unset landscape-client ` to remove it. +``` + +```{note} +The keys `landscape-url` and `landscape-ping-url` are deprecated aliases for `url` and `ping-url`. They still work but will be removed in a future release. Use `url` and `ping-url` for new configurations. +``` + ### Accept the registration ```{note} diff --git a/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-client.md b/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-client.md index 7d95074b..27bea3ed 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-client.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-client.md @@ -26,18 +26,18 @@ Landscape Client is available in Ubuntu's `main` repository in all [Ubuntu relea 1. Set environment variables: ```bash - LANDSCAPE_ACCOUNT_NAME='' - LANDSCAPE_FQDN='' - LANDSCAPE_COMPUTER_TITLE='' + LANDSCAPE_ACCOUNT_NAME='{LANDSCAPE_ACCOUNT_NAME}' + LANDSCAPE_FQDN='{LANDSCAPE_FQDN}' + LANDSCAPE_COMPUTER_TITLE='{LANDSCAPE_COMPUTER_TITLE}' ``` This code block includes the following values which must be changed: - ``: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. + `{LANDSCAPE_ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. - ``: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. + `{LANDSCAPE_FQDN}`: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. - ``: The name of the computer you're installing Landscape Client on. You choose this name. + `{LANDSCAPE_COMPUTER_TITLE}`: The name of the computer you're installing Landscape Client on. You choose this name. 1. Configure: @@ -57,13 +57,13 @@ To install Landscape Client from a PPA: sudo apt update && sudo apt install -y software-properties-common ``` -1. Add the PPA, replacing `` with the appropriate repository: +1. Add the PPA, replacing `{LANDSCAPE_PPA}` with the appropriate repository: ```bash - sudo add-apt-repository -y + sudo add-apt-repository -y {LANDSCAPE_PPA} ``` - - ``: The PPA for the specific Landscape installation you're using. The PPA for the most recent Landscape LTS is: `ppa:landscape/self-hosted-24.04`. The PPA for Landscape's stable rolling release is: `ppa:landscape/latest-stable`. We recommend using an LTS for production deployments. + - `{LANDSCAPE_PPA}`: The PPA for the specific Landscape installation you're using. The PPA for the most recent Landscape LTS is: `ppa:landscape/self-hosted-24.04`. The PPA for Landscape's stable rolling release is: `ppa:landscape/latest-stable`. We recommend using an LTS for production deployments. 1. Install the `landscape-client` package: @@ -74,18 +74,18 @@ To install Landscape Client from a PPA: 1. Set environment variables: ```bash - LANDSCAPE_ACCOUNT_NAME='' - LANDSCAPE_FQDN='' - LANDSCAPE_COMPUTER_TITLE='' + LANDSCAPE_ACCOUNT_NAME='{LANDSCAPE_ACCOUNT_NAME}' + LANDSCAPE_FQDN='{LANDSCAPE_FQDN}' + LANDSCAPE_COMPUTER_TITLE='{LANDSCAPE_COMPUTER_TITLE}' ``` This code block includes the following values which must be changed: - ``: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. + `{LANDSCAPE_ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. - ``: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. + `{LANDSCAPE_FQDN}`: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. - ``: The name of the computer you're installing Landscape Client on. You choose this name. + `{LANDSCAPE_COMPUTER_TITLE}`: The name of the computer you're installing Landscape Client on. You choose this name. 1. Configure: @@ -102,15 +102,15 @@ This method is suitable when using charmed operators. To install Landscape Clien 1. Set environment variables: ```bash - LANDSCAPE_ACCOUNT_NAME='' - LANDSCAPE_FQDN='' + LANDSCAPE_ACCOUNT_NAME='{LANDSCAPE_ACCOUNT_NAME}' + LANDSCAPE_FQDN='{LANDSCAPE_FQDN}' ``` This code block includes the following values which must be changed: - ``: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. + `{LANDSCAPE_ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. - ``: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. + `{LANDSCAPE_FQDN}`: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should set this to `landscape.canonical.com`. 1. Deploy the charm: @@ -144,19 +144,19 @@ This method is suitable if it's available during a machine's provisioning stage. ```yaml landscape: client: - account_name: "" - computer_title: "" - url: "https:///message-system" - ping_url: "http:///ping" + account_name: "{LANDSCAPE_ACCOUNT_NAME}" + computer_title: "{LANDSCAPE_COMPUTER_TITLE}" + url: "https://{LANDSCAPE_FQDN}/message-system" + ping_url: "http://{LANDSCAPE_FQDN}/ping" ``` This code block includes the following values which must be changed: - ``: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. + `{LANDSCAPE_ACCOUNT_NAME}`: Self-hosted Landscape users should set this to `standalone`. Landscape SaaS users should specify the name of their Landscape SaaS account. - ``: The name of the computer you're installing Landscape Client on. You choose this name. + `{LANDSCAPE_COMPUTER_TITLE}`: The name of the computer you're installing Landscape Client on. You choose this name. - ``: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should omit `url` and `ping_url`. + `{LANDSCAPE_FQDN}`: Self-hosted Landscape users should set this to the FQDN used during their Landscape Server installation. Landscape SaaS users should omit `url` and `ping_url`. For additional information, see the [cloud-init Landscape module documentation](https://cloudinit.readthedocs.io/en/latest/reference/modules.html#landscape). @@ -173,18 +173,18 @@ The snap is generally used for Ubuntu Core devices. You can install the Landscap (howto-heading-register-client-self-signed-certificate)= ## Register a client machine on a self-hosted server with a self-signed certificate -If your self-hosted Landscape server uses a self-signed certificate, you'll need to download the server certificate to the client before registration. Replace `` with the FQDN or IP address of your server. +If your self-hosted Landscape server uses a self-signed certificate, you'll need to download the server certificate to the client before registration. Replace `{LANDSCAPE_FQDN}` with the FQDN or IP address of your server. Download the server certificate: ```bash -echo -n | openssl s_client -connect :443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee /etc/landscape/server.pem +echo -n | openssl s_client -connect {LANDSCAPE_FQDN}:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee /etc/landscape/server.pem ``` Then register the client: ```bash -sudo landscape-config --computer-title "My client" --account-name standalone --url https:///message-system --ping-url http:///ping +sudo landscape-config --computer-title "My client" --account-name standalone --url https://{LANDSCAPE_FQDN}/message-system --ping-url http://{LANDSCAPE_FQDN}/ping ``` If you used a custom CA, you'll need to pass the `--ssl-public-key` parameter pointing to the CA file so that the client can recognize the issuer of the server certificate. diff --git a/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment.md b/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment.md index 38982ec7..ba81b22c 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment.md @@ -111,10 +111,10 @@ The `secure_id` can be listed with a given user email invitation in the database You can generate the invite URL(s) in the following format: ```text -https:///accept-invitation/ +https://{LANDSCAPE_FQDN}/accept-invitation/{SECURE_ID} ``` -Replace `` with the URL of your Landscape server, and `` with the value from the database query. +Replace `{LANDSCAPE_FQDN}` with the FQDN of your Landscape server, and `{SECURE_ID}` with the value from the database query. ### Accept the invitation diff --git a/docs/how-to-guides/repository-mirrors/manage-repositories-with-the-api.md b/docs/how-to-guides/repository-mirrors/manage-repositories-with-the-api.md index 3ed1f97c..0ecf9295 100644 --- a/docs/how-to-guides/repository-mirrors/manage-repositories-with-the-api.md +++ b/docs/how-to-guides/repository-mirrors/manage-repositories-with-the-api.md @@ -79,7 +79,7 @@ Note: the secret key must NOT have a passphrase. To remove the passphrase from a gpg --edit-key A1234B5678C9101112D12141516E17181920FGH0 ``` -See the [gpg](http://manpages.ubuntu.com/cgi-bin/search.py?q=gpg) man page for more details. +See the [gpg](https://manpages.ubuntu.com/manpages/resolute/man1/gpg.1.html) man page for more details. List the keys: @@ -234,7 +234,7 @@ At the end of this activity, all computers that have the `example-tag` will get ```bash deb http://your-server.com/repository/standalone/ubuntu bionic-security main restricted universe multiverse -deb http://your-server.com/repository/standalone/ubuntu bionic main restricted universe multiverse +deb http://your-server.com/repository/standalone/ubuntu bionic main restricted universe multiverse deb http://your-server.com/repository/standalone/ubuntu bionic-updates main restricted universe multiverse ``` @@ -322,7 +322,7 @@ The `%(lds)s` bit will be replaced by whatever follows the `lds:` prefix in the ```text my-package (1.0-0ubuntu1) bionic-staging; urgency=low - * Released 1.0 + * Released 1.0 -- Package Builder Tue, 12 Feb 2023 14:57:05 -0300 (...) ``` @@ -451,7 +451,7 @@ landscape-api create-pocket \ security bionic ubuntu \ main,restricted,universe,multiverse amd64 mirror mirror-key \ --mirror-suite bionic-security \ - --mirror-uri http://archive.ubuntu.com/ubuntu/ + --mirror-uri http://archive.ubuntu.com/ubuntu/ ``` The specific suffix is not significant. You could theoretically choose a different convention for pocket names, but we suggest you stick to this usage. Once you've created the pocket or pockets you want to use, call `sync-mirror-pocket` to start the mirroring process: diff --git a/docs/how-to-guides/ubuntu-pro/enable-landscape.md b/docs/how-to-guides/ubuntu-pro/enable-landscape.md index 4b5cdcb4..d0cbb296 100644 --- a/docs/how-to-guides/ubuntu-pro/enable-landscape.md +++ b/docs/how-to-guides/ubuntu-pro/enable-landscape.md @@ -33,7 +33,7 @@ This command will install `landscape-client` and start up an interactive wizard ## Enable non-interactively -If you know the details of your Landscape setup then you can register a machine without using the wizard. Under the hood, ``pro`` installs and executes `landscape-config`, so you can pass any [parameters supported by](https://manpages.ubuntu.com/manpages/noble/en/man1/landscape-config.1.html) `landscape-config` to `pro enable landscape`. +If you know the details of your Landscape setup then you can register a machine without using the wizard. Under the hood, ``pro`` installs and executes `landscape-config`, so you can pass any [parameters supported by](https://manpages.ubuntu.com/manpages/resolute/man1/landscape-config.1.html) `landscape-config` to `pro enable landscape`. You can use the `--assume-yes` flag to automatically accept the defaults for any un-provided parameters.