From cbbbb35e0baa8c23f0c0d50c37881055d7e73339 Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Thu, 22 May 2025 18:48:08 -0500 Subject: [PATCH 001/187] adding ci to sync from public --- .github/workflows/sync-from-public-docs.yaml | 29 ++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 .github/workflows/sync-from-public-docs.yaml diff --git a/.github/workflows/sync-from-public-docs.yaml b/.github/workflows/sync-from-public-docs.yaml new file mode 100644 index 00000000..7bc9654c --- /dev/null +++ b/.github/workflows/sync-from-public-docs.yaml @@ -0,0 +1,29 @@ +# .github/workflows/sync-from-public.yml +name: Sync from Public Repo + +on: + repository_dispatch: + types: [sync-public-main] + +jobs: + sync-public: + runs-on: ubuntu-latest + steps: + - name: Checkout private staging repo + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + ref: main + + - name: Add public repo as upstream and merge + run: | + git remote add upstream https://github.com/canonical/landscape-documentation.git + git fetch upstream + git merge upstream/main --no-edit + git push origin main + + - name: Merge main into develop + run: | + git checkout develop + git merge main --no-edit + git push origin develop From 53fac0326714f234b72ba5dec8b2e53f3ed6feb1 Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Wed, 28 May 2025 17:25:42 -0500 Subject: [PATCH 002/187] add descriptive commit messages --- .github/workflows/sync-from-public-docs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/sync-from-public-docs.yaml b/.github/workflows/sync-from-public-docs.yaml index 7bc9654c..8cb5c6ec 100644 --- a/.github/workflows/sync-from-public-docs.yaml +++ b/.github/workflows/sync-from-public-docs.yaml @@ -19,11 +19,11 @@ jobs: run: | git remote add upstream https://github.com/canonical/landscape-documentation.git git fetch upstream - git merge upstream/main --no-edit + git merge upstream/main -m "merge: sync from public docs" git push origin main - name: Merge main into develop run: | git checkout develop - git merge main --no-edit + git merge main -m "merge: sync from main" git push origin develop From f204218bdb621cb408c04fe803d8cf1c74748279 Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Thu, 29 May 2025 16:59:18 -0500 Subject: [PATCH 003/187] adjust configs --- .github/workflows/sync-from-public-docs.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sync-from-public-docs.yaml b/.github/workflows/sync-from-public-docs.yaml index 8cb5c6ec..c6218873 100644 --- a/.github/workflows/sync-from-public-docs.yaml +++ b/.github/workflows/sync-from-public-docs.yaml @@ -14,12 +14,13 @@ jobs: with: token: ${{ secrets.GITHUB_TOKEN }} ref: main + fetch-depth: '0' - name: Add public repo as upstream and merge run: | git remote add upstream https://github.com/canonical/landscape-documentation.git git fetch upstream - git merge upstream/main -m "merge: sync from public docs" + git merge --allow-unrelated-histories upstream/main -Xtheirs -m "merge: sync from public docs" git push origin main - name: Merge main into develop From e034a9d4be5b9c1f708f8936eea2120b9a10656c Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Thu, 29 May 2025 17:23:57 -0500 Subject: [PATCH 004/187] Add user identity --- .github/workflows/sync-from-public-docs.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/sync-from-public-docs.yaml b/.github/workflows/sync-from-public-docs.yaml index c6218873..fb31d42e 100644 --- a/.github/workflows/sync-from-public-docs.yaml +++ b/.github/workflows/sync-from-public-docs.yaml @@ -18,6 +18,8 @@ jobs: - name: Add public repo as upstream and merge run: | + git config user.name "landscape-github-actions[bot]" + git config user.email "landscape-github-actions[bot]@users.noreply.github.com" git remote add upstream https://github.com/canonical/landscape-documentation.git git fetch upstream git merge --allow-unrelated-histories upstream/main -Xtheirs -m "merge: sync from public docs" From 3a9f50061f13c3a30936f7a40759dd0c8a556e4d Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Thu, 29 May 2025 17:47:23 -0500 Subject: [PATCH 005/187] add config to ignore .github --- .github/workflows/sync-from-public-docs.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sync-from-public-docs.yaml b/.github/workflows/sync-from-public-docs.yaml index fb31d42e..270bb1dc 100644 --- a/.github/workflows/sync-from-public-docs.yaml +++ b/.github/workflows/sync-from-public-docs.yaml @@ -22,7 +22,9 @@ jobs: git config user.email "landscape-github-actions[bot]@users.noreply.github.com" git remote add upstream https://github.com/canonical/landscape-documentation.git git fetch upstream - git merge --allow-unrelated-histories upstream/main -Xtheirs -m "merge: sync from public docs" + git merge --allow-unrelated-histories upstream/main -Xtheirs --no-commit + git restore --staged .github + git commit -m "merge: sync from public docs" git push origin main - name: Merge main into develop From 7d54089f142a121e97513897e46e6fde0761c79d Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 11 Jun 2025 11:43:53 -0700 Subject: [PATCH 006/187] feat: add docs for child instance profiles --- README.md | 2 +- .../api/legacy-api-endpoints/index.md | 3 +- .../child-instance-profiles.md | 302 ++++++++++++ .../reference/api/rest-api-endpoints/index.md | 3 +- docs/reference/api/rest-api-endpoints/wsl.md | 440 +++++++++--------- 5 files changed, 518 insertions(+), 232 deletions(-) create mode 100644 docs/reference/api/rest-api-endpoints/child-instance-profiles.md diff --git a/README.md b/README.md index c3bd022f..11db5075 100644 --- a/README.md +++ b/README.md @@ -28,4 +28,4 @@ Landscape is a member of the Ubuntu family. It welcomes community contributions, * [Get support](https://ubuntu.com/support/community-support) * [Join the Discourse forum](https://discourse.ubuntu.com/c/landscape/89) -Thinking about using Landscape for your next project? [Get in touch!](https://ubuntu.com/landscape#get-in-touch) \ No newline at end of file +Thinking about using Landscape for your next project? [Get in touch!](https://ubuntu.com/landscape#get-in-touch) diff --git a/docs/reference/api/legacy-api-endpoints/index.md b/docs/reference/api/legacy-api-endpoints/index.md index 73c3ed0c..2ea80cd9 100644 --- a/docs/reference/api/legacy-api-endpoints/index.md +++ b/docs/reference/api/legacy-api-endpoints/index.md @@ -1,4 +1,5 @@ (reference-api-legacy-api-endpoints-index)= + # Legacy API endpoints ```{toctree} @@ -6,4 +7,4 @@ :maxdepth: 2 :glob: -* \ No newline at end of file +* diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md new file mode 100644 index 00000000..c21b66a9 --- /dev/null +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -0,0 +1,302 @@ +(reference-rest-api-child-instance-profiles)= + +# Child Instance Profiles + +```{note} +Child Instance Profiles are in beta testing. The API endpoints below may not be available to all accounts. +``` + +## GET `/child-instance-profile-types` + +Returns a list of the child instance profile types supported by Landscape. Currently, only WSL Child Instance Profiles are supported. + +Required parameters: + +- None + +Optional parameters: + +- None + +Example request: + +```bash +curl -X GET -H "Authorization: Bearer $JWT" "https://landscape.canonical.com/api/v2/child-instance-profile-types" +``` + +Example output: + +```json +{ + "results": [ + { + "name": "wsl", + "title": "WSL" + } + ] +} +``` + +## GET `/child-instance-profiles` + +Gets a list of child instance profiles. + +Required parameters: + +- none + +Optional parameters: + +- `limit`: The maximum number of results returned by the method. It defaults to 1000. +- `offset`: The offset inside the list of results. + +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" +``` + +Example output: + +```json +{ + "count": 1, + "results": [ + { + "id": 2, + "name": "stock-ubuntu-2404", + "title": "Stock Ubuntu 24.04", + "instance_type": "WSL", + "description": "The image from the store", + "image_name": "Ubuntu-24.04", + "image_source": null, + "cloud_init_contents": null, + "cloud_init_secret_name": null, + "tags": [ + "windows_desktops", + "windows_laptops" + ], + "all_computers": false, + "access_group": "global", + "computers": { + "constrained": [2, 3, 4, 5], + "non-compliant": [3, 5], + "pending": [4] + } + } + ], + "next": null, + "previous": null +} +``` + +## POST `/child-instance-profiles` + +Creates a child instance profile. + +Required parameters: + +- `title`: A title for the profile. +- `description`: A human readable description for the profile. +- `image_name`: The name of the WSL image to use (e.g. `Ubuntu-24.04`). + +Optional parameters: + +- `image_source`: The URL or file path for the rootfs image. +- `cloud_init_contents`: The base64-encoded cloud init file contents. +- `access_group`: Optional name of the access group to create the profile under; defaults to Global Access. +- `tags`: A comma separated string of tag names to associate with the profile. +- `all_computers`: If true, this profile will be associated with all computers; defaults to false. + +Example requests: + +```bash +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Stock Ubuntu 24.04", "description": "The image from the store", "image_name": "Ubuntu-24.04", "tags": "windows_laptops,windows_desktops"}' + +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d "{\"title\": \"Customized Ubuntu 24.04\", \"description\": \"The image from the store customized\", \"image_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < cloud_init.yaml)\"}" + +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Custom Rootfs Image", "description": "My custom image", "image_name": "CustomUbuntu", "image_source": "https://example.com/myimage.tar.gz"}' +``` + +Example output: + +```json +{ + "id": 2, + "name": "customized-ubuntu-2404", + "title": "Customized Ubuntu 24.04", + "instance_type": "WSL", + "description": "The image from the store customized", + "image_name": "Ubuntu-24.04", + "image_source": null, + "cloud_init_contents": "********", + "cloud_init_secret_name": null, + "tags": [ + "windows_desktops", + "windows_laptops" + ], + "all_computers": false, + "access_group": "global", + "computers": { + "constrained": [2, 3, 4, 5], + "non-compliant": [], + "pending": [2, 3, 4, 5] + } +} +``` + +## DELETE `/child-instance-profiles/` + +Delete the specified child instance profile. + +Required parameters: + +- none + +Optional parameters: + +- none + +Example request: + +```bash +curl -X DELETE https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" +``` + +Example output: + +Empty response. + +## GET `/child-instance-profiles/` + +Get details of the specified child instance profile. + +Required parameters: + +- none + +Optional parameters: + +- none + +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" +``` + +Example output: + +```json +{ + "id": 2, + "name": "stock-ubuntu-2404", + "title": "Stock Ubuntu 24.04", + "instance_type": "WSL", + "description": "The image from the store", + "image_name": "Ubuntu-24.04", + "image_source": null, + "cloud_init_contents": null, + "cloud_init_secret_name": null, + "tags": [ + "windows_desktops", + "windows_laptops" + ], + "all_computers": false, + "access_group": "global", + "computers": { + "constrained": [2, 3, 4, 5], + "non-compliant": [3, 5], + "pending": [4] + } +} +``` + +## PATCH `/child-instance-profiles/` + +Edit a child instance profile. + +Required parameters: + +- None. + +Optional parameters: + +- `title`: A title for the profile. +- `description`: A human readable description for the profile. +- `access_group`: Name of the access group for the profile under. +- `tags`: A comma separated string of tag names to associate with the profile. +- `all_computers`: Whether or not to associate this profile with all computers. + +Example request: + +```bash +curl -X PATCH https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -d '{"description": "The stock image from the store", "tags": "windows_laptops"}' +``` + +Example output: + +```json +{ + "id": 2, + "name": "stock-ubuntu-2404", + "title": "Stock Ubuntu 24.04", + "instance_type": "WSL", + "description": "The stock image from the store", + "image_name": "Ubuntu-24.04", + "image_source": null, + "cloud_init_contents": null, + "cloud_init_secret_name": null, + "tags": [ + "windows_laptops" + ], + "all_computers": false, + "access_group": "global", + "computers": { + "constrained": [2, 3, 4, 5], + "non-compliant": [3, 5], + "pending": [4] + } +} +``` + +## POST `/child-instance-profiles/:reapply` + +Reapply a Child Instance Profile to host machines to make them compliant. + +Required parameters: + +- None + +Optional parameters: + +- `computer_ids`: A list of ids of the host instances to reapply the profile to. These instances must be associated with the profile. If the parameter is omitted, the profile will be reapplied to all non-compliant hosts. + +Example request: + +```bash +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404:reapply -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1,2,3]}' +``` + +Example response: + +```json + +{ + "id": 118, + "creation_time": "2024-08-05T16:38:52Z", + "creator": { + "name": "John Smith", + "email": "john@example.com", + "id": 1 + }, + "type": "ActivityGroup", + "summary": "Reapply profile Stock Ubuntu 24.04", + "completion_time": null, + "parent_id": null, + "deliver_delay_window": 0, + "result_text": null, + "result_code": null, + "activity_status": "delivered" +} +``` diff --git a/docs/reference/api/rest-api-endpoints/index.md b/docs/reference/api/rest-api-endpoints/index.md index 12df8753..1fe682c1 100644 --- a/docs/reference/api/rest-api-endpoints/index.md +++ b/docs/reference/api/rest-api-endpoints/index.md @@ -1,4 +1,5 @@ (reference-api-rest-api-endpoints-index)= + # Rest API endpoints ```{toctree} @@ -6,4 +7,4 @@ :maxdepth: 2 :glob: -* \ No newline at end of file +* diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 9490e145..9bf0cccf 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -1,228 +1,11 @@ (reference-rest-api-wsl)= -# WSL - -## GET `/child-instance-profiles` - -Gets a list of child instance profiles. - -Required parameters: - -- none - -Optional parameters: - -- `limit`: The maximum number of results returned by the method. It defaults to 1000. -- `offset`: The offset inside the list of results. - -Example request: - -```bash -curl -X GET https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -``` - -Example output: - -```text -{ - "count": 1, - "results": [ - { - "id": 2, - "name": "stock-ubuntu-2404", - "title": "Stock Ubuntu 24.04", - "instance_type": "WSL", - "description": "The image from the store", - "image_name": "Ubuntu-24.04", - "image_source": null, - "cloud_init_contents": null, - "cloud_init_secret_name": null, - "tags": [ - "windows_desktops", - "windows_laptops" - ], - "all_computers": false, - "access_group": "global", - "computers": { - "constrained": [2, 3, 4, 5], - "non-compliant": [3, 5], - "pending": [4] - } - } - ], - "next": null, - "previous": null -} -``` - -## POST `/child-instance-profiles` - -Creates a child instance profile. - -Required parameters: - -- `title`: A title for the profile. -- `description`: A human readable description for the profile. -- `image_name`: The name of the WSL image to use (e.g. `Ubuntu-24.04`). - -Optional parameters: - -- `image_source`: The URL or file path for the rootfs image. -- `cloud_init_contents`: The base64-encoded cloud init file contents. -- `access_group`: Optional name of the access group to create the profile under; defaults to Global Access. -- `tags`: A comma separated string of tag names to associate with the profile. -- `all_computers`: If true, this profile will be associated with all computers; defaults to false. - -Example requests: - -```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Stock Ubuntu 24.04", "description": "The image from the store", "image_name": "Ubuntu-24.04", "tags": "windows_laptops,windows_desktops"}' - -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d "{\"title\": \"Customized Ubuntu 24.04\", \"description\": \"The image from the store customized\", \"image_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < cloud_init.yaml)\"}" - -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Custom Rootfs Image", "description": "My custom image", "image_name": "CustomUbuntu", "image_source": "https://example.com/myimage.tar.gz"}' -``` - -Example output: - -```text -{ - "id": 2, - "name": "customized-ubuntu-2404", - "title": "Customized Ubuntu 24.04", - "instance_type": "WSL", - "description": "The image from the store customized", - "image_name": "Ubuntu-24.04", - "image_source": null, - "cloud_init_contents": "********", - "cloud_init_secret_name": null, - "tags": [ - "windows_desktops", - "windows_laptops" - ], - "all_computers": false, - "access_group": "global", - "computers": { - "constrained": [2, 3, 4, 5], - "non-compliant": [], - "pending": [2, 3, 4, 5] - } -} -``` - -## DELETE `/child-instance-profiles/` - -Delete the specified child instance profile. - -Required parameters: - -- none - -Optional parameters: - -- none - -Example request: - -```bash -curl -X DELETE https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -``` - -Example output: - -Empty response. - -## GET `/child-instance-profiles/` - -Get details of the specified child instance profile. - -Required parameters: - -- none - -Optional parameters: - -- none - -Example request: - -```bash -curl -X GET https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -``` - -Example output: - -```text -{ - "id": 2, - "name": "stock-ubuntu-2404", - "title": "Stock Ubuntu 24.04", - "instance_type": "WSL", - "description": "The image from the store", - "image_name": "Ubuntu-24.04", - "image_source": null, - "cloud_init_contents": null, - "cloud_init_secret_name": null, - "tags": [ - "windows_desktops", - "windows_laptops" - ], - "all_computers": false, - "access_group": "global", - "computers": { - "constrained": [2, 3, 4, 5], - "non-compliant": [3, 5], - "pending": [4] - } -} -``` -## PATCH `/child-instance-profiles/` - -Edit a child instance profile. - -Required parameters: - -- None. - -Optional parameters: - -- `title`: A title for the profile. -- `description`: A human readable description for the profile. -- `access_group`: Name of the access group for the profile under. -- `tags`: A comma separated string of tag names to associate with the profile. -- `all_computers`: Whether or not to associate this profile with all computers. - -Example requests: +# WSL -```bash -curl -X PATCH https://your-landscape.domain.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -d '{"description": "The stock image from the store", "tags": "windows_laptops"}' +```{note} +WSL features are in beta testing. The API endpoints below may not be available to all accounts. ``` -Example output: - -```text -{ - "id": 2, - "name": "stock-ubuntu-2404", - "title": "Stock Ubuntu 24.04", - "instance_type": "WSL", - "description": "The stock image from the store", - "image_name": "Ubuntu-24.04", - "image_source": null, - "cloud_init_contents": null, - "cloud_init_secret_name": null, - "tags": [ - "windows_laptops" - ], - "all_computers": false, - "access_group": "global", - "computers": { - "constrained": [2, 3, 4, 5], - "non-compliant": [3, 5], - "pending": [4] - } -} -``` ## POST `/computers//children` Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape. @@ -249,7 +32,8 @@ curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H " ``` Example output: -```text + +```json { "id": 118, "creation_time": "2024-08-05T16:38:52Z", @@ -276,7 +60,8 @@ curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H " ``` Example output: -```text + +```json { "id": 118, "creation_time": "2024-08-05T16:38:52Z", @@ -301,9 +86,202 @@ Notes: 1. Sending both `cloud_init` and `data_id` will produce a 400 response. 1. If `rootfs_url` is specified, then a 400 response is returned if the computer name matches any of the following case-insensitive patterns: `Ubuntu`, `Ubuntu-Preview`, `Ubuntu-XY.ZW`. +## POST `/computers//delete-children` + +Create activities to remove the specified child instances from the host. + +Required parameters: + +- `child_names`: A list of names of the child instances to remove. + +Optional parameters: + +- None + +Example request: + +```bash +curl -X POST -H "Authorization: Bearer $JWT" "https://landscape.canonical.com/api/v2/computers/6/delete-children" -d '{"computer_names": ["child_one", "child_two"]}' +``` + +Example output: + +```json +{ + "id": 115, + "deliver_delay_window": 0, + "summary": "Deleting child computer(s)", + "type": "ActivityGroup", + "creator": { + "name": "John Smith", + "email": "john@example.com", + "id": 1 + }, + "activity_status": "undelivered", + "parent_id": null, + "creation_time": "2025-06-10T22:29:22Z", + "approval_time": null, + "completion_time": null, + "result_text": null, + "result_code": null +} +``` + +## GET `/computers/wsl-hosts` + +Gets a list of Windows computers that host at least one WSL instance that is registered in Landscape. + +Required parameters: + +- None + +Optional parameters: + +- `query`: A query string with tokens used to filter the returned result objects. +- `limit`: The maximum number of results returned by the method. It defaults to 1000. +- `offset`: The offset inside the list of results. + +Example request: + +```bash +curl -X GET -H "Authorization: Bearer $JWT" "https://landscape.canonical.com/api/v2/computers/wsl-hosts" +``` + +Example output: + +```json +{ + "count": 1, + "results": [ + { + "id": 6, + "title": "Noel's Windows Laptop", + "comment": "", + "hostname": "noel", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2025-06-10T22:00:30Z", + "tags": [ + "laptop", + "windows" + ], + "access_group": "server", + "distribution": "10 / 11", + "distribution_info": { + "description": "Windows 10 / Windows 11", + "distributor": "Microsoft", + "release": "10 / 11", + "code_name": "windows" + }, + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "default_child": null, + "ubuntu_pro_info": null, + "livepatch_info": null, + "ubuntu_pro_reboot_required_info": null, + "num_child": 2, + "cloud_init": {}, + "archived": false, + "employee_id": null, + "is_wsl_instance": false, + "children": [ + { + "id": 7, + "title": "Bionic WSL", + "comment": "", + "hostname": "bionic-wsl", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2025-06-10T21:59:30Z", + "tags": [ + "bionic", + "wsl" + ], + "access_group": "global", + "distribution": "18.04", + "distribution_info": { + "description": "Ubuntu 18.04 LTS", + "distributor": "Ubuntu", + "release": "18.04", + "code_name": "bionic" + }, + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "default_child": null, + "ubuntu_pro_info": null, + "livepatch_info": null, + "ubuntu_pro_reboot_required_info": null, + "num_child": 0, + "cloud_init": {}, + "archived": false, + "employee_id": null, + "is_wsl_instance": true, + "is_default_child": null + }, + { + "id": 8, + "title": "Focal WSL", + "comment": "", + "hostname": "focal-wsl", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2025-06-10T21:58:30Z", + "tags": [ + "focal", + "wsl" + ], + "access_group": "global", + "distribution": "20.04", + "distribution_info": { + "description": "Ubuntu 20.04 LTS", + "distributor": "Ubuntu", + "release": "20.04", + "code_name": "focal" + }, + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "default_child": null, + "ubuntu_pro_info": null, + "livepatch_info": null, + "ubuntu_pro_reboot_required_info": null, + "num_child": 0, + "cloud_init": {}, + "archived": false, + "employee_id": null, + "is_wsl_instance": true, + "is_default_child": null + } + ], + "is_default_child": null, + "parent": null + } + ], + "next": null, + "previous": null +} +``` + ## GET `/wsl-instance-names` -Gets a listing of valid WSL image names. +Gets a listing of image names for the official Ubuntu WSL images available in the Windows Store. Required parameters: @@ -320,16 +298,20 @@ curl -X GET -H "Authorization: Bearer $JWT" "https://landscape.canonical.com/api ``` Example output: -```bash + +```json [ { - "name": "Ubuntu", - "label": "Ubuntu" + "name": "Ubuntu", + "label": "Ubuntu" }, { - "name": "Ubuntu-22.04", - "label": "Ubuntu 22.04" + "name": "Ubuntu-22.04", + "label": "Ubuntu 22.04 LTS" + }, + { + "name": "Ubuntu-24.04", + "label": "Ubuntu 24.04 LTS" } ] ``` - From 593f1ee37cba8bc8bb3ad79742956d552c07b69d Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 16 Jun 2025 11:55:25 -0700 Subject: [PATCH 007/187] update from feedback --- .../child-instance-profiles.md | 16 ++++++++-------- docs/reference/api/rest-api-endpoints/wsl.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md index c21b66a9..d9649698 100644 --- a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -104,14 +104,14 @@ Optional parameters: - `image_source`: The URL or file path for the rootfs image. - `cloud_init_contents`: The base64-encoded cloud init file contents. -- `access_group`: Optional name of the access group to create the profile under; defaults to Global Access. -- `tags`: A comma separated string of tag names to associate with the profile. +- `access_group`: Name of the access group the profile applies to; defaults to Global Access. +- `tags`: A list of tag names to associate with the profile. - `all_computers`: If true, this profile will be associated with all computers; defaults to false. Example requests: ```bash -curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Stock Ubuntu 24.04", "description": "The image from the store", "image_name": "Ubuntu-24.04", "tags": "windows_laptops,windows_desktops"}' +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "Stock Ubuntu 24.04", "description": "The image from the store", "image_name": "Ubuntu-24.04", "tags": ["windows_laptops", "windows_desktops"]}' curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d "{\"title\": \"Customized Ubuntu 24.04\", \"description\": \"The image from the store customized\", \"image_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < cloud_init.yaml)\"}" @@ -145,7 +145,7 @@ Example output: } ``` -## DELETE `/child-instance-profiles/` +## DELETE `/child-instance-profiles/` Delete the specified child instance profile. @@ -167,7 +167,7 @@ Example output: Empty response. -## GET `/child-instance-profiles/` +## GET `/child-instance-profiles/` Get details of the specified child instance profile. @@ -225,13 +225,13 @@ Optional parameters: - `title`: A title for the profile. - `description`: A human readable description for the profile. - `access_group`: Name of the access group for the profile under. -- `tags`: A comma separated string of tag names to associate with the profile. +- `tags`: A list of tag names to associate with the profile. - `all_computers`: Whether or not to associate this profile with all computers. Example request: ```bash -curl -X PATCH https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -d '{"description": "The stock image from the store", "tags": "windows_laptops"}' +curl -X PATCH https://landscape.canonical.com/api/v2/child-instance-profiles/stock-ubuntu-2404 -H "Authorization: Bearer $JWT" -d '{"description": "The stock image from the store", "tags": ["windows_laptops"]}' ``` Example output: @@ -260,7 +260,7 @@ Example output: } ``` -## POST `/child-instance-profiles/:reapply` +## POST `/child-instance-profiles/:reapply` Reapply a Child Instance Profile to host machines to make them compliant. diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 9bf0cccf..0847db9a 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -137,7 +137,7 @@ Required parameters: Optional parameters: -- `query`: A query string with tokens used to filter the returned result objects. +- `query`: A query string with tokens used to filter the returned result objects. See {ref}`reference-rest-api-computers` for details. - `limit`: The maximum number of results returned by the method. It defaults to 1000. - `offset`: The offset inside the list of results. From 34d6eca6ff335d26156c674efabfb440f49d4ad8 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 17 Jun 2025 12:19:23 -0700 Subject: [PATCH 008/187] feat: add documentation for searching by profile type --- .../api/rest-api-endpoints/computers.md | 545 +++++++++++------- 1 file changed, 324 insertions(+), 221 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 2dc2a3db..84089c2d 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -1,9 +1,10 @@ (reference-rest-api-computers)= + # Computers ## GET `/computers` -Get information on a list of computers associated with the account. +Get information on a list of computers associated with the account. Path parameters: @@ -26,6 +27,9 @@ Query parameters: - `license-id`: Search for computers licensed to the specified `license-id`. - `needs:license` OR `license-id:none`: Search for computers that do not have a Landscape license, and, as a result, are not managed. - `annotation`: Search for computers which define the specified annotation key. Optionally specify `annotation::` which will only return computers whose key matches and value also contains the `` specified. + - `profile::`: Instances associated with the specified profile. The `` must be one of `security`, `script`, `repository`, `package`, `upgrade`, `reboot`, `removal`, or `wsl`. The `` is the database id of the profile. + - `profile:security::`: Instances associated with the specified USG security profile with the indicated last audit result. The `` is the database id of the profile. The `` must be one of `pass`, `fail`, or `in-progress`. + - `profile:wsl::`: Instances associated with the specified WSL Child Instance Profile. The `` is the database id of the profile. The `` must either be `compliant` or `noncompliant`. - `OR`: Search for computers matching term A or term B. `OR` must be in all-caps. - `NOT`: search for computers not matching the next term. `NOT` must be in all-caps. - `limit`: The maximum number of results returned by the method. It defaults to 1000. @@ -35,43 +39,45 @@ Query parameters: - `with_annotations`: If true, include the details of all custom annotation information known. Example request: + ```bash curl -X GET https://landscape.canonical.com/api/v2/computers?limit=1 -H "Authorization: Bearer $JWT" ``` Example output: -```bash + +```json { "count": 13, "results": [ - { - "id": 1, - "title": "Application Server 1", - "comment": "", - "hostname": "appserv1", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:21:41Z", - "tags": [ - "lucid", - "server", - "webfarm" - ], - "access_group": "server", - "distribution": "10.04", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": false, - "children": [], - "parent": null - } + { + "id": 1, + "title": "Application Server 1", + "comment": "", + "hostname": "appserv1", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:21:41Z", + "tags": [ + "lucid", + "server", + "webfarm" + ], + "access_group": "server", + "distribution": "10.04", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": false, + "children": [], + "parent": null + } ], "next": "https://landscape.canonical.com/api/v2/computers?limit=1&offset=1", "previous": null @@ -79,13 +85,14 @@ Example output: ``` Example request: + ```bash curl -X GET https://landscape.canonical.com/api/v2/computers?query=id:1%20OR%20id:2 -H "Authorization: Bearer $JWT" -H "Authorization: Bearer $JWT" ``` Example output: -```bash +```json { "count": 2, "results": [ @@ -153,12 +160,107 @@ Example output: "next": null, "previous": null } +``` +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/computers/?query=profile:wsl:1:compliant -H "Authorization: Bearer $JWT" +``` + +Example output: + +```json +{ + "count": 1, + "results": [ + { + "id": 6, + "title": "Jane's Windows Laptop", + "comment": "", + "hostname": "jane", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:16:41Z", + "tags": [ + "laptop", + "windows" + ], + "access_group": "server", + "distribution": "10 / 11", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": false, + "children": [ + { + "id": 11, + "title": "Bionic WSL", + "comment": "", + "hostname": "bionic-wsl", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:11:41Z", + "tags": [ + "bionic", + "wsl" + ], + "access_group": "global", + "distribution": "18.04", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": true + }, + { + "id": 12, + "title": "Focal WSL", + "comment": "", + "hostname": "focal-wsl", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:10:41Z", + "tags": [ + "focal", + "wsl" + ], + "access_group": "global", + "distribution": "20.04", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": true + } + ], + "parent": null + } + ], + "next": null, + "previous": null +} ``` ## GET `/computers/` -Get information on a specific computer in the account. +Get information on a specific computer in the account. Path parameters: @@ -179,7 +281,7 @@ curl -X GET https://landscape.canonical.com/api/v2/computers/1?with_grouped_hard Example output: -```text +```json { "id": 1, "title": "Application Server 1", @@ -679,46 +781,46 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/activities?limit=1 Example output: -```bash +```json { "count": 26, "results": [ + { + "id": 143, + "creation_time": "2024-03-01T20:58:14Z", + "creator": { + "name": "John Smith", + "email": "john@example.com", + "id": 1 + }, + "type": "ChangePackagesRequest", + "summary": "Remove package abs-guide", + "result_text": null, + "computer_id": 1, + "approval_time": null, + "delivery_time": null, + "deliver_after_time": null, + "deliver_before_time": null, + "package_ids": [ + 73 + ], + "changes": [ { - "id": 143, - "creation_time": "2024-03-01T20:58:14Z", - "creator": { - "name": "John Smith", - "email": "john@example.com", - "id": 1 - }, - "type": "ChangePackagesRequest", - "summary": "Remove package abs-guide", - "result_text": null, - "computer_id": 1, - "approval_time": null, - "delivery_time": null, - "deliver_after_time": null, - "deliver_before_time": null, - "package_ids": [ - 73 - ], - "changes": [ - { - "package": "abs-guide", - "complemented": false, - "type": "remove", - "version": "10-3" - } - ], - "parent_id": 142, - "modification_time": "2024-03-01T20:58:14Z", - "completion_time": null, - "schedule_before_time": null, - "schedule_after_time": null, - "result_code": null, - "activity_status": "undelivered", - "children": [] + "package": "abs-guide", + "complemented": false, + "type": "remove", + "version": "10-3" } + ], + "parent_id": 142, + "modification_time": "2024-03-01T20:58:14Z", + "completion_time": null, + "schedule_before_time": null, + "schedule_after_time": null, + "result_code": null, + "activity_status": "undelivered", + "children": [] + } ], "next": "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1&offset=1", "previous": null @@ -745,15 +847,40 @@ curl -X GET https://landscape.canonical.com/api/v2/computers/wsl-hosts -H "Autho Example output: -```bash +```json { "count": 1, "results": [ + { + "id": 6, + "title": "Jane's Windows Laptop", + "comment": "", + "hostname": "jane", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:16:41Z", + "tags": [ + "laptop", + "windows" + ], + "access_group": "server", + "distribution": "10 / 11", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": false, + "children": [ { - "id": 6, - "title": "Jane's Windows Laptop", + "id": 11, + "title": "Bionic WSL", "comment": "", - "hostname": "jane", + "hostname": "bionic-wsl", "total_memory": 1024, "total_swap": 1024, "reboot_required_flag": false, @@ -761,72 +888,47 @@ Example output: "clone_id": null, "secrets_name": null, "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:16:41Z", + "last_ping_time": "2024-02-07T21:11:41Z", "tags": [ - "laptop", - "windows" + "bionic", + "wsl" ], - "access_group": "server", - "distribution": "10 / 11", + "access_group": "global", + "distribution": "18.04", "cloud_instance_metadata": {}, "vm_info": null, "container_info": null, "ubuntu_pro_info": null, - "is_wsl_instance": false, - "children": [ - { - "id": 11, - "title": "Bionic WSL", - "comment": "", - "hostname": "bionic-wsl", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:11:41Z", - "tags": [ - "bionic", - "wsl" - ], - "access_group": "global", - "distribution": "18.04", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": true - }, - { - "id": 12, - "title": "Focal WSL", - "comment": "", - "hostname": "focal-wsl", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:10:41Z", - "tags": [ - "focal", - "wsl" - ], - "access_group": "global", - "distribution": "20.04", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": true - } + "is_wsl_instance": true + }, + { + "id": 12, + "title": "Focal WSL", + "comment": "", + "hostname": "focal-wsl", + "total_memory": 1024, + "total_swap": 1024, + "reboot_required_flag": false, + "update_manager_prompt": "normal", + "clone_id": null, + "secrets_name": null, + "last_exchange_time": null, + "last_ping_time": "2024-02-07T21:10:41Z", + "tags": [ + "focal", + "wsl" ], - "parent": null + "access_group": "global", + "distribution": "20.04", + "cloud_instance_metadata": {}, + "vm_info": null, + "container_info": null, + "ubuntu_pro_info": null, + "is_wsl_instance": true } + ], + "parent": null + } ], "next": null, "previous": null @@ -873,7 +975,7 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/23/packages?limit= Example output: -```bash +```json { "count": 92372, "results": [ @@ -918,47 +1020,46 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/22/snaps/installed Example output: -```bash +```json { "count": 4, "results": [ - { - "version": "4.0.9-a29c6f1", - "revision": "24061", - "tracking_channel": "4.0/stable/ubuntu-20.04", - "held_until": null, - "confinement": "strict", - "snap": { - "id": "J60k4GY0HppDwOeW8dZdWc8obX0xujRu", - "name": "lxd", - "publisher": { - "username": "canonical", - "validation": "verified" - }, - "summary": "LXD - container and VM manager" - } + { + "version": "4.0.9-a29c6f1", + "revision": "24061", + "tracking_channel": "4.0/stable/ubuntu-20.04", + "held_until": null, + "confinement": "strict", + "snap": { + "id": "J60k4GY0HppDwOeW8dZdWc8obX0xujRu", + "name": "lxd", + "publisher": { + "username": "canonical", + "validation": "verified" }, - { - "version": "2.61.1", - "revision": "20671", - "tracking_channel": "latest/stable", - "held_until": null, - "confinement": "strict", - "snap": { - "id": "PM2rV4ml8uWu4RDBT8dSGnJUYbevVhc4", - "name": "snapd", - "publisher": { - "username": "canonical", - "validation": "verified" - }, - "summary": "Daemon and tooling that enable snap packages" - } - } + "summary": "LXD - container and VM manager" + } + }, + { + "version": "2.61.1", + "revision": "20671", + "tracking_channel": "latest/stable", + "held_until": null, + "confinement": "strict", + "snap": { + "id": "PM2rV4ml8uWu4RDBT8dSGnJUYbevVhc4", + "name": "snapd", + "publisher": { + "username": "canonical", + "validation": "verified" + }, + "summary": "Daemon and tooling that enable snap packages" + } + } ], "next": "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2&offset=2", "previous": null } - ``` ## GET `/computers//users//groups` @@ -981,21 +1082,22 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/22/users/ubuntu/gr ``` Example output: -```bash + +```json { "groups": [ - { - "id": 1020, - "computer_id": 22, - "gid": 4, - "name": "adm" - }, - { - "id": 1022, - "computer_id": 22, - "gid": 29, - "name": "audio" - }, + { + "id": 1020, + "computer_id": 22, + "gid": 4, + "name": "adm" + }, + { + "id": 1022, + "computer_id": 22, + "gid": 29, + "name": "audio" + }, ] } ``` @@ -1021,32 +1123,32 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/22/processes?limit Example output: -```bash +```json { "count": 84, "results": [ - { - "id": 2551, - "computer_id": 22, - "pid": 1525, - "gid": 1000, - "name": "(sd-pam)", - "state": "S", - "start_time": "2024-02-07T20:26:55Z", - "vm_size": 104024, - "cpu_utilisation": 0 - }, - { - "id": 2552, - "computer_id": 22, - "pid": 1530, - "gid": 1000, - "name": "-bash", - "state": "S", - "start_time": "2024-02-07T20:26:55Z", - "vm_size": 10032, - "cpu_utilisation": 0 - } + { + "id": 2551, + "computer_id": 22, + "pid": 1525, + "gid": 1000, + "name": "(sd-pam)", + "state": "S", + "start_time": "2024-02-07T20:26:55Z", + "vm_size": 104024, + "cpu_utilisation": 0 + }, + { + "id": 2552, + "computer_id": 22, + "pid": 1530, + "gid": 1000, + "name": "-bash", + "state": "S", + "start_time": "2024-02-07T20:26:55Z", + "vm_size": 10032, + "cpu_utilisation": 0 + } ], "next": "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2&offset=2", "previous": null @@ -1072,12 +1174,14 @@ Optional parameters: - None Example request: + ```bash curl -X POST "https://landscape.canonical.com/api/v2/computers/1/usergroups/update_bulk" -H "Authorization: Bearer $JWT" -d '{"action": "add", "usernames": ["john", "jane"], "groupnames": ["finance", "admin"]}' ``` Example output: -```bash + +```json { "id": 407, "creation_time": "2024-03-21T21:52:12Z", @@ -1112,31 +1216,30 @@ Optional query parameters: Example request: -``` +```bash curl -X POST "https://landscape.canonical.com/api/v2/computers/29/restart" \ - -H "Authorization: Bearer $JWT" \ + -H "Authorization: Bearer $JWT" \ ``` Example response: -``` +```json { - "activity_status": "undelivered", - "approval_time": null, - "completion_time": null, - "creation_time": "2024-11-22T00:01:18Z", - "creator": { - "email": "john@example.com", - "id": 1, - "name": "John Smith" - }, - "deliver_delay_window": 0, - "id": 2225, - "parent_id": null, - "result_code": null, - "result_text": null, - "summary": "Restart computer", - "type": "ActivityGroup" + "activity_status": "undelivered", + "approval_time": null, + "completion_time": null, + "creation_time": "2024-11-22T00:01:18Z", + "creator": { + "email": "john@example.com", + "id": 1, + "name": "John Smith" + }, + "deliver_delay_window": 0, + "id": 2225, + "parent_id": null, + "result_code": null, + "result_text": null, + "summary": "Restart computer", + "type": "ActivityGroup" } ``` - From c86d2e0b586b9662e340854ecd0b1488317036d9 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 17 Jun 2025 16:51:35 -0700 Subject: [PATCH 009/187] feat: update GET /child-instance-profiles parameters --- .../api/rest-api-endpoints/child-instance-profiles.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md index d9649698..6f8796bb 100644 --- a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -47,13 +47,15 @@ Required parameters: Optional parameters: +- `names`: A comma separated list of profile names. The profiles returned will exactly match one of these names. +- `search`: Only profiles with names or descriptions matching the search term are returned. - `limit`: The maximum number of results returned by the method. It defaults to 1000. - `offset`: The offset inside the list of results. Example request: ```bash -curl -X GET https://landscape.canonical.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" +curl -X GET https://landscape.canonical.com/api/v2/child-instance-profiles?search=ubuntu -H "Authorization: Bearer $JWT" ``` Example output: From 2442053bc27630f87cacd1a43ab83ecfae107af3 Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Mon, 23 Jun 2025 18:31:38 -0600 Subject: [PATCH 010/187] add `only_landscape_created` to responses/post req --- docs/reference/api/rest-api-endpoints/wsl.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 9490e145..13b21a5e 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -46,7 +46,8 @@ Example output: "constrained": [2, 3, 4, 5], "non-compliant": [3, 5], "pending": [4] - } + }, + "only_landscape_created": false } ], "next": null, @@ -71,6 +72,8 @@ Optional parameters: - `access_group`: Optional name of the access group to create the profile under; defaults to Global Access. - `tags`: A comma separated string of tag names to associate with the profile. - `all_computers`: If true, this profile will be associated with all computers; defaults to false. +- `only_landscape_created`: If true, delete WSL instances from the associated computers that were not created by Landscape. This cannot be changed and defaults to false. + Example requests: @@ -105,7 +108,8 @@ Example output: "constrained": [2, 3, 4, 5], "non-compliant": [], "pending": [2, 3, 4, 5] - } + }, + "only_landscape_created": false } ``` @@ -172,7 +176,8 @@ Example output: "constrained": [2, 3, 4, 5], "non-compliant": [3, 5], "pending": [4] - } + }, + "only_landscape_created": false } ``` @@ -220,7 +225,8 @@ Example output: "constrained": [2, 3, 4, 5], "non-compliant": [3, 5], "pending": [4] - } + }, + "only_landscape_created": false } ``` ## POST `/computers//children` From 1a02d6336ef446e375c414994c671bc310a9c410 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 24 Jun 2025 12:14:52 -0700 Subject: [PATCH 011/187] feat: add wsl limits endpoint --- docs/reference/api/rest-api-endpoints/wsl.md | 40 ++++++++++++++++++-- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 0847db9a..136c1b09 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -6,6 +6,38 @@ WSL features are in beta testing. The API endpoints below may not be available to all accounts. ``` +## GET `/accounts//wsl_feature_limits` + +Get the limits for WSL related features for the account. + +Path parameters: + +- `name`: The name of the account + +Required parameters: + +- None + +Optional parameters: + +- None + +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/accounts/example-account/wsl_feature_limits -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "max_windows_host_machines": 1000, + "max_wsl_child_instances_per_host": 10, + "max_wsl_child_instance_profiles": 100 +} +``` + ## POST `/computers//children` Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape. @@ -24,11 +56,11 @@ Optional parameters: Example requests: ```bash -curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04"}' +curl -X POST https://landscape.canonical.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04"}' -curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04", "data_id": "data-id", "token": "vault-token"}' +curl -X POST https://landscape.canonical.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Ubuntu-24.04", "data_id": "data-id", "token": "vault-token"}' -curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d "{\"computer_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < ~/cloud_init.yaml)\"}" +curl -X POST https://landscape.canonical.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d "{\"computer_name\": \"Ubuntu-24.04\", \"cloud_init\": \"$(base64 --wrap=0 < ~/cloud_init.yaml)\"}" ``` Example output: @@ -56,7 +88,7 @@ Example output: Example request: ```bash -curl -X POST https://your-landscape.domain.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Custom-WSL-Image", "cloud_init": "", "rootfs_url": "https://example.com/custom_wsl_image.tar.gz"}' +curl -X POST https://landscape.canonical.com/api/v2/computers/20/children -H "Authorization: Bearer $JWT" -d '{"computer_name": "Custom-WSL-Image", "cloud_init": "", "rootfs_url": "https://example.com/custom_wsl_image.tar.gz"}' ``` Example output: From 6a28b7e20f59258ce4d602fee5780189dcb2b828 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 25 Jun 2025 15:26:44 -0700 Subject: [PATCH 012/187] update url, re-sort endpoints --- docs/reference/api/rest-api-endpoints/wsl.md | 64 ++++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 136c1b09..be2f4416 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -6,38 +6,6 @@ WSL features are in beta testing. The API endpoints below may not be available to all accounts. ``` -## GET `/accounts//wsl_feature_limits` - -Get the limits for WSL related features for the account. - -Path parameters: - -- `name`: The name of the account - -Required parameters: - -- None - -Optional parameters: - -- None - -Example request: - -```bash -curl -X GET https://landscape.canonical.com/api/v2/accounts/example-account/wsl_feature_limits -H "Authorization: Bearer $JWT" -``` - -Example response: - -```json -{ - "max_windows_host_machines": 1000, - "max_wsl_child_instances_per_host": 10, - "max_wsl_child_instance_profiles": 100 -} -``` - ## POST `/computers//children` Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape. @@ -311,6 +279,38 @@ Example output: } ``` +## GET `/wsl-feature-limits` + +Get the limits for WSL related features for the account. + +Path parameters: + +- `name`: The name of the account + +Required parameters: + +- None + +Optional parameters: + +- None + +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/wsl-feature-limits -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "max_windows_host_machines": 1000, + "max_wsl_child_instances_per_host": 10, + "max_wsl_child_instance_profiles": 100 +} +``` + ## GET `/wsl-instance-names` Gets a listing of image names for the official Ubuntu WSL images available in the Windows Store. From 61efb55a93f91c12c150f389d767d77cae01d8d6 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Fri, 27 Jun 2025 14:52:27 -0700 Subject: [PATCH 013/187] feat: add docs for with_profiles flag --- .../api/rest-api-endpoints/computers.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 84089c2d..c1249333 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -272,6 +272,85 @@ Query parameters: - `with_grouped_hardware`: If true, include the details of all hardware information known, grouped by hardware type. - `with_hardware`: If true, include the details of all hardware information known. - `with_network`: If true, include the details of all network devices attached to the computer. +- `with_profiles`: If true, include details about all profiles the computer is associated with. + + +Example request: + +```bash +curl -X GET https://landscape.canonical.com/api/v2/computers/1?with_profiles=true -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +{ + "access_group": "server", + "archived": false, + "children": [], + "clone_id": null, + "cloud_init": { + "availability_zone": "us-east-1" + }, + "cloud_instance_metadata": {}, + "comment": "", + "container_info": null, + "default_child": null, + "distribution": "10.04", + "distribution_info": { + "code_name": "lucid", + "description": "Ubuntu 10.04 LTS", + "distributor": "Ubuntu", + "release": "10.04" + }, + "employee_id": null, + "hostname": "appserv1", + "id": 1, + "is_default_child": null, + "is_wsl_instance": false, + "last_exchange_time": null, + "last_ping_time": "2025-06-27T21:17:37Z", + "livepatch_info": null, + "num_child": 0, + "parent": null, + "profiles": [ + { + "id": 7, + "name": "Desktop Packages", + "type": "package" + }, + { + "id": 7, + "name": "Engineering Repos", + "type": "repository" + }, + { + "id": 22, + "name": "One Month Removal", + "type": "removal" + } + { + "id": 4, + "name": "Server Packages", + "type": "package", + }, + ], + "reboot_required_flag": false, + "secrets_name": null, + "tags": [ + "lucid", + "server", + "webfarm" + ], + "title": "Application Server 1", + "total_memory": 1024, + "total_swap": 1024, + "ubuntu_pro_info": null, + "ubuntu_pro_reboot_required_info": null, + "update_manager_prompt": "normal", + "vm_info": null +} +``` Example request: From 4a71159c0f2d380bef007e2c755c4530bd7317f8 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Fri, 27 Jun 2025 14:54:21 -0700 Subject: [PATCH 014/187] remove whitespace --- docs/reference/api/rest-api-endpoints/computers.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index c1249333..ae119a66 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -274,7 +274,6 @@ Query parameters: - `with_network`: If true, include the details of all network devices attached to the computer. - `with_profiles`: If true, include details about all profiles the computer is associated with. - Example request: ```bash From ad6d7d01316c5df3250a74b7ebd9bd68146acd84 Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Wed, 2 Jul 2025 09:11:49 -0600 Subject: [PATCH 015/187] feat: add API reference for `POST `/child-instance-profiles/make-hosts-compliant`` --- docs/reference/api/rest-api-endpoints/wsl.md | 29 +++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 13b21a5e..46a667f2 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -113,6 +113,34 @@ Example output: } ``` +## POST `/child-instance-profiles/make-hosts-compliant` + +Make the given Windows host computers compliant with all of their WSL profiles by reapplying them if needed. + +Required parameters: + +- `host_computer_ids`: The list of IDs of Windows computers to make compliant with their WSL profiles. + +Example requests: + +```sh +curl -X POST http://your-landscape.domain.com/child-instance-profiles/make-hosts-compliant \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $JWT" \ + -d '{"host_computer_ids": [6, 15]}' +``` + +Example output: + +```json +{ + "computer_ids_reapplied_to": [6, 15], + "message": "Successfully created activities for 2 Windows computers to + make them compliant with their WSL profile(s)." +} + +``` + ## DELETE `/child-instance-profiles/` Delete the specified child instance profile. @@ -338,4 +366,3 @@ Example output: } ] ``` - From 360be8bf2d6b5c06e6d31393de239e16a6fc159e Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Wed, 2 Jul 2025 09:15:47 -0600 Subject: [PATCH 016/187] fix illegal json for syntax highlighting --- docs/reference/api/rest-api-endpoints/wsl.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 46a667f2..b554421d 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -134,9 +134,11 @@ Example output: ```json { - "computer_ids_reapplied_to": [6, 15], - "message": "Successfully created activities for 2 Windows computers to - make them compliant with their WSL profile(s)." + "computer_ids_reapplied_to": [ + 6, + 15 + ], + "message": "Successfully created activities for 2 Windows computers to make them compliant with their WSL profile(s)." } ``` From 5417fed5550da71184db201aeb16341127a33f68 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 2 Jul 2025 15:19:48 -0700 Subject: [PATCH 017/187] fix: update profile payload (#17) --- docs/reference/api/rest-api-endpoints/computers.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index ae119a66..a9b5611c 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -315,22 +315,26 @@ Example response: "profiles": [ { "id": 7, - "name": "Desktop Packages", + "name": "desktop-packages", + "title": "Desktop Packages", "type": "package" }, { "id": 7, - "name": "Engineering Repos", + "name": "engineering-repos", + "title": "Engineering Repos", "type": "repository" }, { "id": 22, - "name": "One Month Removal", + "name": "one-month-removal", + "title": "One Month Removal", "type": "removal" } { "id": 4, - "name": "Server Packages", + "name": "server-packages", + "title": "Server Packages", "type": "package", }, ], From 6c24903fc1096d5408cc0a18950e88c988517623 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Fri, 4 Jul 2025 05:13:32 +0800 Subject: [PATCH 018/187] feat: feature flag wsl endpoints (#19) --- .../pluggable-authentication-modules-pam.md | 2 +- .../manual-installation.md | 4 +- .../configure-landscape-beta.md | 7 +- .../wsl-integration/register-wsl-hosts.md | 9 +- .../reference/api/legacy-api-endpoints/wsl.md | 9 ++ .../child-instance-profiles.md | 9 ++ .../api/rest-api-endpoints/computers.md | 108 ------------------ docs/reference/api/rest-api-endpoints/wsl.md | 9 ++ 8 files changed, 43 insertions(+), 114 deletions(-) diff --git a/docs/how-to-guides/external-authentication/pluggable-authentication-modules-pam.md b/docs/how-to-guides/external-authentication/pluggable-authentication-modules-pam.md index b8a6014a..961d3abb 100644 --- a/docs/how-to-guides/external-authentication/pluggable-authentication-modules-pam.md +++ b/docs/how-to-guides/external-authentication/pluggable-authentication-modules-pam.md @@ -14,5 +14,5 @@ Once these are in place, restart Landscape Server and it should be possible to l If you use PAM to authenticate, the user details stored in Landscape are associated with the PAM identity supplied. PAM authentication has been tested against an LDAP server running on Ubuntu, and also with Active Directory running on Windows. -For more information on PAM authentication see [PAM Tutorial](http://wpollock.com/AUnix2/PAM-Help.htm). +For more information on PAM authentication see [PAM Tutorial](https://wpollock.com/AUnix2/PAM-Help.htm). diff --git a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md index 6f4b9ef3..e27bad02 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md @@ -497,8 +497,8 @@ Listen 6554 # directive. Try using SSLCACertificateFile instead # SSLCertificateChainFile /etc/ssl/certs/landscape_server_ca.crt - ProxyPass / h2c://localhost:50051/ - ProxyPassReverse / http://localhost:50051/ + ProxyPass / h2c://localhost:50052/ + ProxyPassReverse / http://localhost:50052/ ``` We now need to enable some modules: diff --git a/docs/how-to-guides/wsl-integration/configure-landscape-beta.md b/docs/how-to-guides/wsl-integration/configure-landscape-beta.md index 7a142af6..0d5c4316 100644 --- a/docs/how-to-guides/wsl-integration/configure-landscape-beta.md +++ b/docs/how-to-guides/wsl-integration/configure-landscape-beta.md @@ -22,6 +22,9 @@ grpc.max_connection_age_ms = 2592000000 # 30 days [hostagent-message-consumer] threads = 1 stores = main account-1 + +[features] +enable-wsl-child-instance-profiles = true ``` ## Update your Apache config @@ -52,8 +55,8 @@ Listen 6554 # directive. Try using SSLCACertificateFile instead # SSLCertificateChainFile /etc/ssl/certs/landscape_server_ca.crt - ProxyPass / h2c://localhost:50051/ - ProxyPassReverse / http://localhost:50051/ + ProxyPass / h2c://localhost:50052/ + ProxyPassReverse / http://localhost:50052/ ``` diff --git a/docs/how-to-guides/wsl-integration/register-wsl-hosts.md b/docs/how-to-guides/wsl-integration/register-wsl-hosts.md index 4c516d93..21f84e31 100644 --- a/docs/how-to-guides/wsl-integration/register-wsl-hosts.md +++ b/docs/how-to-guides/wsl-integration/register-wsl-hosts.md @@ -146,7 +146,14 @@ If your Windows host machine doesn’t appear as a pending computer in your Land [host] url = landscape-server.domain.com:6554 ``` - + +- **Check that the `enable-wsl-child-instance-profiles` in the `[features]` section of your `LandscapeConfig` key is set to `true`.** + + ```bash + [features] + enable-wsl-child-instance-profiles = true + ``` + - **Ensure your firewall settings are configured appropriately** > See also: [Ubuntu Pro for WSL documentation on firewall requirements](https://canonical-ubuntu-pro-for-wsl.readthedocs-hosted.com/en/latest/reference/firewall_requirements/) diff --git a/docs/reference/api/legacy-api-endpoints/wsl.md b/docs/reference/api/legacy-api-endpoints/wsl.md index 4c1e2939..ec09746b 100644 --- a/docs/reference/api/legacy-api-endpoints/wsl.md +++ b/docs/reference/api/legacy-api-endpoints/wsl.md @@ -7,6 +7,15 @@ The methods available here are for managing Windows Subsystem for Linux (WSL) cl These API methods only apply to Landscape Beta at this time. ``` +To enable WSL features in self-hosted Landscape, add: + +```bash +[features] +enable-wsl-child-instance-profiles = true +``` + +to the `service.conf` file. + ## CreateChildComputer Create child computer instances on a parent host machine. diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md index 6f8796bb..31d63198 100644 --- a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -6,6 +6,15 @@ Child Instance Profiles are in beta testing. The API endpoints below may not be available to all accounts. ``` +To enable WSL features in self-hosted Landscape, add: + +```bash +[features] +enable-wsl-child-instance-profiles = true +``` + +to the `service.conf` file. + ## GET `/child-instance-profile-types` Returns a list of the child instance profile types supported by Landscape. Currently, only WSL Child Instance Profiles are supported. diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index a9b5611c..b280c8c0 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -909,114 +909,6 @@ Example output: } ``` -## GET `/computers/wsl-hosts` - -Gets a list of Windows computers that are hosting at least one WSL instance. - -Path parameters: - -- None - -Query parameters: - -- `query`: A query string with space-separated tokens used to filter the returned computers. Words provided as search parameters are treated as keywords, matching the hostname or the computer title. Selector prefixes can be used to further customize the search. - -Example request: - -```bash -curl -X GET https://landscape.canonical.com/api/v2/computers/wsl-hosts -H "Authorization: Bearer $JWT" -``` - -Example output: - -```json -{ - "count": 1, - "results": [ - { - "id": 6, - "title": "Jane's Windows Laptop", - "comment": "", - "hostname": "jane", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:16:41Z", - "tags": [ - "laptop", - "windows" - ], - "access_group": "server", - "distribution": "10 / 11", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": false, - "children": [ - { - "id": 11, - "title": "Bionic WSL", - "comment": "", - "hostname": "bionic-wsl", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:11:41Z", - "tags": [ - "bionic", - "wsl" - ], - "access_group": "global", - "distribution": "18.04", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": true - }, - { - "id": 12, - "title": "Focal WSL", - "comment": "", - "hostname": "focal-wsl", - "total_memory": 1024, - "total_swap": 1024, - "reboot_required_flag": false, - "update_manager_prompt": "normal", - "clone_id": null, - "secrets_name": null, - "last_exchange_time": null, - "last_ping_time": "2024-02-07T21:10:41Z", - "tags": [ - "focal", - "wsl" - ], - "access_group": "global", - "distribution": "20.04", - "cloud_instance_metadata": {}, - "vm_info": null, - "container_info": null, - "ubuntu_pro_info": null, - "is_wsl_instance": true - } - ], - "parent": null - } - ], - "next": null, - "previous": null -} -``` - ## GET `/computers//groups` Get all user groups for the provided computer ID. diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index be2f4416..5044604f 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -6,6 +6,15 @@ WSL features are in beta testing. The API endpoints below may not be available to all accounts. ``` +To enable WSL features in self-hosted Landscape, add: + +```bash +[features] +enable-wsl-child-instance-profiles = true +``` + +to the `service.conf` file. + ## POST `/computers//children` Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape. From 8caeb1cfe84a295db641c0f35e49747e5fa46769 Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Thu, 3 Jul 2025 16:06:34 -0600 Subject: [PATCH 019/187] fix url.... --- docs/reference/api/rest-api-endpoints/wsl.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index a44d9164..25448ea5 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -26,10 +26,7 @@ Required parameters: Example requests: ```sh -curl -X POST http://your-landscape.domain.com/child-instance-profiles/make-hosts-compliant \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $JWT" \ - -d '{"host_computer_ids": [6, 15]}' +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' ``` Example output: @@ -42,7 +39,6 @@ Example output: ], "message": "Successfully created activities for 2 Windows computers to make them compliant with their WSL profile(s)." } - ``` ## POST `/computers//children` From c86719cd4a3bab2ebfa45c78771926e0b166380b Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Mon, 7 Jul 2025 15:29:06 -0600 Subject: [PATCH 020/187] feat: update `/GET computers` to include `with_wsl_profiles` --- .../api/rest-api-endpoints/computers.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index b280c8c0..c372f71c 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -37,6 +37,7 @@ Query parameters: - `with_network`: If true, include the details of all network devices attached to the computer. - `with_hardware`: If true, include the details of all hardware information known. - `with_annotations`: If true, include the details of all custom annotation information known. +- `with_wsl_profiles`: If true, include WSL profiles associated with Windows computers. Defaults to false. Example request: @@ -165,7 +166,7 @@ Example output: Example request: ```bash -curl -X GET https://landscape.canonical.com/api/v2/computers/?query=profile:wsl:1:compliant -H "Authorization: Bearer $JWT" +curl -X GET https://landscape.canonical.com/api/v2/computers/?query=profile:wsl:1:compliant&with_wsl_profiles=true -H "Authorization: Bearer $JWT" ``` Example output: @@ -250,7 +251,21 @@ Example output: "is_wsl_instance": true } ], - "parent": null + "parent": null, + "wsl_profiles": [ + { + "id": 1, + "name": "Bionic WSL", + "title": "Bionic Profile", + "type": "wsl" + }, + { + "id": 2, + "name": "Focal WSL", + "title": "Focal Profile", + "type": "wsl" + } + ] } ], "next": null, From e56573bb0f08087ed58c2f42a8046713cea9bf13 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 7 Jul 2025 14:55:25 -0700 Subject: [PATCH 021/187] fix: update wsl feature limit doc (#21) --- docs/reference/api/rest-api-endpoints/wsl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 25448ea5..ac660ae6 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -320,7 +320,7 @@ Get the limits for WSL related features for the account. Path parameters: -- `name`: The name of the account +- None Required parameters: From ded50e6b413e15c339f3eba0f10e01bd3ca766af Mon Sep 17 00:00:00 2001 From: jansdhillon Date: Tue, 8 Jul 2025 10:05:49 -0600 Subject: [PATCH 022/187] feat: add `registered_at` key to GET `/computers/` and add annotations to example --- docs/reference/api/rest-api-endpoints/computers.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 2dc2a3db..0643e4f1 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -174,7 +174,7 @@ Query parameters: Example request: ```bash -curl -X GET https://landscape.canonical.com/api/v2/computers/1?with_grouped_hardware=true -H "Authorization: Bearer $JWT" +curl -X GET https://landscape.canonical.com/api/v2/computers/1?with_grouped_hardware=true&with_annotations=true -H "Authorization: Bearer $JWT" ``` Example output: @@ -188,6 +188,7 @@ Example output: "total_memory": 1024, "total_swap": 1024, "reboot_required_flag": false, + "registered_at": "2024-07-10T22:22:16Z", "update_manager_prompt": "normal", "clone_id": null, "secrets_name": null, @@ -198,6 +199,9 @@ Example output: "server", "webfarm" ], + "annotations": { + "code": "Ymv1YjUL" + }, "access_group": "server", "distribution": "10.04", "cloud_instance_metadata": {}, @@ -1139,4 +1143,3 @@ Example response: "type": "ActivityGroup" } ``` - From 020a9f7348940005106746fe9a84baa2a289266a Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 8 Jul 2025 15:54:06 -0700 Subject: [PATCH 023/187] feat: add docs for child instance profiles (#20) --- .../api/rest-api-endpoints/computers.md | 338 +++++++++--------- docs/reference/api/rest-api-endpoints/wsl.md | 113 ++++++ 2 files changed, 282 insertions(+), 169 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index f7177b9c..c21cbcb7 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -860,74 +860,6 @@ Example output: } ``` -## GET `/computers/activities` - -Get details of the activities for specified computer(s). - -Path parameters: - -- None - -Query parameters: - -- (Required) `computer_ids`: An ID assigned to a specific computer. -- `limit`: The maximum number of results returned by the method. It defaults to 1000. -- `offset`: The offset inside the list of results. - -Example request: - -```bash -curl -X GET "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1" -H "Authorization: Bearer $JWT" -``` - -Example output: - -```json -{ - "count": 26, - "results": [ - { - "id": 143, - "creation_time": "2024-03-01T20:58:14Z", - "creator": { - "name": "John Smith", - "email": "john@example.com", - "id": 1 - }, - "type": "ChangePackagesRequest", - "summary": "Remove package abs-guide", - "result_text": null, - "computer_id": 1, - "approval_time": null, - "delivery_time": null, - "deliver_after_time": null, - "deliver_before_time": null, - "package_ids": [ - 73 - ], - "changes": [ - { - "package": "abs-guide", - "complemented": false, - "type": "remove", - "version": "10-3" - } - ], - "parent_id": 142, - "modification_time": "2024-03-01T20:58:14Z", - "completion_time": null, - "schedule_before_time": null, - "schedule_after_time": null, - "result_code": null, - "activity_status": "undelivered", - "children": [] - } - ], - "next": "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1&offset=1", - "previous": null -} -``` - ## GET `/computers//groups` Get all user groups for the provided computer ID. @@ -992,9 +924,9 @@ Example output: } ``` -## GET `/computers//snaps/installed` +## GET `/computers//processes` -List all installed snaps on a single computer. +Gets the active processes for the computer. Path parameters: @@ -1008,96 +940,89 @@ Query parameters: Example request: ```bash -curl -X GET "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2" -H "Authorization: Bearer $JWT" +curl -X GET "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2" -H "Authorization: Bearer $JWT" ``` Example output: ```json { - "count": 4, + "count": 84, "results": [ { - "version": "4.0.9-a29c6f1", - "revision": "24061", - "tracking_channel": "4.0/stable/ubuntu-20.04", - "held_until": null, - "confinement": "strict", - "snap": { - "id": "J60k4GY0HppDwOeW8dZdWc8obX0xujRu", - "name": "lxd", - "publisher": { - "username": "canonical", - "validation": "verified" - }, - "summary": "LXD - container and VM manager" - } + "id": 2551, + "computer_id": 22, + "pid": 1525, + "gid": 1000, + "name": "(sd-pam)", + "state": "S", + "start_time": "2024-02-07T20:26:55Z", + "vm_size": 104024, + "cpu_utilisation": 0 }, { - "version": "2.61.1", - "revision": "20671", - "tracking_channel": "latest/stable", - "held_until": null, - "confinement": "strict", - "snap": { - "id": "PM2rV4ml8uWu4RDBT8dSGnJUYbevVhc4", - "name": "snapd", - "publisher": { - "username": "canonical", - "validation": "verified" - }, - "summary": "Daemon and tooling that enable snap packages" - } + "id": 2552, + "computer_id": 22, + "pid": 1530, + "gid": 1000, + "name": "-bash", + "state": "S", + "start_time": "2024-02-07T20:26:55Z", + "vm_size": 10032, + "cpu_utilisation": 0 } ], - "next": "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2&offset=2", + "next": "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2&offset=2", "previous": null } ``` -## GET `/computers//users//groups` +## POST `/computers//restart` -Get all the groups for the provided username on the given computer ID. +Restarts the specified computer Path parameters: - `computer_id`: An ID assigned to a specific computer. -- `username`: The username of the account. -Query parameters: +Optional query parameters: -- None +- `deliver_after`: A time in the future to deliver the reboot activity +- `deliver_delay_window`: Randomize delivery within the given time frame (minutes) Example request: ```bash -curl -X GET "https://landscape.canonical.com/api/v2/computers/22/users/ubuntu/groups" -H "Authorization: Bearer $JWT" +curl -X POST "https://landscape.canonical.com/api/v2/computers/29/restart" \ + -H "Authorization: Bearer $JWT" \ ``` -Example output: +Example response: ```json { - "groups": [ - { - "id": 1020, - "computer_id": 22, - "gid": 4, - "name": "adm" - }, - { - "id": 1022, - "computer_id": 22, - "gid": 29, - "name": "audio" - }, - ] + "activity_status": "undelivered", + "approval_time": null, + "completion_time": null, + "creation_time": "2024-11-22T00:01:18Z", + "creator": { + "email": "john@example.com", + "id": 1, + "name": "John Smith" + }, + "deliver_delay_window": 0, + "id": 2225, + "parent_id": null, + "result_code": null, + "result_text": null, + "summary": "Restart computer", + "type": "ActivityGroup" } ``` -## GET `/computers//processes` +## GET `/computers//snaps/installed` -Gets the active processes for the computer. +List all installed snaps on a single computer. Path parameters: @@ -1111,39 +1036,49 @@ Query parameters: Example request: ```bash -curl -X GET "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2" -H "Authorization: Bearer $JWT" +curl -X GET "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2" -H "Authorization: Bearer $JWT" ``` Example output: ```json { - "count": 84, + "count": 4, "results": [ { - "id": 2551, - "computer_id": 22, - "pid": 1525, - "gid": 1000, - "name": "(sd-pam)", - "state": "S", - "start_time": "2024-02-07T20:26:55Z", - "vm_size": 104024, - "cpu_utilisation": 0 + "version": "4.0.9-a29c6f1", + "revision": "24061", + "tracking_channel": "4.0/stable/ubuntu-20.04", + "held_until": null, + "confinement": "strict", + "snap": { + "id": "J60k4GY0HppDwOeW8dZdWc8obX0xujRu", + "name": "lxd", + "publisher": { + "username": "canonical", + "validation": "verified" + }, + "summary": "LXD - container and VM manager" + } }, { - "id": 2552, - "computer_id": 22, - "pid": 1530, - "gid": 1000, - "name": "-bash", - "state": "S", - "start_time": "2024-02-07T20:26:55Z", - "vm_size": 10032, - "cpu_utilisation": 0 + "version": "2.61.1", + "revision": "20671", + "tracking_channel": "latest/stable", + "held_until": null, + "confinement": "strict", + "snap": { + "id": "PM2rV4ml8uWu4RDBT8dSGnJUYbevVhc4", + "name": "snapd", + "publisher": { + "username": "canonical", + "validation": "verified" + }, + "summary": "Daemon and tooling that enable snap packages" + } } ], - "next": "https://landscape.canonical.com/api/v2/computers/22/processes?limit=2&offset=2", + "next": "https://landscape.canonical.com/api/v2/computers/22/snaps/installed?limit=2&offset=2", "previous": null } ``` @@ -1194,45 +1129,110 @@ Example output: } ``` -## POST `/computers//restart` +## GET `/computers//users//groups` -Restarts the specified computer +Get all the groups for the provided username on the given computer ID. Path parameters: - `computer_id`: An ID assigned to a specific computer. +- `username`: The username of the account. -Optional query parameters: +Query parameters: -- `deliver_after`: A time in the future to deliver the reboot activity -- `deliver_delay_window`: Randomize delivery within the given time frame (minutes) +- None Example request: ```bash -curl -X POST "https://landscape.canonical.com/api/v2/computers/29/restart" \ - -H "Authorization: Bearer $JWT" \ +curl -X GET "https://landscape.canonical.com/api/v2/computers/22/users/ubuntu/groups" -H "Authorization: Bearer $JWT" ``` -Example response: +Example output: ```json { - "activity_status": "undelivered", - "approval_time": null, - "completion_time": null, - "creation_time": "2024-11-22T00:01:18Z", - "creator": { - "email": "john@example.com", - "id": 1, - "name": "John Smith" - }, - "deliver_delay_window": 0, - "id": 2225, - "parent_id": null, - "result_code": null, - "result_text": null, - "summary": "Restart computer", - "type": "ActivityGroup" + "groups": [ + { + "id": 1020, + "computer_id": 22, + "gid": 4, + "name": "adm" + }, + { + "id": 1022, + "computer_id": 22, + "gid": 29, + "name": "audio" + }, + ] +} +``` + +## GET `/computers/activities` + +Get details of the activities for specified computer(s). + +Path parameters: + +- None + +Query parameters: + +- (Required) `computer_ids`: An ID assigned to a specific computer. +- `limit`: The maximum number of results returned by the method. It defaults to 1000. +- `offset`: The offset inside the list of results. + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1" -H "Authorization: Bearer $JWT" +``` + +Example output: + +```json +{ + "count": 26, + "results": [ + { + "id": 143, + "creation_time": "2024-03-01T20:58:14Z", + "creator": { + "name": "John Smith", + "email": "john@example.com", + "id": 1 + }, + "type": "ChangePackagesRequest", + "summary": "Remove package abs-guide", + "result_text": null, + "computer_id": 1, + "approval_time": null, + "delivery_time": null, + "deliver_after_time": null, + "deliver_before_time": null, + "package_ids": [ + 73 + ], + "changes": [ + { + "package": "abs-guide", + "complemented": false, + "type": "remove", + "version": "10-3" + } + ], + "parent_id": 142, + "modification_time": "2024-03-01T20:58:14Z", + "completion_time": null, + "schedule_before_time": null, + "schedule_after_time": null, + "result_code": null, + "activity_status": "undelivered", + "children": [] + } + ], + "next": "https://landscape.canonical.com/api/v2/computers/activities?limit=1&computer_ids=1&offset=1", + "previous": null } ``` diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index ac660ae6..5850c320 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -41,6 +41,119 @@ Example output: } ``` +## GET `/computers//children` + +Get information about the WSL instances associated with the computer. + +Path parameters: + +- `computer_id`: The ID assigned to a specific computer. + +Query parameters: + +- None + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/computers/23/children" -H "Authorization: Bearer $JWT" +``` + +Example response: + +```json +[ + { + "name": "WSL instance created via WSL profile, installed, registered", + "computer_id": 5, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": "WSL Profile 1", + "is_running": true, + "installed": true, + "registered": true, + "default": true, + }, + { + "name": "WSL instance associated with profile, not installed, installation in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "uninstalled", + "profile": "WSL Profile 2", + "is_running": false, + "installed": false, + "registered": false, + "default": null + }, + { + "name": "WSL instance associated with profile, installed, registration in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "unregistered", + "profile": "WSL Profile 3", + "is_running": false, + "installed": true, + "registered": false, + "default": null + }, + { + "name": "WSL instance associated with profile, not installed, installation not in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 4", + "is_running": false, + "installed": false, + "registered": false, + "default": null + }, + { + "name": "WSL instance not created via Landscape, not conflicting with any profile", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": null, + "is_running": false, + "installed": true, + "registered": false, + "default": false + }, + { + "name": "WSL instance not created via Landscape, conflicting with a profile", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 2", + "is_running": false, + "installed": true, + "registered": false, + "default": false + }, + { + "name": "WSL instance created via Landscape without a WSL profile, registered, not conflicting with any profile", + "computer_id": 6, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": null, + "is_running": false, + "installed": true, + "registered": true, + "default": false + }, + { + "name": "WSL instance created via Landscape without a WSL profile, registered, conflicting with any profile", + "computer_id": 7, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 1", + "is_running": false, + "installed": true, + "registered": true, + "default": false + } +] +``` + ## POST `/computers//children` Creates an activity to install a WSL instance on a Windows host. The WSL instance will be managed in Landscape. From cfd8a616c13637ce0032dec812fb8145a328b6e1 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 9 Jul 2025 16:45:45 -0700 Subject: [PATCH 024/187] fix: update GET /computers//children response payload (#24) --- docs/reference/api/rest-api-endpoints/wsl.md | 182 ++++++++++--------- 1 file changed, 92 insertions(+), 90 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 5850c320..c82cc189 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -62,96 +62,98 @@ curl -X GET "https://landscape.canonical.com/api/v2/computers/23/children" -H "A Example response: ```json -[ - { - "name": "WSL instance created via WSL profile, installed, registered", - "computer_id": 5, - "version_id": "Ubuntu 22.04", - "compliance": "compliant", - "profile": "WSL Profile 1", - "is_running": true, - "installed": true, - "registered": true, - "default": true, - }, - { - "name": "WSL instance associated with profile, not installed, installation in progress", - "computer_id": null, - "version_id": "Ubuntu 22.04", - "compliance": "uninstalled", - "profile": "WSL Profile 2", - "is_running": false, - "installed": false, - "registered": false, - "default": null - }, - { - "name": "WSL instance associated with profile, installed, registration in progress", - "computer_id": null, - "version_id": "Ubuntu 22.04", - "compliance": "unregistered", - "profile": "WSL Profile 3", - "is_running": false, - "installed": true, - "registered": false, - "default": null - }, - { - "name": "WSL instance associated with profile, not installed, installation not in progress", - "computer_id": null, - "version_id": "Ubuntu 22.04", - "compliance": "noncompliant", - "profile": "WSL Profile 4", - "is_running": false, - "installed": false, - "registered": false, - "default": null - }, - { - "name": "WSL instance not created via Landscape, not conflicting with any profile", - "computer_id": null, - "version_id": "Ubuntu 22.04", - "compliance": "compliant", - "profile": null, - "is_running": false, - "installed": true, - "registered": false, - "default": false - }, - { - "name": "WSL instance not created via Landscape, conflicting with a profile", - "computer_id": null, - "version_id": "Ubuntu 22.04", - "compliance": "noncompliant", - "profile": "WSL Profile 2", - "is_running": false, - "installed": true, - "registered": false, - "default": false - }, - { - "name": "WSL instance created via Landscape without a WSL profile, registered, not conflicting with any profile", - "computer_id": 6, - "version_id": "Ubuntu 22.04", - "compliance": "compliant", - "profile": null, - "is_running": false, - "installed": true, - "registered": true, - "default": false - }, - { - "name": "WSL instance created via Landscape without a WSL profile, registered, conflicting with any profile", - "computer_id": 7, - "version_id": "Ubuntu 22.04", - "compliance": "noncompliant", - "profile": "WSL Profile 1", - "is_running": false, - "installed": true, - "registered": true, - "default": false - } -] +{ + "children": [ + { + "name": "WSL instance created via WSL profile, installed, registered", + "computer_id": 5, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": "WSL Profile 1", + "is_running": true, + "installed": true, + "registered": true, + "default": true, + }, + { + "name": "WSL instance associated with profile, not installed, installation in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "uninstalled", + "profile": "WSL Profile 2", + "is_running": false, + "installed": false, + "registered": false, + "default": null + }, + { + "name": "WSL instance associated with profile, installed, registration in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "unregistered", + "profile": "WSL Profile 3", + "is_running": false, + "installed": true, + "registered": false, + "default": null + }, + { + "name": "WSL instance associated with profile, not installed, installation not in progress", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 4", + "is_running": false, + "installed": false, + "registered": false, + "default": null + }, + { + "name": "WSL instance not created via Landscape, not conflicting with any profile", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": null, + "is_running": false, + "installed": true, + "registered": false, + "default": false + }, + { + "name": "WSL instance not created via Landscape, conflicting with a profile", + "computer_id": null, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 2", + "is_running": false, + "installed": true, + "registered": false, + "default": false + }, + { + "name": "WSL instance created via Landscape without a WSL profile, registered, not conflicting with any profile", + "computer_id": 6, + "version_id": "Ubuntu 22.04", + "compliance": "compliant", + "profile": null, + "is_running": false, + "installed": true, + "registered": true, + "default": false + }, + { + "name": "WSL instance created via Landscape without a WSL profile, registered, conflicting with any profile", + "computer_id": 7, + "version_id": "Ubuntu 22.04", + "compliance": "noncompliant", + "profile": "WSL Profile 1", + "is_running": false, + "installed": true, + "registered": true, + "default": false + } + ] +} ``` ## POST `/computers//children` From e97888a95190da2a30b9cd6561b29c369444b82f Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 21 Jul 2025 13:45:49 -0700 Subject: [PATCH 025/187] feat: add additional paramters to the GET /computers docs --- .../api/rest-api-endpoints/computers.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index c21cbcb7..d97a2d71 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -30,14 +30,23 @@ Query parameters: - `profile::`: Instances associated with the specified profile. The `` must be one of `security`, `script`, `repository`, `package`, `upgrade`, `reboot`, `removal`, or `wsl`. The `` is the database id of the profile. - `profile:security::`: Instances associated with the specified USG security profile with the indicated last audit result. The `` is the database id of the profile. The `` must be one of `pass`, `fail`, or `in-progress`. - `profile:wsl::`: Instances associated with the specified WSL Child Instance Profile. The `` is the database id of the profile. The `` must either be `compliant` or `noncompliant`. - - `OR`: Search for computers matching term A or term B. `OR` must be in all-caps. - - `NOT`: search for computers not matching the next term. `NOT` must be in all-caps. + - `OR`: Search for computers matching term A or term B. The text `OR` must be in all-caps. + - `NOT`: search for computers not matching the next term. The text `NOT` must be in all-caps. - `limit`: The maximum number of results returned by the method. It defaults to 1000. - `offset`: The offset inside the list of results. -- `with_network`: If true, include the details of all network devices attached to the computer. -- `with_hardware`: If true, include the details of all hardware information known. -- `with_annotations`: If true, include the details of all custom annotation information known. +- `with_alerts`: If true, includes alert information in each computer object if that alert is active. Defaults to false. +- `with_upgrades`: If true, includes how many regular and security upgrades that computer has. Defaults to false. +- `with_reboot_packages`: Show packages needing reboot. Defaults to false. +- `with_network`: If true, include the details of all network devices attached to the computer. Defaults to false. +- `with_all_network`: If true, include the details of all active and inactive network devices attached to the computer. Defaults to false. +- `with_hardware`: If true, include the details of all hardware information known. Defaults to false. +- `with_annotations`: If true, include the details of all custom annotation information known. Defaults to false. +- `with_grouped_hardware`: If true, include the details of all known hardware information grouped by device category. Defaults to false. - `with_wsl_profiles`: If true, include WSL profiles associated with Windows computers. Defaults to false. +- `archived_only`: If true, only includes archived computers. If false, only includes non-archived computers. Defaults to false. +- `root_only`: Whether or not to include only the root member of a computer family tree. Defaults to true. If false, all computers will be included. +- `wsl_parents`: If true, restrict the result to WSL parent instances (i.e. Windows machines). This parameter can be used in conjunction with the `wsl_children` parameter. Defaults to false (no additional filtering). +- `wsl_children`: If true, restrict the result to WSL child instances. This parameter can be used in conjunction with the `wsl_parents` parameter. This parameter requires the `root_only` flag be set to false. Defaults to false (no additional filtering). Example request: From d77951728004b47da2fa59a75235f5c275256efa Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 22 Jul 2025 11:13:31 -0700 Subject: [PATCH 026/187] fix: update compliance for WSL ghosts (#26) --- docs/reference/api/rest-api-endpoints/wsl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index c82cc189..181fc90b 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -79,7 +79,7 @@ Example response: "name": "WSL instance associated with profile, not installed, installation in progress", "computer_id": null, "version_id": "Ubuntu 22.04", - "compliance": "uninstalled", + "compliance": "pending", "profile": "WSL Profile 2", "is_running": false, "installed": false, @@ -101,7 +101,7 @@ Example response: "name": "WSL instance associated with profile, not installed, installation not in progress", "computer_id": null, "version_id": "Ubuntu 22.04", - "compliance": "noncompliant", + "compliance": "uninstalled", "profile": "WSL Profile 4", "is_running": false, "installed": false, From 0e99a13337aa50e791507f1a3c37886493b89671 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Tue, 22 Jul 2025 12:20:32 -0700 Subject: [PATCH 027/187] fix: broken link for tests (#27) --- docs/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c622292a..cc35ea13 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -139,7 +139,8 @@ "https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html", "https://wiki.ubuntu.com/Membership", "https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server", - "https://ubuntu.com/aws#get-in-touch" + "https://ubuntu.com/aws#get-in-touch", + "http://nfs.sourceforge.net/#faq_d2" ] @@ -289,4 +290,4 @@ 'how-to-guides/landscape-installation-and-set-up/install-on-microsoft-azure': '../cloud-providers/install-on-microsoft-azure', 'how-to-guides/security/manage-repositories-in-an-air-gapped-or-offline-environment': '../../repository-mirrors/manage-repositories-in-an-air-gapped-or-offline-environment', 'how-to-guides/security/install-landscape-in-an-air-gapped-or-offline-environment': '../../landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment' -} \ No newline at end of file +} From e45b960e6c3a0affabb6da297f72a3745fb16265 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Fri, 25 Jul 2025 14:12:38 -0500 Subject: [PATCH 028/187] add script_tempdir docs to client configuration setup guide --- .../configure-landscape-client.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md index cd37c683..f09ff7d6 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md @@ -96,6 +96,29 @@ sudo service landscape-client restart ``` Setting `script_users = ALL` (or passing `ALL` to the `--script-users` parameter of `landscape-config`) will allow any system user to run scripts. If `script_users` is not set, then scripts can only be run by the `nobody` user. +Landscape will default to using `/tmp` as a working directory for script execution. +If you'd like to use a different directory, you can set `script_tempdir`: + +```ini +[client] +... +script_tempdir = /var/custom-tempdir +``` + +Landscape will use the `script_tempdir` and when creating scripts and script attachments. +You will need to ensure that whichever user you run scripts as has write and execute privileges on the directories. + +```sh +mkdir -p /var/custom-tempdir + +# all users +sudo chmod 777 /var/custom-tempdir + +# Or, only the landscape user +sudo chown landscape:landscape +sudo chmod 700 /var/custom-tempdir +``` + ## Landscape clients with configuration management tools If you want to manage `landscape-client` through a configuration management tool such as Puppet or Ansible, you can avoid getting duplicate computers by writing the `/etc/landscape/client.conf` and `/etc/default/landscape-client` files, and then restarting the `landscape-client` service. From 0e112b2061255ff03e471e88843b61c6c4ce0075 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Fri, 25 Jul 2025 17:09:39 -0500 Subject: [PATCH 029/187] fix grammar --- .../configure-landscape-client.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md index f09ff7d6..e96a6f2c 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md @@ -105,8 +105,8 @@ If you'd like to use a different directory, you can set `script_tempdir`: script_tempdir = /var/custom-tempdir ``` -Landscape will use the `script_tempdir` and when creating scripts and script attachments. -You will need to ensure that whichever user you run scripts as has write and execute privileges on the directories. +Landscape will use the `script_tempdir` when creating scripts and script attachments. +You will need to ensure that whichever user you run scripts as has write and execute privileges on the directory. ```sh mkdir -p /var/custom-tempdir From 408c3b73538d4946da43a1eccf70b1842d85485f Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 31 Jul 2025 09:57:14 -0500 Subject: [PATCH 030/187] include client version note; use placeholder for tempdir; light cleanup of formatting --- .../configure-landscape-client.md | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md index e96a6f2c..bc9e5a5a 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md @@ -96,27 +96,36 @@ sudo service landscape-client restart ``` Setting `script_users = ALL` (or passing `ALL` to the `--script-users` parameter of `landscape-config`) will allow any system user to run scripts. If `script_users` is not set, then scripts can only be run by the `nobody` user. -Landscape will default to using `/tmp` as a working directory for script execution. -If you'd like to use a different directory, you can set `script_tempdir`: +### Use a custom working directory + +```{note} +Using a custom working directory for script execution is available in Landscape Client 25.04+6542 and later. +``` + +Landscape defaults to using `/tmp` as a working directory for script execution. If you want to use a different directory, set `script_tempdir` to your custom directory: ```ini [client] ... -script_tempdir = /var/custom-tempdir +script_tempdir = ``` -Landscape will use the `script_tempdir` when creating scripts and script attachments. -You will need to ensure that whichever user you run scripts as has write and execute privileges on the directory. +After you've set `script_tempdir`, Landscape will use the `script_tempdir` when creating scripts and script attachments. You'll need to ensure that whichever user(s) you run scripts as have write and execute privileges on the directory. For example, to set these permissions for only the `landscape` user: ```sh -mkdir -p /var/custom-tempdir +mkdir -p -# all users -sudo chmod 777 /var/custom-tempdir +sudo chown landscape:landscape +sudo chmod 700 +``` + +Or, to set these permissions for all users on the system: + +```sh +mkdir -p -# Or, only the landscape user -sudo chown landscape:landscape -sudo chmod 700 /var/custom-tempdir +sudo chown landscape:landscape +sudo chmod 777 ``` ## Landscape clients with configuration management tools From 2f01e5c997646323442d452cdf8a8ca369c41bcd Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 31 Jul 2025 11:21:24 -0700 Subject: [PATCH 031/187] api for wsl profiles --- docs/how-to-guides/wsl-integration/index.md | 1 + .../wsl-integration/manage-wsl-instances.md | 2 +- .../use-child-instance-profiles.md | 35 +++++++++++++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 docs/how-to-guides/wsl-integration/use-child-instance-profiles.md diff --git a/docs/how-to-guides/wsl-integration/index.md b/docs/how-to-guides/wsl-integration/index.md index 76d59702..a4d69876 100644 --- a/docs/how-to-guides/wsl-integration/index.md +++ b/docs/how-to-guides/wsl-integration/index.md @@ -9,6 +9,7 @@ Configure Landscape Beta Set up an environment Register WSL hosts Manage WSL instances +Use child instance profiles Use a specific image source Perform common tasks Get support diff --git a/docs/how-to-guides/wsl-integration/manage-wsl-instances.md b/docs/how-to-guides/wsl-integration/manage-wsl-instances.md index 0114b5d3..8db67e5b 100644 --- a/docs/how-to-guides/wsl-integration/manage-wsl-instances.md +++ b/docs/how-to-guides/wsl-integration/manage-wsl-instances.md @@ -108,5 +108,5 @@ This feature is currently in beta. You can use child instance profiles to provision WSL instances from official Ubuntu images in the Microsoft Store or from custom images at scale. These WSL instances can be configured with cloud-init at the time of provisioning. -For the available endpoints and example requests, see our {ref}`reference-rest-api-beta-only`. +For more information, see {ref}`how-to-use-child-instance-profiles`. diff --git a/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md b/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md new file mode 100644 index 00000000..ce8e942b --- /dev/null +++ b/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md @@ -0,0 +1,35 @@ +(how-to-use-child-instance-profiles)= + +# How to use child instance profiles + +```{note} +This feature is currently in beta. +``` + +> See also: {ref}`reference-rest-api-wsl`. + +This guide describes how to use child instance profiles to provision WSL instances and manage them with Landscape. + +## Create a child instance profile + +You can add Windows host machines to the profile by assigning tags or by associating to all computers. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "JammyProfile", "description": "Jammy", "image_name": "Ubuntu-22.04", "all_computers": "true"}' +``` + +## Apply a child instance profile + +This will create activities to provision WSL instances on every associated Windows host machine. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/JammyProfile:reapply -H "Authorization: Bearer $JWT"' +``` + +## Apply all child instance profiles by Windows host machine + +This will create activities to provision WSL instances on specified Windows host machines for all associated child instance profiles. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' +``` From 77991a847c3770ad92033b9d3cbfbb0cb19ee33d Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 31 Jul 2025 15:05:36 -0700 Subject: [PATCH 032/187] wsl guide --- docs/how-to-guides/wsl-integration/index.md | 2 +- .../wsl-integration/manage-wsl-instances.md | 6 +- .../use-child-instance-profiles.md | 35 --------- .../wsl-integration/use-wsl-profiles.md | 72 +++++++++++++++++++ .../child-instance-profiles.md | 1 + 5 files changed, 77 insertions(+), 39 deletions(-) delete mode 100644 docs/how-to-guides/wsl-integration/use-child-instance-profiles.md create mode 100644 docs/how-to-guides/wsl-integration/use-wsl-profiles.md diff --git a/docs/how-to-guides/wsl-integration/index.md b/docs/how-to-guides/wsl-integration/index.md index a4d69876..aba6acc8 100644 --- a/docs/how-to-guides/wsl-integration/index.md +++ b/docs/how-to-guides/wsl-integration/index.md @@ -9,7 +9,7 @@ Configure Landscape Beta Set up an environment Register WSL hosts Manage WSL instances -Use child instance profiles +Use WSL profiles Use a specific image source Perform common tasks Get support diff --git a/docs/how-to-guides/wsl-integration/manage-wsl-instances.md b/docs/how-to-guides/wsl-integration/manage-wsl-instances.md index 8db67e5b..0df9e58d 100644 --- a/docs/how-to-guides/wsl-integration/manage-wsl-instances.md +++ b/docs/how-to-guides/wsl-integration/manage-wsl-instances.md @@ -100,13 +100,13 @@ landscape-api delete-child-computers 21,34 Removing a WSL instance from its Windows host machine will also remove the associated WSL instance from Landscape. -## Use child instance profiles +## Use WSL profiles ```{note} This feature is currently in beta. ``` -You can use child instance profiles to provision WSL instances from official Ubuntu images in the Microsoft Store or from custom images at scale. These WSL instances can be configured with cloud-init at the time of provisioning. +You can use WSL profiles to provision WSL instances from official Ubuntu images in the Microsoft Store or from custom images at scale. These WSL instances can be configured with cloud-init at the time of provisioning. -For more information, see {ref}`how-to-use-child-instance-profiles`. +For more information, see {ref}`how-to-use-wsl-profiles`. diff --git a/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md b/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md deleted file mode 100644 index ce8e942b..00000000 --- a/docs/how-to-guides/wsl-integration/use-child-instance-profiles.md +++ /dev/null @@ -1,35 +0,0 @@ -(how-to-use-child-instance-profiles)= - -# How to use child instance profiles - -```{note} -This feature is currently in beta. -``` - -> See also: {ref}`reference-rest-api-wsl`. - -This guide describes how to use child instance profiles to provision WSL instances and manage them with Landscape. - -## Create a child instance profile - -You can add Windows host machines to the profile by assigning tags or by associating to all computers. - -```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "JammyProfile", "description": "Jammy", "image_name": "Ubuntu-22.04", "all_computers": "true"}' -``` - -## Apply a child instance profile - -This will create activities to provision WSL instances on every associated Windows host machine. - -```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/JammyProfile:reapply -H "Authorization: Bearer $JWT"' -``` - -## Apply all child instance profiles by Windows host machine - -This will create activities to provision WSL instances on specified Windows host machines for all associated child instance profiles. - -```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' -``` diff --git a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md new file mode 100644 index 00000000..9ef95d68 --- /dev/null +++ b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md @@ -0,0 +1,72 @@ +(how-to-use-wsl-profiles)= + +# How to use WSL profiles + +```{note} +This feature is currently in beta. +``` + +> See also: {ref}`reference-rest-api-child-instance-profiles` and {ref}`reference-rest-api-wsl`. + +This guide describes how to use WSL profiles (also called child instance profiles) to provision WSL instances and manage them with Landscape. + +## Create a WSL profile in the Landscape web portal + +You can create a new WSL profile from the Landscape web portal. To do this: + +1. Click **Profiles** +2. Click **WSL profiles** +3. Click **Add WSL profile** + +In the WSL profile creation form, complete the following fields: + +- **Title**: A title for the profile. +- **Description**: A human readable description for the profile. +- **Access group**: The access group the profile will apply to. Restricts which instances the profile can manage and which users can edit and execute the profile. +- **RootFS image**: The URL or file path for the RootFS image. +- **Cloud-init**: The contents of the cloud init to be supplied to the WSL instance. This can be uploaded as a file or inputted as text. +- **Association**: + - **Associate to all instances**: The profile will affect all instances in the same access group as the profile + - **Tag(s)**: Only instances having the specific tag(s), in the same access group as the profile will be affected + +After you've created your WSL profile, activities will be created to install the specified WSL instance on the associated Windows host machines. +A Windows host machine is considered compliant with a WSL profile if it has the corresponding WSL instance that is created by Landscape. + +You can view, edit, duplicate, or remove the profile using the dot menu under **Actions**. You can also see the number of associated parents and the number of compliant or non-compliant Windows host machines. + +## Create a WSL profile using the Landscape API + +You can create a WSL profile via Landscape's REST API. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "JammyProfile", "description": "Jammy", "image_name": "Ubuntu-22.04", "all_computers": "true"}' +``` + +## Reapply a WSL profile using the Landscape API + +Activities to install the corresponding WSL instance are automatically created when a Windows host machine is associated with a WSL profile. +If you want to fix any non-compliant Windows host machines, you can reapply a WSL profile via Landscape's REST API. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/JammyProfile:reapply -H "Authorization: Bearer $JWT" +``` + +## Apply all WSL profiles by Windows host machine in the Landscape web portal + +You can apply all WSL profiles that are associated to a Windows host machine from the Landscape web portal. To do this: + +1. Find the Windows machine that you want to apply WSL profiles. This can be found by clicking the link under **Associated Parents** in the **WSL profiles** page or by going to the **Computers** page. +2. Click the name of the Windows machine that you want to make compliant. +3. Click on the **WSL** tab. +4. Click on **Make Compliant** +5. Type "make {the name of your Windows host machine}" + +This will create activities to provision WSL instances on specified Windows host machines for all associated WSL profiles. + +## Apply all WSL profiles by Windows host machine using the Landscape API + +You can reapply all WSL profiles on specified Windows host machines via Landscape's REST API. + +```bash +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' +``` diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md index 31d63198..ea1cd744 100644 --- a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -115,6 +115,7 @@ Optional parameters: - `image_source`: The URL or file path for the rootfs image. - `cloud_init_contents`: The base64-encoded cloud init file contents. +- `only_landscape_created`: If true, this profile will delete WSL instances that were not created by Landscape from the associated Windows host machines; defaults to false. - `access_group`: Name of the access group the profile applies to; defaults to Global Access. - `tags`: A list of tag names to associate with the profile. - `all_computers`: If true, this profile will be associated with all computers; defaults to false. From 7145f95d8302d36cf5ae310c7c49494b52f6adcf Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 31 Jul 2025 15:34:29 -0700 Subject: [PATCH 033/187] add rootfs to spelling --- docs/.sphinx/.wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt index be5021a1..19803940 100644 --- a/docs/.sphinx/.wordlist.txt +++ b/docs/.sphinx/.wordlist.txt @@ -51,6 +51,8 @@ ReadMe reST reStructuredText roadmap +rootfs +RootFS RTD subdirectories subfolders From a9fe8a708b983df90ff2c6c3d7ecf153a6575532 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 31 Jul 2025 15:35:11 -0700 Subject: [PATCH 034/187] fix some UI references --- docs/how-to-guides/wsl-integration/use-wsl-profiles.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md index 9ef95d68..a1211611 100644 --- a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md +++ b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md @@ -55,14 +55,18 @@ curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/Ja You can apply all WSL profiles that are associated to a Windows host machine from the Landscape web portal. To do this: -1. Find the Windows machine that you want to apply WSL profiles. This can be found by clicking the link under **Associated Parents** in the **WSL profiles** page or by going to the **Computers** page. +1. Find the Windows machine that you want to apply WSL profiles. This can be found by clicking the link under **Associated parents** in the **WSL profiles** page or by going to the **Instances** page. 2. Click the name of the Windows machine that you want to make compliant. 3. Click on the **WSL** tab. 4. Click on **Make Compliant** -5. Type "make {the name of your Windows host machine}" +5. Type "make {the name of your Windows host machine} compliant" This will create activities to provision WSL instances on specified Windows host machines for all associated WSL profiles. +```{note} +The **Make compliant** button will be hidden if the Windows machine has no associated WSL profiles. +``` + ## Apply all WSL profiles by Windows host machine using the Landscape API You can reapply all WSL profiles on specified Windows host machines via Landscape's REST API. From 3f193f6140ca48d637683c6ea5cd0060a7ec4b69 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Fri, 1 Aug 2025 15:21:59 -0700 Subject: [PATCH 035/187] changes --- docs/.sphinx/.wordlist.txt | 2 +- .../wsl-integration/use-wsl-profiles.md | 49 +++++++++---------- 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt index 19803940..4d66fcc9 100644 --- a/docs/.sphinx/.wordlist.txt +++ b/docs/.sphinx/.wordlist.txt @@ -52,7 +52,7 @@ reST reStructuredText roadmap rootfs -RootFS +Rootfs RTD subdirectories subfolders diff --git a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md index a1211611..150bf78c 100644 --- a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md +++ b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md @@ -2,53 +2,53 @@ # How to use WSL profiles +> See also: {ref}`reference-rest-api-child-instance-profiles` and {ref}`reference-rest-api-wsl` REST API endpoints. + ```{note} This feature is currently in beta. ``` -> See also: {ref}`reference-rest-api-child-instance-profiles` and {ref}`reference-rest-api-wsl`. +## Background information -This guide describes how to use WSL profiles (also called child instance profiles) to provision WSL instances and manage them with Landscape. +Child instance profiles are configurations specifying the containers, VMs, or other virtual instances running on a machine registered with Landscape. Currently, WSL profiles are the only type of child instance profile that we support. -## Create a WSL profile in the Landscape web portal +WSL profiles are configurations that specify the WSL instances to be provisioned on associated Windows machines. Each WSL profile corresponds to one WSL instance with a unique rootfs image name. A Windows host machine is considered compliant with a WSL profile if it has installed a corresponding WSL instance that is registered with Landscape, or has an activity to do so. Otherwise, the Windows machine is considered non-compliant with the WSL profile. This guide describes how to use WSL profiles to provision WSL instances and manage them with Landscape. -You can create a new WSL profile from the Landscape web portal. To do this: +## Create a WSL profile in the Landscape web portal -1. Click **Profiles** -2. Click **WSL profiles** -3. Click **Add WSL profile** +To create a new WSL profile from the Landscape web portal, go to **Profiles** > **WSL profiles** > **Add WSL profile**. -In the WSL profile creation form, complete the following fields: +Then complete the relevant fields: -- **Title**: A title for the profile. -- **Description**: A human readable description for the profile. +- **Title**: A title for the profile. For example, "Ubuntu 24.04" +- **Description**: A description for the profile. For example, "Install 24.04 LTS WSL instance" - **Access group**: The access group the profile will apply to. Restricts which instances the profile can manage and which users can edit and execute the profile. -- **RootFS image**: The URL or file path for the RootFS image. -- **Cloud-init**: The contents of the cloud init to be supplied to the WSL instance. This can be uploaded as a file or inputted as text. -- **Association**: +- **Rootfs image**: The rootfs image to be installed. These correspond to the available WSL Ubuntu releases on the Microsoft Store. The Ubuntu image corresponds to the latest release available on the store and will give the WSL instance the ability to upgrade to the next release when it is available. If you have a custom rootfs image, you can provide the URL instead by selecting **From URL**. If you want multiple copies of the same rootfs image, you must use the **From URL** selection and provide a unique name. + - **Image name**: The name of the rootfs image that will be installed on the WSL instance. This field only appears if you select **From URL** for the **Rootfs image**. + - **Rootfs image URL**: The URL of the rootfs image that will be installed on the WSL instance. This URL must be reachable by the affected WSL instances. See {ref}`how-to-wsl-use-specific-image-source` for instructions on ensuring the WSL instance can reach the provided rootfs image URL. This field only appears if you select **From URL** for the **Rootfs image**. +- **Cloud-init** (optional): The contents of the cloud-init to be supplied to the WSL instance. This can be uploaded as a file or inputted as text. +- **Association** (optional): - **Associate to all instances**: The profile will affect all instances in the same access group as the profile - **Tag(s)**: Only instances having the specific tag(s), in the same access group as the profile will be affected -After you've created your WSL profile, activities will be created to install the specified WSL instance on the associated Windows host machines. -A Windows host machine is considered compliant with a WSL profile if it has the corresponding WSL instance that is created by Landscape. +After you've added your WSL profile, activities will be created to install the specified WSL instance on the associated Windows host machines. -You can view, edit, duplicate, or remove the profile using the dot menu under **Actions**. You can also see the number of associated parents and the number of compliant or non-compliant Windows host machines. +You can edit, duplicate, or remove the profile using the dot menu under **Actions**. You can also see the number of associated parents and the number of compliant or non-compliant Windows host machines. ## Create a WSL profile using the Landscape API -You can create a WSL profile via Landscape's REST API. +To create a WSL profile via Landscape's REST API, see the following example command: ```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "JammyProfile", "description": "Jammy", "image_name": "Ubuntu-22.04", "all_computers": "true"}' +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles -H "Authorization: Bearer $JWT" -d '{"title": "NobleProfile", "description": "Noble", "image_name": "Ubuntu-24.04", "all_computers": "true"}' ``` ## Reapply a WSL profile using the Landscape API -Activities to install the corresponding WSL instance are automatically created when a Windows host machine is associated with a WSL profile. -If you want to fix any non-compliant Windows host machines, you can reapply a WSL profile via Landscape's REST API. +Activities to install the corresponding WSL instance are automatically created when a Windows host machine is associated with a WSL profile. If you want to fix any non-compliant Windows host machines, you can reapply a WSL profile via Landscape's REST API. See the following example command: ```bash -curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/JammyProfile:reapply -H "Authorization: Bearer $JWT" +curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/NobleProfile:reapply -H "Authorization: Bearer $JWT" ``` ## Apply all WSL profiles by Windows host machine in the Landscape web portal @@ -58,18 +58,17 @@ You can apply all WSL profiles that are associated to a Windows host machine fro 1. Find the Windows machine that you want to apply WSL profiles. This can be found by clicking the link under **Associated parents** in the **WSL profiles** page or by going to the **Instances** page. 2. Click the name of the Windows machine that you want to make compliant. 3. Click on the **WSL** tab. -4. Click on **Make Compliant** -5. Type "make {the name of your Windows host machine} compliant" +4. Click **Make compliant** and complete the prompt. This will create activities to provision WSL instances on specified Windows host machines for all associated WSL profiles. ```{note} -The **Make compliant** button will be hidden if the Windows machine has no associated WSL profiles. +The **Make compliant** button is hidden for Windows machines that have no associated WSL profiles. ``` ## Apply all WSL profiles by Windows host machine using the Landscape API -You can reapply all WSL profiles on specified Windows host machines via Landscape's REST API. +To reapply all WSL profiles on specified Windows host machines via Landscape's REST API, see the following example command: ```bash curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' From 3c7e1cc5f45912275b66e0e0ae7e788f4f49d3f6 Mon Sep 17 00:00:00 2001 From: YanisaHS Date: Mon, 4 Aug 2025 12:34:31 -0500 Subject: [PATCH 036/187] wording changes --- .../wsl-integration/use-wsl-profiles.md | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md index 150bf78c..a47fe587 100644 --- a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md +++ b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md @@ -8,11 +8,19 @@ This feature is currently in beta. ``` +This guide describes how to use WSL profiles to provision WSL instances and manage them with Landscape. + ## Background information -Child instance profiles are configurations specifying the containers, VMs, or other virtual instances running on a machine registered with Landscape. Currently, WSL profiles are the only type of child instance profile that we support. +In Landscape, a child instance profile is a configuration that defines the virtual instances, such as containers or VMs, that run on a machine registered with Landscape. Currently, WSL profiles are the only type of child instance profile supported. + +WSL profiles specify the WSL instance to be provisioned on a Windows host machine. Each WSL profile corresponds to a single WSL instance with a unique rootfs image name. You also have the option to configure your WSL instance with a cloud-init file. -WSL profiles are configurations that specify the WSL instances to be provisioned on associated Windows machines. Each WSL profile corresponds to one WSL instance with a unique rootfs image name. A Windows host machine is considered compliant with a WSL profile if it has installed a corresponding WSL instance that is registered with Landscape, or has an activity to do so. Otherwise, the Windows machine is considered non-compliant with the WSL profile. This guide describes how to use WSL profiles to provision WSL instances and manage them with Landscape. +A Windows host machine is considered **compliant** with a WSL profile if it meets one of these criteria: + - It has an installed WSL instance that's registered with Landscape and matches the profile, or + - It has an activity to provision and register the corresponding WSL instance. + +A Windows machine that doesn't meet either of these criteria is considered **non-compliant** with the WSL profile. ## Create a WSL profile in the Landscape web portal @@ -23,17 +31,17 @@ Then complete the relevant fields: - **Title**: A title for the profile. For example, "Ubuntu 24.04" - **Description**: A description for the profile. For example, "Install 24.04 LTS WSL instance" - **Access group**: The access group the profile will apply to. Restricts which instances the profile can manage and which users can edit and execute the profile. -- **Rootfs image**: The rootfs image to be installed. These correspond to the available WSL Ubuntu releases on the Microsoft Store. The Ubuntu image corresponds to the latest release available on the store and will give the WSL instance the ability to upgrade to the next release when it is available. If you have a custom rootfs image, you can provide the URL instead by selecting **From URL**. If you want multiple copies of the same rootfs image, you must use the **From URL** selection and provide a unique name. - - **Image name**: The name of the rootfs image that will be installed on the WSL instance. This field only appears if you select **From URL** for the **Rootfs image**. - - **Rootfs image URL**: The URL of the rootfs image that will be installed on the WSL instance. This URL must be reachable by the affected WSL instances. See {ref}`how-to-wsl-use-specific-image-source` for instructions on ensuring the WSL instance can reach the provided rootfs image URL. This field only appears if you select **From URL** for the **Rootfs image**. +- **Rootfs image**: The rootfs image to be installed. These correspond to the available WSL Ubuntu releases on the Microsoft Store. The Ubuntu image corresponds to the latest release available on the store and will give the WSL instance the ability to upgrade to the next release when it's available. If you have a custom rootfs image, you can provide the URL instead by selecting **From URL**. If you want multiple copies of the same rootfs image, you must use the **From URL** selection and provide a unique name. + - **Image name**: The name of the rootfs image that will be installed on the WSL instance. + - **Rootfs image URL**: The URL of the rootfs image that will be installed on the WSL instance. This URL must be reachable by the affected WSL instances. For instructions on ensuring the WSL instance can reach the provided rootfs image URL, see {ref}`how-to-wsl-use-specific-image-source`. - **Cloud-init** (optional): The contents of the cloud-init to be supplied to the WSL instance. This can be uploaded as a file or inputted as text. - **Association** (optional): - - **Associate to all instances**: The profile will affect all instances in the same access group as the profile - - **Tag(s)**: Only instances having the specific tag(s), in the same access group as the profile will be affected + - **Associate to all instances**: The profile will affect all instances in the same access group as the profile. + - **Tag(s)**: Only instances having the specific tag(s), in the same access group as the profile will be affected. After you've added your WSL profile, activities will be created to install the specified WSL instance on the associated Windows host machines. -You can edit, duplicate, or remove the profile using the dot menu under **Actions**. You can also see the number of associated parents and the number of compliant or non-compliant Windows host machines. +You can edit or remove the profile using the dot menu under **Actions**. You can also see the number of associated parents and the number of compliant or non-compliant Windows host machines. ## Create a WSL profile using the Landscape API @@ -55,7 +63,7 @@ curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/No You can apply all WSL profiles that are associated to a Windows host machine from the Landscape web portal. To do this: -1. Find the Windows machine that you want to apply WSL profiles. This can be found by clicking the link under **Associated parents** in the **WSL profiles** page or by going to the **Instances** page. +1. Find the Windows machine that you want to apply WSL profiles. To find this, click the link under **Associated parents** in the **WSL profiles** page, or by go to the **Instances** page. 2. Click the name of the Windows machine that you want to make compliant. 3. Click on the **WSL** tab. 4. Click **Make compliant** and complete the prompt. From 4a5c14ccb020769b3edaa62d58f9e51776c89896 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Mon, 4 Aug 2025 10:44:11 -0700 Subject: [PATCH 037/187] looks good --- docs/how-to-guides/wsl-integration/use-wsl-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md index a47fe587..90f3f6dd 100644 --- a/docs/how-to-guides/wsl-integration/use-wsl-profiles.md +++ b/docs/how-to-guides/wsl-integration/use-wsl-profiles.md @@ -63,7 +63,7 @@ curl -X POST https://your-landscape.domain.com/api/v2/child-instance-profiles/No You can apply all WSL profiles that are associated to a Windows host machine from the Landscape web portal. To do this: -1. Find the Windows machine that you want to apply WSL profiles. To find this, click the link under **Associated parents** in the **WSL profiles** page, or by go to the **Instances** page. +1. Find the Windows machine that you want to apply WSL profiles. To find this, click the link under **Associated parents** in the **WSL profiles** page, or by going to the **Instances** page. 2. Click the name of the Windows machine that you want to make compliant. 3. Click on the **WSL** tab. 4. Click **Make compliant** and complete the prompt. From 97340b5286c2ba708822d66ed4697ea4e6500b87 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Tue, 5 Aug 2025 18:32:18 -0600 Subject: [PATCH 038/187] feat: create table of all possible immutable settings (#30) --- docs/reference/config/immutable-settings.md | 25 +++++++++++++++++++++ docs/reference/config/index.md | 9 ++++++++ docs/reference/index.md | 3 ++- 3 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 docs/reference/config/immutable-settings.md create mode 100644 docs/reference/config/index.md diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md new file mode 100644 index 00000000..4ba7e92d --- /dev/null +++ b/docs/reference/config/immutable-settings.md @@ -0,0 +1,25 @@ +(reference-immutable-settings)= + +# Immutable configuration settings + +The following immutable configurations can be set in `service.conf` or through environment variables: + +| Deprecated ENV name | New ENV name | Deprecated section of `service.conf` | Section of `service.conf` | Deprecated key name in `service.conf` | Key name in `service.conf` | Default value | Purpose | +| :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | +| `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | +| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_GLOBAL__ROOT_URL` | `global` | `global` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | +| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_GLOBAL__LICENSE_FILE` | `N/A` | `global` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | +| `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_FEATURES__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `features` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | +| `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_FEATURES__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `features` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | +| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | +| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_GLOBAL__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | +| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_GLOBAL__GPG_HOME_DIR` | `N/A` | `global` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `LANDSCAPE_FQDN` | `LANDSCAPE_GLOBAL__FQDN` | `N/A` | `global` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | +| `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_GLOBAL__MIDDLEWARE` | `N/A` | `global` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | +| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_GLOBAL__ANALYTICS_ID` | `N/A` | `global` | `N/A` | `google_analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | +| `LANDSCAPE_APT_PORT` | `LANDSCAPE_GLOBAL__APT_PORT` | `N/A` | `global` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | +| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `secrets` | `secrets` | `secrets-service-url` | `secrets_service_url` | `None` | If provided through an environment variable, it’s expected to be the token itself. If set in `service.conf` it’s expected to be the URL of the secrets service to get the token from. | +| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `None` | The URL to use for the secrets service. | +| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_FEATURES__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `features` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | +| `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | +| `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | diff --git a/docs/reference/config/index.md b/docs/reference/config/index.md new file mode 100644 index 00000000..a9ad4e17 --- /dev/null +++ b/docs/reference/config/index.md @@ -0,0 +1,9 @@ +(reference-config-index)= +# Configuration + +```{toctree} +:titlesonly: +:maxdepth: 2 +:glob: + +immutable-settings \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index 07a4ecd6..4bff1f21 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -9,7 +9,8 @@ This section includes technical information you may need to reference when using :glob: api/index +config/index release-notes/index logs/index networking/index -terms/index \ No newline at end of file +terms/index From 4f075c4029bf5f957d0e2e431c1efc5257e7578d Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 6 Aug 2025 15:38:07 +0000 Subject: [PATCH 039/187] refactor: move api doc (#31) --- .../child-instance-profiles.md | 26 +++++++++++++++++++ docs/reference/api/rest-api-endpoints/wsl.md | 26 ------------------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md index ea1cd744..1cbbe72e 100644 --- a/docs/reference/api/rest-api-endpoints/child-instance-profiles.md +++ b/docs/reference/api/rest-api-endpoints/child-instance-profiles.md @@ -312,3 +312,29 @@ Example response: "activity_status": "delivered" } ``` + +## POST `/child-instance-profiles/make-hosts-compliant` + +Make the given Windows host computers compliant with all of their WSL profiles by reapplying them if needed. + +Required parameters: + +- `host_computer_ids`: The list of IDs of Windows computers to make compliant with their WSL profiles. + +Example requests: + +```sh +curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' +``` + +Example output: + +```json +{ + "computer_ids_reapplied_to": [ + 6, + 15 + ], + "message": "Successfully created activities for 2 Windows computers to make them compliant with their WSL profile(s)." +} +``` diff --git a/docs/reference/api/rest-api-endpoints/wsl.md b/docs/reference/api/rest-api-endpoints/wsl.md index 181fc90b..39495b9d 100644 --- a/docs/reference/api/rest-api-endpoints/wsl.md +++ b/docs/reference/api/rest-api-endpoints/wsl.md @@ -15,32 +15,6 @@ enable-wsl-child-instance-profiles = true to the `service.conf` file. -## POST `/child-instance-profiles/make-hosts-compliant` - -Make the given Windows host computers compliant with all of their WSL profiles by reapplying them if needed. - -Required parameters: - -- `host_computer_ids`: The list of IDs of Windows computers to make compliant with their WSL profiles. - -Example requests: - -```sh -curl -X POST https://landscape.canonical.com/api/v2/child-instance-profiles/make-hosts-compliant -H "Authorization: Bearer $JWT" -d '{"host_computer_ids": [6, 15]}' -``` - -Example output: - -```json -{ - "computer_ids_reapplied_to": [ - 6, - 15 - ], - "message": "Successfully created activities for 2 Windows computers to make them compliant with their WSL profile(s)." -} -``` - ## GET `/computers//children` Get information about the WSL instances associated with the computer. From 98b3a429c586e03d75979d5fd1bb1fabfcab54ce Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 6 Aug 2025 19:25:24 +0000 Subject: [PATCH 040/187] feat: add ENV only table (#32) * sort em * add LANDSCAPE_CONFIG_FILE and ENV only table --- docs/reference/config/immutable-settings.md | 30 ++++++++++++--------- 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 4ba7e92d..360111b2 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -6,20 +6,26 @@ The following immutable configurations can be set in `service.conf` or through e | Deprecated ENV name | New ENV name | Deprecated section of `service.conf` | Section of `service.conf` | Deprecated key name in `service.conf` | Key name in `service.conf` | Default value | Purpose | | :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | -| `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | -| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_GLOBAL__ROOT_URL` | `global` | `global` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | -| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_GLOBAL__LICENSE_FILE` | `N/A` | `global` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | +| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_GLOBAL__ANALYTICS_ID` | `N/A` | `global` | `N/A` | `google_analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | +| `LANDSCAPE_APT_PORT` | `LANDSCAPE_GLOBAL__APT_PORT` | `N/A` | `global` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | | `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_FEATURES__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `features` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | | `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_FEATURES__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `features` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | -| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | -| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_GLOBAL__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | -| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_GLOBAL__GPG_HOME_DIR` | `N/A` | `global` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_FEATURES__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `features` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | | `LANDSCAPE_FQDN` | `LANDSCAPE_GLOBAL__FQDN` | `N/A` | `global` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | +| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_GLOBAL__GPG_HOME_DIR` | `N/A` | `global` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_GLOBAL__LICENSE_FILE` | `N/A` | `global` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | +| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_GLOBAL__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | | `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_GLOBAL__MIDDLEWARE` | `N/A` | `global` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | -| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_GLOBAL__ANALYTICS_ID` | `N/A` | `global` | `N/A` | `google_analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | -| `LANDSCAPE_APT_PORT` | `LANDSCAPE_GLOBAL__APT_PORT` | `N/A` | `global` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | -| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `secrets` | `secrets` | `secrets-service-url` | `secrets_service_url` | `None` | If provided through an environment variable, it’s expected to be the token itself. If set in `service.conf` it’s expected to be the URL of the secrets service to get the token from. | -| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `None` | The URL to use for the secrets service. | -| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_FEATURES__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `features` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | -| `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | +| `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | +| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | +| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_GLOBAL__ROOT_URL` | `global` | `global` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | | `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | +| `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | +| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `None` | The URL to use for the secrets service. | +| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `secrets` | `secrets` | `secrets-service-url` | `secrets_service_url` | `None` | If provided through an environment variable, it’s expected to be the token itself. If set in `service.conf` it’s expected to be the URL of the secrets service to get the token from. | + +The following immutable configurations can be set through environment variables only: + +| ENV name | Default value | Purpose | +| :---- | :---- | :---- | +| `LANDSCAPE_CONFIG_FILE` | `/etc/landscape/service.conf` | File path location of the `service.conf` file. | From b036ed4701daa12c0e01a0b51e40d76083633a55 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Wed, 6 Aug 2025 16:03:34 -0600 Subject: [PATCH 041/187] feat!: remove `[grpc]` instructions (#33) --- docs/how-to-guides/upgrade/upgrade-to-24-04-lts.md | 4 ---- .../how-to-guides/wsl-integration/configure-landscape-beta.md | 4 ---- 2 files changed, 8 deletions(-) diff --git a/docs/how-to-guides/upgrade/upgrade-to-24-04-lts.md b/docs/how-to-guides/upgrade/upgrade-to-24-04-lts.md index d8bf4f4c..0f84d4b8 100644 --- a/docs/how-to-guides/upgrade/upgrade-to-24-04-lts.md +++ b/docs/how-to-guides/upgrade/upgrade-to-24-04-lts.md @@ -22,9 +22,6 @@ Add the following lines to your `service.conf` file. This is commonly located in hostagent_virtual_host = landscape-hostagent hostagent_task_queue = landscape-server-hostagent-task-queue -[grpc] -grpc.max_connection_age_ms = 2592000000 # 30 days - [hostagent-message-consumer] threads = 1 stores = main account-1 @@ -52,4 +49,3 @@ If you're upgrading a Landscape Server instance that was manually installed (ins - In your `service.conf` file, add an entry for `secret-token` in the `[landscape]` section and set it as a random string. You can set any string you want, but it should be reasonably long. You can use `openssl` to create a random string. For example, `openssl rand -base64 128 | tr -d '\n'`. - Update your Apache vhost if it wasn't already auto-upgraded - diff --git a/docs/how-to-guides/wsl-integration/configure-landscape-beta.md b/docs/how-to-guides/wsl-integration/configure-landscape-beta.md index 0d5c4316..4cbf6067 100644 --- a/docs/how-to-guides/wsl-integration/configure-landscape-beta.md +++ b/docs/how-to-guides/wsl-integration/configure-landscape-beta.md @@ -16,9 +16,6 @@ Open the `service.conf` file located in the `/etc/landscape` directory and add t hostagent_virtual_host = landscape-hostagent hostagent_task_queue = landscape-server-hostagent-task-queue -[grpc] -grpc.max_connection_age_ms = 2592000000 # 30 days - [hostagent-message-consumer] threads = 1 stores = main account-1 @@ -88,4 +85,3 @@ sudo service landscape-hostagent-consumer restart ``` Done! Now you're ready to use WSL with Landscape. If you want instructions on setting up your environment, see {ref}`how-to-wsl-set-up-environment`. If you already have a Windows machine set up with WSL and Ubuntu, see {ref}`how-to-register-wsl-hosts`. - From 6970b49b218674d972978b46630b9dcbc28af190 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 7 Aug 2025 09:03:19 -0700 Subject: [PATCH 042/187] add line about allowed_interfaces --- .../landscape-installation-and-set-up/manual-installation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md index e27bad02..ebf7c36e 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md @@ -200,6 +200,7 @@ Section `[landscape]`: * Add an entry for `secret-token` and set it as a random string. You can set any string you want, but it should be reasonably long. You can use `openssl` to create a random string. For example, `openssl rand -base64 128 | tr -d '\n'`. +If you want the services to allow only certain interfaces, you can set `allowed_interfaces` in each of the services listed in the configuration file. These must be space-separated IP addresses or hostnames. ### Run the Landscape setup script From 6b120c55d8b0c87e3101198338fcc6fe8fe49b6a Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 7 Aug 2025 11:08:47 -0700 Subject: [PATCH 043/187] spelling --- .../landscape-installation-and-set-up/manual-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md index ebf7c36e..000c6abf 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md @@ -200,7 +200,7 @@ Section `[landscape]`: * Add an entry for `secret-token` and set it as a random string. You can set any string you want, but it should be reasonably long. You can use `openssl` to create a random string. For example, `openssl rand -base64 128 | tr -d '\n'`. -If you want the services to allow only certain interfaces, you can set `allowed_interfaces` in each of the services listed in the configuration file. These must be space-separated IP addresses or hostnames. +If you want the services to allow only certain interfaces, you can set `allowed_interfaces` in each of the services listed in the configuration file. These must be space-separated IP addresses or host names. ### Run the Landscape setup script From dd6343cf18384efbdaf1cb73180f0004fcc5a833 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 7 Aug 2025 15:06:34 -0700 Subject: [PATCH 044/187] add example --- docs/.custom_wordlist.txt | 3 ++- .../manual-installation.md | 6 +++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index ee229c2f..ee6d1b57 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -133,6 +133,7 @@ Livepatch Livepatches livepatching logfile +localhost loopback LXC LXD @@ -359,4 +360,4 @@ CBID MikeT gh Owsalla -TropicolX \ No newline at end of file +TropicolX diff --git a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md index 000c6abf..f30aea95 100644 --- a/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md +++ b/docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md @@ -200,7 +200,11 @@ Section `[landscape]`: * Add an entry for `secret-token` and set it as a random string. You can set any string you want, but it should be reasonably long. You can use `openssl` to create a random string. For example, `openssl rand -base64 128 | tr -d '\n'`. -If you want the services to allow only certain interfaces, you can set `allowed_interfaces` in each of the services listed in the configuration file. These must be space-separated IP addresses or host names. +If you want the services to allow only certain interfaces, you can set `allowed_interfaces` in each of the services listed in the configuration file. These must be space-separated IP addresses or host names. For example, to only allow connections on localhost, you may have a configuration like the following: + +```bash +allowed_interfaces = localhost 127.0.0.1 ::1 +``` ### Run the Landscape setup script From e9e99ca6315be0cd78dc28f7580a310bf54214ff Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Fri, 8 Aug 2025 20:36:14 +0000 Subject: [PATCH 045/187] feat: start service.conf docs; add system settings section (#35) --- docs/reference/config/immutable-settings.md | 16 ++++---- docs/reference/config/index.md | 3 +- docs/reference/config/service-conf.md | 42 +++++++++++++++++++++ 3 files changed, 52 insertions(+), 9 deletions(-) create mode 100644 docs/reference/config/service-conf.md diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 360111b2..93f77818 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -6,19 +6,19 @@ The following immutable configurations can be set in `service.conf` or through e | Deprecated ENV name | New ENV name | Deprecated section of `service.conf` | Section of `service.conf` | Deprecated key name in `service.conf` | Key name in `service.conf` | Default value | Purpose | | :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | -| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_GLOBAL__ANALYTICS_ID` | `N/A` | `global` | `N/A` | `google_analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | -| `LANDSCAPE_APT_PORT` | `LANDSCAPE_GLOBAL__APT_PORT` | `N/A` | `global` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | +| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `N/A` | `system` | `N/A` | `analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | +| `LANDSCAPE_APT_PORT` | `LANDSCAPE_SYSTEM__APT_PORT` | `N/A` | `system` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | | `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_FEATURES__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `features` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | | `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_FEATURES__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `features` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | | `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_FEATURES__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `features` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | -| `LANDSCAPE_FQDN` | `LANDSCAPE_GLOBAL__FQDN` | `N/A` | `global` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | -| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_GLOBAL__GPG_HOME_DIR` | `N/A` | `global` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | -| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_GLOBAL__LICENSE_FILE` | `N/A` | `global` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | -| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_GLOBAL__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | -| `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_GLOBAL__MIDDLEWARE` | `N/A` | `global` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | +| `LANDSCAPE_FQDN` | `LANDSCAPE_SYSTEM__FQDN` | `N/A` | `system` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | +| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `N/A` | `system` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `N/A` | `system` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | +| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_SYSTEM__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | +| `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `N/A` | `system` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | | `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | | `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | -| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_GLOBAL__ROOT_URL` | `global` | `global` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | +| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_SYSTEM__ROOT_URL` | `global` | `system` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | | `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | | `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | | `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `None` | The URL to use for the secrets service. | diff --git a/docs/reference/config/index.md b/docs/reference/config/index.md index a9ad4e17..541c0372 100644 --- a/docs/reference/config/index.md +++ b/docs/reference/config/index.md @@ -6,4 +6,5 @@ :maxdepth: 2 :glob: -immutable-settings \ No newline at end of file +immutable-settings +service-conf diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md new file mode 100644 index 00000000..ccd496e8 --- /dev/null +++ b/docs/reference/config/service-conf.md @@ -0,0 +1,42 @@ +(reference-service-conf)= + +# The `service.conf` file + +All Landscape service configurations are defined in the `service.conf` file. This file follows the `INI` file format. The default location for this file is `/etc/landscape/service.conf`. You can override that by setting the `LANDSCAPE_SERVICE_CONF` environment variable with the file path location of the `service.conf` file. + +Changes to the `service.conf` file only take affect once you restart the relevant service(s). + +Starting with Landscape 25.10, every entry in the `service.conf` file can be overridden by a corresponding environment variable. These variables have the following general structure: `LANDSCAPE_SECTION_NAME__KEY_NAME`. + +The sections below contain information about the key-value pairs that can be set in each section, the corresponding environment variable, the default value (if any), and the purpose of the entry. + +```{note} +The usage of the `-` character in section names and key names is deprecated in Landscape Server 25.10 in favor of the `_` character. Support for the `-` character will be removed in Landscape Server 26.04. + +In addition, the names of some sections of the `service.conf` file are deprecated in Landscape Server 25.10. The new names are detailed below. Support for the deprecated names will be removed in Landscape Server 26.04. +``` + +## The `[system]` section + +```{note} +The `[global]` section name is deprecated. The `[system]` section replaces the `[global]` section. +``` + +The `[system]` section contains configurations that apply across many or all of Landscape's services. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `analytics_id` | - | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | +| `apt_port` | - | `LANDSCAPE_SYSTEM__APT_PORT` | 8085 | The port the `landscape_apt` service should use. | +| `audit_retention_period` | `audit-retention-period` | `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` | `-1` | The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. | +| `deployment_mode` | `deployment-mode` | `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` | `standalone` | Used only for development. The default value is appropriate for self-hosted Landscape. | +| `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | +| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | +| {spellexception}`pidfile_directory` | {spellexception}`pidfile-directory` | {spellexception}`LANDSCAPE_SYSTEM__PIDFILE_DIRECTORY` | `/tmp/landscape` | Unused | +| `max_service_memory` | `max-service-memory` | `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` | `0` | An upper limit (in {spellexception}`mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. | +| `middleware` | - | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | +| `offline` | - | `LANDSCAPE_SYSTEM__OFFLINE` | `None` | Set `True` if Landscape is deployed in an air-gapped environment. | +| `oops_path` | `oops-path` | `LANDSCAPE_SYSTEM__OOPS_PATH` | `/var/lib/landscape/landscape-oops` | The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. | +| `root_url` | `root-url` | `LANDSCAPE_SYSTEM__ROOT_URL` | `http://localhost:8080` | Landscape Server's root URL path. | +| `syslog_address` | `syslog-address` | `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` | `/dev/log` | Path to the system's syslog logger. | From ebd8fe9affcbdaddfa560912fde987e1eb89374e Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 11 Aug 2025 19:18:16 +0000 Subject: [PATCH 046/187] feat: add async frontend settings (#37) --- docs/reference/config/service-conf.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index ccd496e8..021887ac 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -40,3 +40,9 @@ The `[system]` section contains configurations that apply across many or all of | `oops_path` | `oops-path` | `LANDSCAPE_SYSTEM__OOPS_PATH` | `/var/lib/landscape/landscape-oops` | The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. | | `root_url` | `root-url` | `LANDSCAPE_SYSTEM__ROOT_URL` | `http://localhost:8080` | Landscape Server's root URL path. | | `syslog_address` | `syslog-address` | `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` | `/dev/log` | Path to the system's syslog logger. | + +## The `[async_frontend]` section + +The `[async_frontend]` section contains configurations that apply to the `landscape-async-frontend` service which handles AJAX requests from the Legacy UI. It has no settings beyond those shared by all services. + +In practice, only the `base_port` setting needs to be configured for the service to operate correctly. From cf7cf35c2d69e6676e39f846e040f34fb059e31d Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Mon, 11 Aug 2025 17:14:53 -0600 Subject: [PATCH 047/187] refactor: separate `VAULT_TOKEN` from `LANDSCAPE_SECRETS__SERVICE_URL`, add default for `vault_url` (#38) --- docs/reference/config/immutable-settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 93f77818..f68e6ff8 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -21,8 +21,8 @@ The following immutable configurations can be set in `service.conf` or through e | `LANDSCAPE_ROOT_URL` | `LANDSCAPE_SYSTEM__ROOT_URL` | `global` | `system` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | | `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | | `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | -| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `None` | The URL to use for the secrets service. | -| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `secrets` | `secrets` | `secrets-service-url` | `secrets_service_url` | `None` | If provided through an environment variable, it’s expected to be the token itself. If set in `service.conf` it’s expected to be the URL of the secrets service to get the token from. | +| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `http://localhost:8200` | The address of the vault to use for the secrets service. | +| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `N/A` | `secrets` | `N/A` | `vault_token` | `None` | The token to use for the vault instead of getting it from the secrets service. | The following immutable configurations can be set through environment variables only: From eda6defc12f06943b45effeb9e21d5eecd7a6ea5 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 12 Aug 2025 00:00:53 +0000 Subject: [PATCH 048/187] feat: add job handler settings section (#39) --- docs/reference/config/service-conf.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 021887ac..d961ef7b 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -43,6 +43,20 @@ The `[system]` section contains configurations that apply across many or all of ## The `[async_frontend]` section +```{note} +The `[async-frontend]` section name is deprecated. The `[async_frontend]` section replaces the `[async-frontend]` section. +``` + The `[async_frontend]` section contains configurations that apply to the `landscape-async-frontend` service which handles AJAX requests from the Legacy UI. It has no settings beyond those shared by all services. In practice, only the `base_port` setting needs to be configured for the service to operate correctly. + +## The `[job_handler]` section + +```{note} +The `[job-handler]` section name is deprecated. The `[job_handler]` section replaces the `[job-handler]` section. +``` + +The `[job_handler]` section contains configurations for the `landscape-job-handler` service which runs background jobs. It has no settings beyond those shared by all services. + +In practice, only the `base_port` setting needs to be configured for the service to operate correctly. From ea805f7afcc9722ac2c2b7e70ab50265f8bc4a60 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Mon, 11 Aug 2025 17:11:06 -0700 Subject: [PATCH 049/187] feat: broker settings documentation (#36) --- docs/reference/config/service-conf.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index d961ef7b..f79908c8 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -51,6 +51,22 @@ The `[async_frontend]` section contains configurations that apply to the `landsc In practice, only the `base_port` setting needs to be configured for the service to operate correctly. +## The `[broker]` section + +The `[broker]` section contains configurations that describe how services connect to our message queues. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `host` | - | `LANDSCAPE_BROKER__HOST` | `localhost` | The hostname or IP address of the message broker server. | +| `hostagent_command_status_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_COMMAND_STATUS_QUEUE` | `landscape-server-hostagent-command-status-queue` | Queue for sending command status updates from the hostagent server to the hostagent consumer. | +| `hostagent_ping_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_PING_QUEUE` | `landscape-server-hostagent-ping-queue` | Queue for sending pings from the hostagent server to the hostagent consumer. | +| `hostagent_task_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_TASK_QUEUE` | `landscape-server-hostagent-task-queue` | Queue for sending tasks from the hostagent consumer to the hostagent server. | +| `hostagent_virtual_host` | - | `LANDSCAPE_BROKER__HOSTAGENT_VIRTUAL_HOST` | `landscape-hostagent` | The virtual host of message queues for the hostagent message server and consumer. This provides support for Landscape integration with Ubuntu Pro for WSL. | +| `password` | - | `LANDSCAPE_BROKER__PASSWORD` | `guest` | Password used to authenticate with the message broker. | +| `port` | - | `LANDSCAPE_BROKER__PORT` | 5672 | Network port where message broker server is listening. | +| `user` | - | `LANDSCAPE_BROKER__USER` | `guest` | Username used to authenticate with the message broker. | +| `vhost` | - | `LANDSCAPE_BROKER__VHOST` | `landscape` | The virtual host namespace. | + ## The `[job_handler]` section ```{note} From aa5baf5ecc47ede5cd377773e6ae7123181c8cb9 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Tue, 12 Aug 2025 15:50:42 +0000 Subject: [PATCH 050/187] feat: add message server settings (#40) --- docs/reference/config/immutable-settings.md | 2 +- docs/reference/config/service-conf.md | 17 +++++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index f68e6ff8..137176bb 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -14,7 +14,7 @@ The following immutable configurations can be set in `service.conf` or through e | `LANDSCAPE_FQDN` | `LANDSCAPE_SYSTEM__FQDN` | `N/A` | `system` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | | `LANDSCAPE_GPG_HOME` | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `N/A` | `system` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | | `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `N/A` | `system` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | -| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_SYSTEM__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use | +| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use. | | `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `N/A` | `system` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | | `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | | `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index f79908c8..764ec2e9 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -76,3 +76,20 @@ The `[job-handler]` section name is deprecated. The `[job_handler]` section repl The `[job_handler]` section contains configurations for the `landscape-job-handler` service which runs background jobs. It has no settings beyond those shared by all services. In practice, only the `base_port` setting needs to be configured for the service to operate correctly. + +## The `[message_server]` section + +```{note} +The `[message-server]` section name is deprecated. The `[message_server]` section replaces the `[message-server]` section. +``` + +The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. + +It has the following settings beyond those shared by all services. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `max_msg_size_bytes` | `max-msg-size-bytes` | `LANDSCAPE_MESSAGE_SERVER__MAX_MSG_SIZE_BYTES` | 30000000 (30 MB) | The maximum size, in bytes, of a message from Landscape Client that Landscape Server will accept. Messages larger than this size will be rejected. | +| `message_snippet_bytes` | `message-snippet-bytes` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SNIPPET_BYTES` | 1000 | When Landscape Server receives a message larger than `max_msg_size_bytes`, it will log an error including the first `message_snippet_bytes` of the message. | +| `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | +| `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | From d5e938711b2914f6eae03f2b27a40a9beb7cdc11 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Tue, 12 Aug 2025 16:28:26 -0600 Subject: [PATCH 051/187] feat: add `[stores]` section docs (#42) --- docs/reference/config/service-conf.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 764ec2e9..35206c4e 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -93,3 +93,29 @@ It has the following settings beyond those shared by all services. | `message_snippet_bytes` | `message-snippet-bytes` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SNIPPET_BYTES` | 1000 | When Landscape Server receives a message larger than `max_msg_size_bytes`, it will log an error including the first `message_snippet_bytes` of the message. | | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | | `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | + +## The `[stores]` section + +The `[stores]` section contains configurations for database store connections and SSL settings used across Landscape services. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `account_1` | `account-1` | `LANDSCAPE_STORES__ACCOUNT_1` | `landscape-standalone-account-1` | The first account database store name. | +| `account_2` | `account-2` | `LANDSCAPE_STORES__ACCOUNT_2` | `None` | The second account database store name. Optional. | +| `host` | - | `LANDSCAPE_STORES__HOST` | `localhost` | The hostname or IP address of the database server. | +| `knowledge` | - | `LANDSCAPE_STORES__KNOWLEDGE` | `landscape-standalone-knowledge` | The knowledge database name. | +| `main` | - | `LANDSCAPE_STORES__MAIN` | `landscape-standalone-main` | The main database name. | +| `package` | - | `LANDSCAPE_STORES__PACKAGE` | `landscape-standalone-package` | The package database name. | +| `password` | - | `LANDSCAPE_STORES__PASSWORD` | `None` | The password for database connections. | +| `resource_1` | `resource-1` | `LANDSCAPE_STORES__RESOURCE_1` | `landscape-standalone-resource-1` | The first resource database name. | +| `resource_2` | `resource-2` | `LANDSCAPE_STORES__RESOURCE_2` | `None` | The second resource database name. Optional and used for testing only. | +| `session` | - | `LANDSCAPE_STORES__SESSION` | `landscape-standalone-session` | The session database name. | +| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with {spellexception}`autocommit` isolation. | +| `sslcert` | - | `LANDSCAPE_STORES__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_STORES__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_STORES__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_STORES__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_STORES__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_STORES__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_STORES__STORES` | `None` | The stores the service should use. | +| `user` | - | `LANDSCAPE_STORES__USER` | `landscape` | The username for database connections. | From c75dece745b6cd40d8a5c831ec24440c889df55a Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Tue, 12 Aug 2025 16:38:25 -0600 Subject: [PATCH 052/187] feat: `[secrets]` section docs (#43) --- docs/reference/config/service-conf.md | 29 +++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 35206c4e..2756c53d 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -94,6 +94,35 @@ It has the following settings beyond those shared by all services. | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | | `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | +## The `[secrets]` section + +The `[secrets]` section contains configurations for the secrets service, including vault connection settings, service URLs, database store configurations, and SSL options. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | +| `base_port` | `base-port` | `LANDSCAPE_SECRETS__BASE_PORT` | `8090` | Base port number for the service. | +| `devmode` | - | `LANDSCAPE_SECRETS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SECRETS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SECRETS__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SECRETS__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | +| `mailer` | - | `LANDSCAPE_SECRETS__MAILER` | `None` | Mailer service configuration. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_SECRETS__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | +| `oops_key` | `oops-key` | `LANDSCAPE_SECRETS__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `service_url` | `secrets-service-url` | `LANDSCAPE_SECRETS__SERVICE_URL` | `None` | The URL to use for the secrets service. Must include a port. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SECRETS__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | +| `sslcert` | - | `LANDSCAPE_SECRETS__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_SECRETS__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_SECRETS__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_SECRETS__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_SECRETS__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_SECRETS__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_SECRETS__STORES` | `None` | The stores the service should use. | +| `threads` | - | `LANDSCAPE_SECRETS__THREADS` | `None` | Number of threads for the service. | +| `vault_token` | - | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `None` | The token to use for the vault instead of getting it from the secrets service. | +| `vault_url` | `secrets-url` | `LANDSCAPE_SECRETS__VAULT_URL` | `http://localhost:8200` | The address of the vault to use for the secrets service. | +| `workers` | - | `LANDSCAPE_SECRETS__WORKERS` | `None` | Number of worker processes for the service. | + ## The `[stores]` section The `[stores]` section contains configurations for database store connections and SSL settings used across Landscape services. From d123949875534e7c11152fb91eb392f995d8d530 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Tue, 12 Aug 2025 16:49:06 -0600 Subject: [PATCH 053/187] feat: add `[scripts]` section docs (#45) --- docs/reference/config/service-conf.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 2756c53d..253335c5 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -94,6 +94,32 @@ It has the following settings beyond those shared by all services. | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | | `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | +## The `[scripts]` section + +The `[scripts]` section contains configurations for the scripts service, including service operation settings, database store configurations, and SSL options. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | +| `base_port` | `base-port` | `LANDSCAPE_SCRIPTS__BASE_PORT` | `8090` | Base port number for the service. | +| `devmode` | - | `LANDSCAPE_SCRIPTS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SCRIPTS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SCRIPTS__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SCRIPTS__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | +| `mailer` | - | `LANDSCAPE_SCRIPTS__MAILER` | `None` | Mailer service configuration. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_SCRIPTS__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | +| `oops_key` | `oops-key` | `LANDSCAPE_SCRIPTS__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SCRIPTS__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | +| `sslcert` | - | `LANDSCAPE_SCRIPTS__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_SCRIPTS__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_SCRIPTS__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_SCRIPTS__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_SCRIPTS__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_SCRIPTS__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_SCRIPTS__STORES` | `None` | The stores the service should use. | +| `threads` | - | `LANDSCAPE_SCRIPTS__THREADS` | `None` | Number of threads for the service. | +| `workers` | - | `LANDSCAPE_SCRIPTS__WORKERS` | `None` | Number of worker processes for the service. | + ## The `[secrets]` section The `[secrets]` section contains configurations for the secrets service, including vault connection settings, service URLs, database store configurations, and SSL options. From 722eedad1c543298ec89990317aae083215cf3b5 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Tue, 12 Aug 2025 21:43:18 -0700 Subject: [PATCH 054/187] maintenance settings --- docs/reference/config/service-conf.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 253335c5..e1f8f9ce 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -77,6 +77,22 @@ The `[job_handler]` section contains configurations for the `landscape-job-handl In practice, only the `base_port` setting needs to be configured for the service to operate correctly. +## The `[maintenance]` section + +The `[maintenance]` section contains configurations for running maintenance scripts. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `sslcert` | - | `LANDSCAPE_MAINTENANCE__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_MAINTENANCE__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_MAINTENANCE__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_MAINTENANCE__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_MAINTENANCE__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_MAINTENANCE__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_MAINTENANCE__STORES` | `None` | The stores the service should use. | +| `threads` | - | `LANDSCAPE_MAINTENANCE__THREADS` | `None` | Number of threads for the service. | +| `workers` | - | `LANDSCAPE_MAINTENANCE__WORKERS` | `None` | Number of worker processes for the service. | + ## The `[message_server]` section ```{note} @@ -100,7 +116,7 @@ The `[scripts]` section contains configurations for the scripts service, includi | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | +| `allowed_interfaces` | - | `LANDSCAPE_SCRIPTS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | | `base_port` | `base-port` | `LANDSCAPE_SCRIPTS__BASE_PORT` | `8090` | Base port number for the service. | | `devmode` | - | `LANDSCAPE_SCRIPTS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | | `enable_metrics` | `enable-metrics` | `LANDSCAPE_SCRIPTS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | From ebe4145bac5e876f7e92166b489584ca11363611 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 13 Aug 2025 18:37:44 +0000 Subject: [PATCH 055/187] fix: add missing message server setting. (#49) --- docs/reference/config/service-conf.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 253335c5..16fd8775 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -83,12 +83,17 @@ In practice, only the `base_port` setting needs to be configured for the service The `[message-server]` section name is deprecated. The `[message_server]` section replaces the `[message-server]` section. ``` +```{note} +The `[backoff]` section is deprecated. The settings have been moved to the `[message_server]` section. +``` + The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. It has the following settings beyond those shared by all services. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | +| `backoff_dir` | `backoff-dirpath` | `LANDSCAPE_MESSAGE_SERVER__BACKOFF_DIR` | `None` | The directory to hold the `backoff.txt` file the server uses to indicate it should back off requests. If `None`, a `config` directory within the `landscape` directory will be used. | | `max_msg_size_bytes` | `max-msg-size-bytes` | `LANDSCAPE_MESSAGE_SERVER__MAX_MSG_SIZE_BYTES` | 30000000 (30 MB) | The maximum size, in bytes, of a message from Landscape Client that Landscape Server will accept. Messages larger than this size will be rejected. | | `message_snippet_bytes` | `message-snippet-bytes` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SNIPPET_BYTES` | 1000 | When Landscape Server receives a message larger than `max_msg_size_bytes`, it will log an error including the first `message_snippet_bytes` of the message. | | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | From 20532887359033c10188f94fb41202d8cbaf1978 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Wed, 13 Aug 2025 15:59:45 -0600 Subject: [PATCH 056/187] feat: add `[appserver]` docs (#48) --- docs/reference/config/service-conf.md | 96 ++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 17 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 16fd8775..41d56f89 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -16,30 +16,67 @@ The usage of the `-` character in section names and key names is deprecated in L In addition, the names of some sections of the `service.conf` file are deprecated in Landscape Server 25.10. The new names are detailed below. Support for the deprecated names will be removed in Landscape Server 26.04. ``` -## The `[system]` section +## The `[appserver]` section ```{note} -The `[global]` section name is deprecated. The `[system]` section replaces the `[global]` section. +The `[landscape]` section name is deprecated. The `[appserver]` section replaces the `[landscape]` section. ``` -The `[system]` section contains configurations that apply across many or all of Landscape's services. +The `[appserver]` section contains configurations for the Landscape application server, including storage paths, authentication providers, and security settings. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `analytics_id` | - | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | -| `apt_port` | - | `LANDSCAPE_SYSTEM__APT_PORT` | 8085 | The port the `landscape_apt` service should use. | -| `audit_retention_period` | `audit-retention-period` | `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` | `-1` | The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. | -| `deployment_mode` | `deployment-mode` | `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` | `standalone` | Used only for development. The default value is appropriate for self-hosted Landscape. | -| `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | -| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | -| `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | -| {spellexception}`pidfile_directory` | {spellexception}`pidfile-directory` | {spellexception}`LANDSCAPE_SYSTEM__PIDFILE_DIRECTORY` | `/tmp/landscape` | Unused | -| `max_service_memory` | `max-service-memory` | `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` | `0` | An upper limit (in {spellexception}`mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. | -| `middleware` | - | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | -| `offline` | - | `LANDSCAPE_SYSTEM__OFFLINE` | `None` | Set `True` if Landscape is deployed in an air-gapped environment. | -| `oops_path` | `oops-path` | `LANDSCAPE_SYSTEM__OOPS_PATH` | `/var/lib/landscape/landscape-oops` | The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. | -| `root_url` | `root-url` | `LANDSCAPE_SYSTEM__ROOT_URL` | `http://localhost:8080` | Landscape Server's root URL path. | -| `syslog_address` | `syslog-address` | `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` | `/dev/log` | Path to the system's syslog logger. | +| `access_log` | `access-log` | `LANDSCAPE_APPSERVER__ACCESS_LOG` | `None` | Path to access log file for this service. | +| `allowed_interfaces` | | `LANDSCAPE_APPSERVER__ALLOWED_INTERFACES` | `None` | Network interfaces allowed for connections. | +| `base_port` | `base-port` | `LANDSCAPE_APPSERVER__BASE_PORT` | `8090` | Base port number for the service. | +| `blob_storage_root` | `blob-storage-root` | `LANDSCAPE_APPSERVER__BLOB_STORAGE_ROOT` | `/var/lib/landscape/blobs` | Root directory for blob storage. | +| `devmode` | | `LANDSCAPE_APPSERVER__DEVMODE` | `None` | Development mode settings. | +| `display_consent_banner_at_each_login` | `display-consent-banner-at-each-login` | `LANDSCAPE_APPSERVER__DISPLAY_CONSENT_BANNER_AT_EACH_LOGIN` | `False` | Whether to display consent banner at each login. | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_APPSERVER__ENABLE_METRICS` | `False` | Whether to enable metrics collection. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_APPSERVER__GPG_HOME_PATH` | `None` | Path to GPG home directory. Must be used with `gpg_passphrase_path`. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_APPSERVER__GPG_PASSPHRASE_PATH` | `None` | Path to GPG passphrase file. Required when `gpg_home_path` is set. | +| `juju_homes_path` | `juju-homes-path` | `LANDSCAPE_APPSERVER__JUJU_HOMES_PATH` | `/var/tmp/juju-homes` | Path to Juju home directories. | +| `known_proxies` | `known-proxies` | `LANDSCAPE_APPSERVER__KNOWN_PROXIES` | `None` | Comma-separated names of known proxies. | +| `mailer` | | `LANDSCAPE_APPSERVER__MAILER` | `None` | Mailer type specification. Must be used with `mailer_path`. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_APPSERVER__MAILER_PATH` | `None` | Path to mailer executable. Required when `mailer` is set. | +| `oidc_client_id` | `oidc-client-id` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_ID` | `None` | OIDC client identifier. Required when using OIDC authentication. | +| `oidc_client_secret` | `oidc-client-secret` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_SECRET` | `None` | OIDC client secret. Required when using OIDC authentication. | +| `oidc_issuer` | `oidc-issuer` | `LANDSCAPE_APPSERVER__OIDC_ISSUER` | `None` | OIDC issuer URL. Required when using OIDC authentication. | +| `oidc_provider` | `oidc-provider` | `LANDSCAPE_APPSERVER__OIDC_PROVIDER` | `unspecified` | The name of OIDC provider to use. Must be either `google`, `okta`, or `unspecified`. | +| `oidc_redirect_uri` | `oidc-redirect-uri` | `LANDSCAPE_APPSERVER__OIDC_REDIRECT_URI` | `None` | OIDC redirect URI for authentication callbacks. | +| `oops_key` | `oops-key` | `LANDSCAPE_APPSERVER__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `openid_logout_url` | `openid-logout-url` | `LANDSCAPE_APPSERVER__OPENID_LOGOUT_URL` | `None` | OpenID logout URL. Required when using OpenID authentication. | +| `openid_provider_url` | `openid-provider-url` | `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` | `None` | OpenID provider URL. Required when using OpenID authentication. | +| `repository_path` | `repository-path` | `LANDSCAPE_APPSERVER__REPOSITORY_PATH` | `/tmp/landscape-repository` | Path to the package repository. | +| `reprepro_binary` | `reprepro-binary` | `LANDSCAPE_APPSERVER__REPREPRO_BINARY` | `None` | Path to the reprepro binary executable. | +| `sanitize_delay` | `sanitize-delay` | `LANDSCAPE_APPSERVER__SANITIZE_DELAY` | `3600` | Delay in seconds for data {spellexception}`sanitization` operations. | +| `secret_token` | `secret-token` | `LANDSCAPE_APPSERVER__SECRET_TOKEN` | `None` | Secret token for application security. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_APPSERVER__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | +| `threads` | | `LANDSCAPE_APPSERVER__THREADS` | `None` | Number of threads for the service. | +| `ubuntu_images_path` | `ubuntu-images-path` | `LANDSCAPE_APPSERVER__UBUNTU_IMAGES_PATH` | `/var/tmp/ubuntu-images` | Path to Ubuntu images directory. | +| `ubuntu_one_redirect_url` | `ubuntu-one-redirect-url` | `LANDSCAPE_APPSERVER__UBUNTU_ONE_REDIRECT_URL` | `None` | Ubuntu One redirect URL for authentication. | +| `workers` | | `LANDSCAPE_APPSERVER__WORKERS` | `None` | Number of worker processes for the service. | + +### Authentication providers + +OpenID: + +- Requires both `openid_provider_url` and `openid_logout_url` to be configured +- Defaults to using Ubuntu One + +OIDC: + +- Requires `oidc_issuer`, `oidc_client_id`, and `oidc_client_secret` to be configured + +### Moved Configuration Keys + +The following keys have moved from the `[appserver]` section to the `[system]` section in Landscape 25.10: + +- `enable-password-authentication` → `enable_password_authentication` in `[system]` +- `enable-subdomain-accounts` → `enable_subdomain_accounts` in `[system]` +- `enable-saas-metrics` → `enable_saas_metrics` in `[system]` + +These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape 26.04, when support will be removed and they must be configured in the `[system]` section. ## The `[async_frontend]` section @@ -179,3 +216,28 @@ The `[stores]` section contains configurations for database store connections an | `store_user` | - | `LANDSCAPE_STORES__STORE_USER` | `None` | Overrides the store username. | | `stores` | - | `LANDSCAPE_STORES__STORES` | `None` | The stores the service should use. | | `user` | - | `LANDSCAPE_STORES__USER` | `landscape` | The username for database connections. | + +## The `[system]` section + +```{note} +The `[global]` section name is deprecated. The `[system]` section replaces the `[global]` section. +``` + +The `[system]` section contains configurations that apply across many or all of Landscape's services. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `analytics_id` | - | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | +| `apt_port` | - | `LANDSCAPE_SYSTEM__APT_PORT` | 8085 | The port the `landscape_apt` service should use. | +| `audit_retention_period` | `audit-retention-period` | `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` | `-1` | The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. | +| `deployment_mode` | `deployment-mode` | `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` | `standalone` | Used only for development. The default value is appropriate for self-hosted Landscape. | +| `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | +| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | +| {spellexception}`pidfile_directory` | {spellexception}`pidfile-directory` | {spellexception}`LANDSCAPE_SYSTEM__PIDFILE_DIRECTORY` | `/tmp/landscape` | Unused | +| `max_service_memory` | `max-service-memory` | `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` | `0` | An upper limit (in {spellexception}`mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. | +| `middleware` | - | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | +| `offline` | - | `LANDSCAPE_SYSTEM__OFFLINE` | `None` | Set `True` if Landscape is deployed in an air-gapped environment. | +| `oops_path` | `oops-path` | `LANDSCAPE_SYSTEM__OOPS_PATH` | `/var/lib/landscape/landscape-oops` | The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. | +| `root_url` | `root-url` | `LANDSCAPE_SYSTEM__ROOT_URL` | `http://localhost:8080` | Landscape Server's root URL path. | +| `syslog_address` | `syslog-address` | `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` | `/dev/log` | Path to the system's syslog logger. | From 2ae90bba9bb65c96b0e232415827e3a19688ceb2 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Wed, 13 Aug 2025 17:27:14 -0700 Subject: [PATCH 057/187] add a few back to the maintenance section --- docs/reference/config/service-conf.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index e1f8f9ce..9ba70a22 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -83,6 +83,13 @@ The `[maintenance]` section contains configurations for running maintenance scri | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_MAINTENANCE__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_MAINTENANCE__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_MAINTENANCE__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | +| `mailer` | - | `LANDSCAPE_MAINTENANCE__MAILER` | `None` | Mailer service configuration. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_MAINTENANCE__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | +| `oops_key` | `oops-key` | `LANDSCAPE_MAINTENANCE__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_MAINTENANCE__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | | `sslcert` | - | `LANDSCAPE_MAINTENANCE__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | | `sslkey` | - | `LANDSCAPE_MAINTENANCE__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | | `sslmode` | - | `LANDSCAPE_MAINTENANCE__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | From eaaaf9421790d3853695c40e68f3458c9c95be9c Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Wed, 13 Aug 2025 17:34:14 -0700 Subject: [PATCH 058/187] schema settings --- docs/reference/config/service-conf.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 41d56f89..0d72cc16 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -136,6 +136,22 @@ It has the following settings beyond those shared by all services. | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | | `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | +## The `[schema]` section + +The `[schema]` section contains configurations for updating the database schema. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `sslcert` | - | `LANDSCAPE_SCHEMA__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_SCHEMA__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_SCHEMA__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_SCHEMA__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_SCHEMA__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_SCHEMA__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_SCHEMA__STORES` | `None` | The stores the service should use. | +| `threads` | - | `LANDSCAPE_SCHEMA__THREADS` | `None` | Number of threads for the service. | +| `workers` | - | `LANDSCAPE_SCHEMA__WORKERS` | `None` | Number of worker processes for the service. | + ## The `[scripts]` section The `[scripts]` section contains configurations for the scripts service, including service operation settings, database store configurations, and SSL options. From 05332fd66842e708f99583bc32680721c665bd82 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Wed, 13 Aug 2025 17:54:00 -0700 Subject: [PATCH 059/187] api settings --- docs/reference/config/service-conf.md | 29 +++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 09860f5c..cc3017d4 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -16,6 +16,35 @@ The usage of the `-` character in section names and key names is deprecated in L In addition, the names of some sections of the `service.conf` file are deprecated in Landscape Server 25.10. The new names are detailed below. Support for the deprecated names will be removed in Landscape Server 26.04. ``` +## The `[api]` section + +The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `allowed_interfaces` | - | `LANDSCAPE_API__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | +| `base_port` | `base-port` | `LANDSCAPE_API__BASE_PORT` | `8090` | Base port number for the service. | +| `cookie_encryption_key` | `cookie-encryption-key` | `LANDSCAPE_API__COOKIE_ENCRYPTION_KEY` | `None` | The key used to encrypt state and nonce cookies. | +| `cors_allow_all` | `cors-allow-all` | `LANDSCAPE_API__CORS_ALLOW_ALL` | `False` | Whether to allow CORS. | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_API__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_API__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_API__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | +| `mailer` | - | `LANDSCAPE_API__MAILER` | `None` | Mailer service configuration. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_API__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | +| `oops_key` | `oops-key` | `LANDSCAPE_API__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `root_url` | `root-url` | `LANDSCAPE_API__ROOT_URL` | `None` | The API URL to use. | +| `snap_store_api_url` | `snap-store-api-url` | `LANDSCAPE_API__SNAP_STORE_API_URL` | `https://api.snapcraft.io/v2` | The API for a Snap Store Proxy. By default, this is the Canonical Snap Store. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_API__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | +| `sslcert` | - | `LANDSCAPE_API__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_API__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_API__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_API__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_API__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_API__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_API__STORES` | `None` | The stores the service should use. | +| `threads` | - | `LANDSCAPE_API__THREADS` | `None` | Number of threads for the service. | +| `workers` | - | `LANDSCAPE_API__WORKERS` | `None` | Number of worker processes for the service. | + ## The `[appserver]` section ```{note} From f279b1957dd36d5cc5101e6300d1ba584ac6c880 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 14 Aug 2025 10:32:36 -0700 Subject: [PATCH 060/187] cors spellcheck --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index ee6d1b57..74cfb0c9 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -48,6 +48,7 @@ Cognito config configs conntrack +CORS createseries Cron cron From 43b4506c1b752ae86b2872524539b636c1866ffd Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Thu, 14 Aug 2025 11:35:29 -0600 Subject: [PATCH 061/187] fix: move `enable_query_debug` to `[system]`, correct env var name, add moved fields (#41) --- docs/reference/config/immutable-settings.md | 2 +- docs/reference/config/service-conf.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 137176bb..9db46258 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -17,7 +17,7 @@ The following immutable configurations can be set in `service.conf` or through e | `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use. | | `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `N/A` | `system` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | | `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | -| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_OOPS__QUERY_DEBUG` | `N/A` | `oops` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | +| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `N/A` | `system` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | | `LANDSCAPE_ROOT_URL` | `LANDSCAPE_SYSTEM__ROOT_URL` | `global` | `system` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | | `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | | `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 41d56f89..aa2ebd9f 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -231,6 +231,10 @@ The `[system]` section contains configurations that apply across many or all of | `apt_port` | - | `LANDSCAPE_SYSTEM__APT_PORT` | 8085 | The port the `landscape_apt` service should use. | | `audit_retention_period` | `audit-retention-period` | `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` | `-1` | The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. | | `deployment_mode` | `deployment-mode` | `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` | `standalone` | Used only for development. The default value is appropriate for self-hosted Landscape. | +| `enable_password_authentication` | - | `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` | `False` | Whether to enable password-based authentication or not. | +| `enable_query_debug` | - | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `False` | Whether to enable query introspection and debugging middleware or not. | +| `enable_saas_metrics` | - | `LANDSCAPE_SYSTEM__ENABLE_SAAS_METRICS` | `False` | Whether to enable metrics on SaaS or not. | +| `enable_subdomain_accounts` | - | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `False` | Whether to enable subdomain accounts or not. | | `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | | `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | | `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | From 09c9f2da51dda3d279203c64eed237dc8087adf1 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 14 Aug 2025 10:55:04 -0700 Subject: [PATCH 062/187] fix link --- docs/how-to-guides/security/harden-your-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/security/harden-your-deployment.md b/docs/how-to-guides/security/harden-your-deployment.md index 280a5d6d..2c5567ef 100644 --- a/docs/how-to-guides/security/harden-your-deployment.md +++ b/docs/how-to-guides/security/harden-your-deployment.md @@ -68,4 +68,4 @@ Ubuntu LTS releases with Ubuntu Pro can take advantage of the [Ubuntu Security G ## Harden Juju -If you used Juju to deploy Landscape, you can follow [Juju's hardening guide](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/#harden-your-deployment) to harden the Juju aspects of your deployment. +If you used Juju to deploy Landscape, you can follow [Juju's hardening guide](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-juju-deployment/harden-your-juju-deployment/#harden-your-deployment) to harden the Juju aspects of your deployment. From e804046b360245213b4fa099f546082e00336f8a Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Thu, 14 Aug 2025 18:04:35 -0600 Subject: [PATCH 063/187] fix: change `features` -> `system` in immutable conf settings table to reflect the real settings (#53) --- docs/reference/config/immutable-settings.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 9db46258..50c34460 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -8,15 +8,15 @@ The following immutable configurations can be set in `service.conf` or through e | :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | | `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `N/A` | `system` | `N/A` | `analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | | `LANDSCAPE_APT_PORT` | `LANDSCAPE_SYSTEM__APT_PORT` | `N/A` | `system` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | -| `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_FEATURES__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `features` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | -| `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_FEATURES__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `features` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | -| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_FEATURES__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `features` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | +| `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `system` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | +| `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `system` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | +| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `system` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | | `LANDSCAPE_FQDN` | `LANDSCAPE_SYSTEM__FQDN` | `N/A` | `system` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | | `LANDSCAPE_GPG_HOME` | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `N/A` | `system` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | | `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `N/A` | `system` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | | `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use. | | `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `N/A` | `system` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | -| `LANDSCAPE_OFFLINE` | `LANDSCAPE_FEATURES__ENABLE_OFFLINE` | `global` | `features` | `offline` | `enable_offline` | `False` | Whether offline mode is set or not (only relevant for standalone setups). | +| `LANDSCAPE_OFFLINE` | `LANDSCAPE_SYSTEM__OFFLINE` | `global` | `system` | `offline` | `offline` | `None` | Whether offline mode is set or not (only relevant for standalone setups). | | `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `N/A` | `system` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | | `LANDSCAPE_ROOT_URL` | `LANDSCAPE_SYSTEM__ROOT_URL` | `global` | `system` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | | `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | From 70cd7ef274a8c8ee58519510210c0bf1aefa070a Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Thu, 14 Aug 2025 18:24:13 -0600 Subject: [PATCH 064/187] feat: add missing `enable-tag-script-execution` to sys settings (#54) --- docs/reference/config/service-conf.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index b8ffde1d..bf5885de 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -104,6 +104,7 @@ The following keys have moved from the `[appserver]` section to the `[system]` s - `enable-password-authentication` → `enable_password_authentication` in `[system]` - `enable-subdomain-accounts` → `enable_subdomain_accounts` in `[system]` - `enable-saas-metrics` → `enable_saas_metrics` in `[system]` +- `enable-tag-script-execution` → `enable_tag_script_execution` in `[system]` These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape 26.04, when support will be removed and they must be configured in the `[system]` section. @@ -303,6 +304,7 @@ The `[system]` section contains configurations that apply across many or all of | `enable_query_debug` | - | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `False` | Whether to enable query introspection and debugging middleware or not. | | `enable_saas_metrics` | - | `LANDSCAPE_SYSTEM__ENABLE_SAAS_METRICS` | `False` | Whether to enable metrics on SaaS or not. | | `enable_subdomain_accounts` | - | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `False` | Whether to enable subdomain accounts or not. | +| `enable_tag_script_execution` | - | `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` | `False` | Whether to enable tag-based script execution or not. | | `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | | `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | | `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | From 008ef4c5599b06f1c1ad4561e2e07c8de1427941 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 22 May 2025 09:30:10 -0500 Subject: [PATCH 065/187] add oidc-provider to standalone OIDC setup --- .../openid-connect-oidc.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/external-authentication/openid-connect-oidc.md b/docs/how-to-guides/external-authentication/openid-connect-oidc.md index c07fcd57..89e96d29 100644 --- a/docs/how-to-guides/external-authentication/openid-connect-oidc.md +++ b/docs/how-to-guides/external-authentication/openid-connect-oidc.md @@ -25,6 +25,27 @@ The `oidc-issuer` is the URL of the issuer. That URL should also be a discovery The `oidc-client-id` and `oidc-client-secret` should be provided by your OIDC provider when you create the client credentials. The provider may require setting an authorization redirect URI. This should look like `https://your_landscape/login/handle-openid`. If your provider also requires a logout redirect URL, this should be the address of your Landscape server such as `https://your_landscape/`. +### (Optional) Specify your provider to enable additional features + +Certain features are available only for certain OIDC providers. +Landscape recognizes the following slugs for providers: + +- `google`: Google OAuth 2.0 +- `okta`: Okta + +```bash +[landscape] +[…] +oidc-issuer = +oidc-client-id = 000000000000-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.apps.googleusercontent.com +oidc-client-secret = a4sDFAsdfA4F52as-asDfAsd +oidc-provider = google +``` + +You will still be able to authenticate as usual without specifying an `oidc-provider`. +It is not required for basic OIDC authentication. +If you change the value of your `oidc-provider`, it will be updated on your next authentication. + ## Restart all Landscape services To restart all Landscape services, run: @@ -46,4 +67,3 @@ oidc-logout-url = ```{note} There is no provision yet to upgrade current users to OIDC authentication. Most providers return pairwise subject identifiers (sub) which are not easily available. For this reason, we do not provide a user migration method and recommend recreating users. ``` - From b7fd2895dcab8ebe83b468cc4f0d62bdd29482ac Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 22 May 2025 14:20:58 -0500 Subject: [PATCH 066/187] add wip docs for provisioning and setup --- .../ubuntu-installer-provisioning/index.md | 10 ++++++ .../provision-a-workstation.md | 13 ++++++++ ...-landscape-for-workstation-provisioning.md | 32 +++++++++++++++++++ 3 files changed, 55 insertions(+) create mode 100644 docs/how-to-guides/ubuntu-installer-provisioning/index.md create mode 100644 docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md create mode 100644 docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/index.md b/docs/how-to-guides/ubuntu-installer-provisioning/index.md new file mode 100644 index 00000000..427798df --- /dev/null +++ b/docs/how-to-guides/ubuntu-installer-provisioning/index.md @@ -0,0 +1,10 @@ +(how-to-guides-ubuntu-installer-provisioning-index)= +# Provisioning devices with the Ubuntu Installer + +```{toctree} +:titlesonly: +:maxdepth: 2 +:glob: + +Setup Landscape for Workstation Provisioning +Provision a Workstation diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md new file mode 100644 index 00000000..395a1502 --- /dev/null +++ b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md @@ -0,0 +1,13 @@ +(how-to-provision-a-workstation)= +# How to provision a workstation using Landscape and the Ubuntu installer + +Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +This is available on self-hosted and SaaS Landscape. +On SaaS Landscape, your account must be hosted on a subdomain. +Your Landscape account must use OIDC authentication. Currently, only Google OAuth 2.0 is supported. + +WIP: + +- Choose Landscape provisioning in the installer +- Use your attach code to authenticate against Landscape +- Log in against your identity provider diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md new file mode 100644 index 00000000..4507dc14 --- /dev/null +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -0,0 +1,32 @@ +(how-to-ubuntu-installer-provisioning-setup-landscape)= +# How to set up Landscape for workstation provisioning + +Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +This is available on self-hosted and SaaS Landscape. +On SaaS Landscape, your account must be hosted on a subdomain. +Your Landscape account must use OIDC authentication. Currently, only Google OAuth 2.0 is supported. + +## Configure OIDC + +Landscape uses OIDC authentication for the workstation provisioning experience. +Configure Google OAuth 2.0 OIDC (link). + +Only users that are known to the OIDC provider will be able to use the provisioning experience. +A local Landscape user that logs in with username/password will not. + +## Upload autoinstall files + +Add your autoinstall files to Landscape. + +## (Optional) Set default autoinstall file + +If a user hasn't been assigned an autoinstall file, they can still provision a device with a specified default autoinstall file. +Only one file may be the default file at a time. +You may change the default file at any time. + +## Associate your autoinstall files with users + +TBD: + +- Option 1: explain the group import and association process +- Option 2: custom claims From 720e3f056fbb00bad4c63d418b293670c3f664cb Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Mon, 2 Jun 2025 17:20:50 -0500 Subject: [PATCH 067/187] fill out ubuntu installer doc --- .../provision-a-workstation.md | 27 +++++++++++++++---- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md index 395a1502..dcb751a7 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md @@ -4,10 +4,27 @@ Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. -Your Landscape account must use OIDC authentication. Currently, only Google OAuth 2.0 is supported. +Your Landscape administrator must have configured an OIDC login method. +Currently, Google OAuth 2.0 is the only OIDC provider that this feature supports. -WIP: +## In the Ubuntu installer -- Choose Landscape provisioning in the installer -- Use your attach code to authenticate against Landscape -- Log in against your identity provider +1. In the Ubuntu installer menu, select **install with Landscape**. +1. Enter the URL of your Landscape deployment. + +The installer will generate a 6 digit attach code for you. +Save this for the next step. + +## In Landscape + +1. Navigate to the **/attach** page in Landscape. +1. Enter your 6 digit attach code. +1. Landscape will confirm that the attach code is valid and prompt you to log in. +1. Authenticate against your OIDC provider. + +## Back in the Ubuntu installer + +1. After successful authentication, Landscape will serve an autoinstall file to the Ubuntu installer. +1. Confirm the autoinstall file. + +The Ubuntu installer will use the autoinstall file to provision your device. From 59c6da8d6c160f1a9a248b0b5f29d2ee05b4adfc Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Mon, 2 Jun 2025 17:35:43 -0500 Subject: [PATCH 068/187] add administrator doc --- ...-landscape-for-workstation-provisioning.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 4507dc14..804223a1 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -14,9 +14,24 @@ Configure Google OAuth 2.0 OIDC (link). Only users that are known to the OIDC provider will be able to use the provisioning experience. A local Landscape user that logs in with username/password will not. +1. Navigate to **Org settings > Identity providers**. +2. Configure a Google OAuth 2.0 client. +3. Request the **groups** claim when configuring the client. +4. Assign the **groups** claim to the **Autoinstall file** resource. + +The **groups** claim will be used to identify an autoinstall file for a user when they authenticate. + +## (Optional) Configure Hashicorp Vault for secure, versioned autoinstall storage + +(Not delivered in 25.10) + +Landscape supports integration with Hashicorp Vault for secure, versioned storage. +When configured as a storage backend, Landscape will store autoinstall files in the Vault. + ## Upload autoinstall files -Add your autoinstall files to Landscape. +1. Navigate to the **Employees > Autoinstall** tab. +2. Upload your autoinstall files to Landscape. ## (Optional) Set default autoinstall file @@ -26,7 +41,12 @@ You may change the default file at any time. ## Associate your autoinstall files with users -TBD: +Associate each autoinstall file with a particular value of the **groups** claim. +When a user reports a **groups** claim with this value, they will be assigned the corresponding autoinstall file. + +### (Optional) Assign priorities -- Option 1: explain the group import and association process -- Option 2: custom claims +If a user reports multiple **groups** claim values, they may be associated with multiple autoinstall files. +However, Landscape will only serve users a single file. +You may assign each file a priority to break ties if this situation arises. +If two files have the same priority or no priority assigned, Landscape will internally resolve the tie and deterministically serve a single file. From e1c972c0ca79aeb2153234c3c1199d26157a5170 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 5 Jun 2025 11:31:43 -0500 Subject: [PATCH 069/187] add index to top-level how-to index --- docs/how-to-guides/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 3a757d91..ce1944a3 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -118,4 +118,5 @@ iot-for-devices/index wsl-integration/index security/index api/index +ubuntu-installer-provisioning/index ``` From a635995defadbee3a3275ea719b7c6c5f829026f Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 5 Jun 2025 11:44:19 -0500 Subject: [PATCH 070/187] enforce my opinions on the custom wordlist --- docs/.custom_wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 8ce69c5f..3baadd1f 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -20,6 +20,7 @@ autoinstall AutoPilot autoremove amd +backend backport Backport backtrace @@ -65,6 +66,7 @@ CVEs datetime debian decrypt +deterministically DirectoryAPI DISA distros @@ -94,6 +96,7 @@ filesystem frontend HAProxy hardcoded +Hashicorp hashid Hashids heredoc From 4d4b45176ba2546c7f1c7dc33cf9f9d6b1272d8f Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Wed, 6 Aug 2025 17:21:44 -0500 Subject: [PATCH 071/187] remove references to Google OAuth 2.0 and non-delivered functionality for 25.08 --- .../provision-a-workstation.md | 1 - ...-landscape-for-workstation-provisioning.md | 39 +++---------------- 2 files changed, 6 insertions(+), 34 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md index dcb751a7..0f8f0435 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md @@ -5,7 +5,6 @@ Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an a This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. -Currently, Google OAuth 2.0 is the only OIDC provider that this feature supports. ## In the Ubuntu installer diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 804223a1..8be7b384 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -4,49 +4,22 @@ Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. -Your Landscape account must use OIDC authentication. Currently, only Google OAuth 2.0 is supported. +Your Landscape account must use OIDC authentication. ## Configure OIDC Landscape uses OIDC authentication for the workstation provisioning experience. -Configure Google OAuth 2.0 OIDC (link). Only users that are known to the OIDC provider will be able to use the provisioning experience. A local Landscape user that logs in with username/password will not. 1. Navigate to **Org settings > Identity providers**. -2. Configure a Google OAuth 2.0 client. -3. Request the **groups** claim when configuring the client. -4. Assign the **groups** claim to the **Autoinstall file** resource. +2. Configure an OIDC client. -The **groups** claim will be used to identify an autoinstall file for a user when they authenticate. - -## (Optional) Configure Hashicorp Vault for secure, versioned autoinstall storage - -(Not delivered in 25.10) - -Landscape supports integration with Hashicorp Vault for secure, versioned storage. -When configured as a storage backend, Landscape will store autoinstall files in the Vault. - -## Upload autoinstall files +## Upload autoinstall file 1. Navigate to the **Employees > Autoinstall** tab. -2. Upload your autoinstall files to Landscape. - -## (Optional) Set default autoinstall file - -If a user hasn't been assigned an autoinstall file, they can still provision a device with a specified default autoinstall file. -Only one file may be the default file at a time. -You may change the default file at any time. - -## Associate your autoinstall files with users - -Associate each autoinstall file with a particular value of the **groups** claim. -When a user reports a **groups** claim with this value, they will be assigned the corresponding autoinstall file. - -### (Optional) Assign priorities +2. Upload your autoinstall file(s) to Landscape. +3. Set the autoinstall file to be your default autoinstall file. This ensures it is served to all users that successfully authenticate. -If a user reports multiple **groups** claim values, they may be associated with multiple autoinstall files. -However, Landscape will only serve users a single file. -You may assign each file a priority to break ties if this situation arises. -If two files have the same priority or no priority assigned, Landscape will internally resolve the tie and deterministically serve a single file. +Only one file may be the default. From 2cc041233845606399e0f383334aa0fb4986bba3 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 14 Aug 2025 17:43:38 -0500 Subject: [PATCH 072/187] add service install instructions --- .../provision-a-workstation.md | 2 +- ...-landscape-for-workstation-provisioning.md | 32 +++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md index 0f8f0435..63d4a131 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md @@ -18,7 +18,7 @@ Save this for the next step. 1. Navigate to the **/attach** page in Landscape. 1. Enter your 6 digit attach code. -1. Landscape will confirm that the attach code is valid and prompt you to log in. +1. Landscape will confirm that the attach code is valid and will prompt you to log in. 1. Authenticate against your OIDC provider. ## Back in the Ubuntu installer diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 8be7b384..5cab5eca 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -6,6 +6,32 @@ This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. +```{note} +This feature is available from Landscape server `25.08` onwards. +``` + +## Install the `landscape-ubuntu-installer-attach` package + +Landscape requires an additional service for the Ubuntu installer attach experience. + +```sh +sudo add-apt-repository ppa:landscape/latest-stable +sudo apt update +sudo apt install landscape-ubuntu-installer-attach +``` + +## Enable the feature + +On self-hosted, you'll need to set the feature flag in your `service.conf`: + +```ini +[features] +[...] +enable-employee-management = true +``` + +On SaaS, you'll need to make a request to support. + ## Configure OIDC Landscape uses OIDC authentication for the workstation provisioning experience. @@ -13,6 +39,12 @@ Landscape uses OIDC authentication for the workstation provisioning experience. Only users that are known to the OIDC provider will be able to use the provisioning experience. A local Landscape user that logs in with username/password will not. +### Self-hosted + +See {ref}`how-to-external-auth-oidc`. + +### SaaS + 1. Navigate to **Org settings > Identity providers**. 2. Configure an OIDC client. From deabe3addfd8b2da7c936e6fdcf684cb443b045a Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Mon, 18 Aug 2025 09:18:55 -0500 Subject: [PATCH 073/187] add note about default file --- .../setup-landscape-for-workstation-provisioning.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 5cab5eca..0c7a5e74 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -50,8 +50,13 @@ See {ref}`how-to-external-auth-oidc`. ## Upload autoinstall file +```note +Currently, only the default file can be served to users. +Ensure that you set a default file. +``` + 1. Navigate to the **Employees > Autoinstall** tab. 2. Upload your autoinstall file(s) to Landscape. -3. Set the autoinstall file to be your default autoinstall file. This ensures it is served to all users that successfully authenticate. +3. Set the autoinstall file to be your default autoinstall file. Only one file may be the default. From 617fd631c60642fd24f6c632c2ec70bd1239dbbd Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Mon, 18 Aug 2025 09:36:11 -0500 Subject: [PATCH 074/187] fix note --- .../setup-landscape-for-workstation-provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 0c7a5e74..11a9c2a5 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -50,7 +50,7 @@ See {ref}`how-to-external-auth-oidc`. ## Upload autoinstall file -```note +```{note} Currently, only the default file can be served to users. Ensure that you set a default file. ``` From 729d9abc4aa9351bd0234b97001eaf3d0be03f40 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Mon, 18 Aug 2025 09:51:22 -0600 Subject: [PATCH 075/187] feat: `[oops]` section docs (#47) --- docs/.custom_wordlist.txt | 6 ++++++ docs/reference/config/service-conf.md | 20 ++++++++++++++++---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 8ce69c5f..d4d15ae1 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -7,6 +7,7 @@ ajax allowlist allowlists amongst +AMQP Ansible Apache apache @@ -16,6 +17,7 @@ appserver ascii async auth +autocommit autoinstall AutoPilot autoremove @@ -102,6 +104,7 @@ HMAC HmacSHA hostagent hostname +hostnames html http HTTPS @@ -122,6 +125,7 @@ Keycloak KeyError Kudu KVM +keyrings kvm kwarg labelled @@ -230,6 +234,7 @@ rsyslog rsyslogd SaaS Sanitization +sanitization scalable scalability SDK @@ -267,6 +272,7 @@ timeframe TLD TLS TLSv +traceback transactional UA ubuntu diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index bf5885de..2b0b820f 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -78,7 +78,7 @@ The `[appserver]` section contains configurations for the Landscape application | `openid_provider_url` | `openid-provider-url` | `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` | `None` | OpenID provider URL. Required when using OpenID authentication. | | `repository_path` | `repository-path` | `LANDSCAPE_APPSERVER__REPOSITORY_PATH` | `/tmp/landscape-repository` | Path to the package repository. | | `reprepro_binary` | `reprepro-binary` | `LANDSCAPE_APPSERVER__REPREPRO_BINARY` | `None` | Path to the reprepro binary executable. | -| `sanitize_delay` | `sanitize-delay` | `LANDSCAPE_APPSERVER__SANITIZE_DELAY` | `3600` | Delay in seconds for data {spellexception}`sanitization` operations. | +| `sanitize_delay` | `sanitize-delay` | `LANDSCAPE_APPSERVER__SANITIZE_DELAY` | `3600` | Delay in seconds for data sanitization operations. | | `secret_token` | `secret-token` | `LANDSCAPE_APPSERVER__SECRET_TOKEN` | `None` | Secret token for application security. | | `soft_timeout` | `soft-timeout` | `LANDSCAPE_APPSERVER__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | | `threads` | | `LANDSCAPE_APPSERVER__THREADS` | `None` | Number of threads for the service. | @@ -189,6 +189,18 @@ It has the following settings beyond those shared by all services. | `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | | `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | +## The `[oops]` section + +The `[oops]` section contains configurations for the OOPS error reporting and debugging system used for logging and traceback collection. + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `amqp_exchange` | `amqp-exchange` | `LANDSCAPE_OOPS__AMQP_EXCHANGE` | `None` | AMQP exchange name for error reporting. | +| `amqp_key` | `amqp-key` | `LANDSCAPE_OOPS__AMQP_KEY` | `None` | AMQP routing key for error messages. Requires `amqp_exchange` to be set. | +| `directory` | - | `LANDSCAPE_OOPS__DIRECTORY` | `None` | Directory path for OOPS error report storage. | +| `path` | - | `LANDSCAPE_OOPS__PATH` | `None` | File path for OOPS configuration. | +| `reporter` | - | `LANDSCAPE_OOPS__REPORTER` | `None` | Error reporter configuration. | + ## The `[schema]` section The `[schema]` section contains configurations for updating the database schema. @@ -237,7 +249,7 @@ The `[secrets]` section contains configurations for the secrets service, includi | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | +| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or hostnames for the service. | | `base_port` | `base-port` | `LANDSCAPE_SECRETS__BASE_PORT` | `8090` | Base port number for the service. | | `devmode` | - | `LANDSCAPE_SECRETS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | | `enable_metrics` | `enable-metrics` | `LANDSCAPE_SECRETS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | @@ -276,7 +288,7 @@ The `[stores]` section contains configurations for database store connections an | `resource_1` | `resource-1` | `LANDSCAPE_STORES__RESOURCE_1` | `landscape-standalone-resource-1` | The first resource database name. | | `resource_2` | `resource-2` | `LANDSCAPE_STORES__RESOURCE_2` | `None` | The second resource database name. Optional and used for testing only. | | `session` | - | `LANDSCAPE_STORES__SESSION` | `landscape-standalone-session` | The session database name. | -| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with {spellexception}`autocommit` isolation. | +| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with autocommit isolation. | | `sslcert` | - | `LANDSCAPE_STORES__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | | `sslkey` | - | `LANDSCAPE_STORES__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | | `sslmode` | - | `LANDSCAPE_STORES__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | @@ -306,7 +318,7 @@ The `[system]` section contains configurations that apply across many or all of | `enable_subdomain_accounts` | - | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `False` | Whether to enable subdomain accounts or not. | | `enable_tag_script_execution` | - | `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` | `False` | Whether to enable tag-based script execution or not. | | `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | -| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | +| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the keyrings. | | `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | | {spellexception}`pidfile_directory` | {spellexception}`pidfile-directory` | {spellexception}`LANDSCAPE_SYSTEM__PIDFILE_DIRECTORY` | `/tmp/landscape` | Unused | | `max_service_memory` | `max-service-memory` | `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` | `0` | An upper limit (in {spellexception}`mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. | From 7c69a2dc0a26523b144d3cc1e5ff3b29579fc15d Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Mon, 18 Aug 2025 09:52:11 -0600 Subject: [PATCH 076/187] feat: add `[load_shaper]` section docs (#46) --- docs/reference/config/service-conf.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 2b0b820f..a37e413b 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -167,6 +167,24 @@ The `[maintenance]` section contains configurations for running maintenance scri | `threads` | - | `LANDSCAPE_MAINTENANCE__THREADS` | `None` | Number of threads for the service. | | `workers` | - | `LANDSCAPE_MAINTENANCE__WORKERS` | `None` | Number of worker processes for the service. | +## The `[load_shaper]` section + +```{note} +The `[load-shaper]` section name is deprecated. The `[load_shaper]` section replaces the `[load-shaper]` section. +``` + +The `[load_shaper]` section contains configurations for controlling how many messages are processed in each message exchange. It allots a time window for message processing based on the current database load. + +```{caution} +The default values have been chosen based on the underlying algorithm and typical workloads. Modifying these values is not advisable unless you have thoroughly tested the impact on your specific system, as changes can significantly affect performance and system stability. +``` + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `critical_load` | `critical-load` | `LANDSCAPE_LOAD_SHAPER__CRITICAL_LOAD` | `10.0` | A float representing the database load threshold at which message processing time is reduced to zero. When load reaches this value, no time slice is allocated for processing. | +| `good_duration` | `good-duration` | `LANDSCAPE_LOAD_SHAPER__GOOD_DURATION` | `60.0` | A float representing the baseline time slice (in seconds) allocated for message processing when the database load is at the good load threshold. This duration is scaled up or down based on current load. | +| `good_load` | `good-load` | `LANDSCAPE_LOAD_SHAPER__GOOD_LOAD` | `3.0` | A float representing the optimal database load threshold. When load is at this value, the full good duration time slice is allocated. Load below this increases the time slice, load above this decreases it. | + ## The `[message_server]` section ```{note} From 898a7015ec7825e5c95adce132abe508e3182ed3 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Mon, 18 Aug 2025 10:34:20 -0600 Subject: [PATCH 077/187] feat: `[package_upload]` section docs, add sections for generic store/services settings (#44) --- docs/reference/config/service-conf.md | 191 +++++++++----------------- 1 file changed, 67 insertions(+), 124 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index a37e413b..2fa60d49 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -16,34 +16,59 @@ The usage of the `-` character in section names and key names is deprecated in L In addition, the names of some sections of the `service.conf` file are deprecated in Landscape Server 25.10. The new names are detailed below. Support for the deprecated names will be removed in Landscape Server 26.04. ``` +(shared-service-settings)= +## Shared service settings + +There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service: + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `allowed_interfaces` | - | `LANDSCAPE_SERVICE__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or hostnames for the service. | +| `base_port` | `base-port` | `LANDSCAPE_SERVICE__BASE_PORT` | `8090` | Base port number for the service. | +| `devmode` | - | `LANDSCAPE_SERVICE__DEVMODE` | `None` | Development mode configuration (ex. `on`). | +| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SERVICE__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | +| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SERVICE__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | +| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SERVICE__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | +| `mailer` | - | `LANDSCAPE_SERVICE__MAILER` | `None` | Mailer service configuration. | +| `mailer_path` | `mailer-path` | `LANDSCAPE_SERVICE__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | +| `oops_key` | `oops-key` | `LANDSCAPE_SERVICE__OOPS_KEY` | `None` | Key for OOPS error reporting system. | +| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SERVICE__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | +| `threads` | - | `LANDSCAPE_SERVICE__THREADS` | `None` | Number of threads for the service. | +| `workers` | - | `LANDSCAPE_SERVICE__WORKERS` | `None` | Number of worker processes for the service. | + +```{important} +The shared service settings are not mutually exclusive with the shared store settings; services can use both, if specified. +``` + +(shared-store-settings)= +## Shared store settings + +There are a set of generic settings related to databases and SSL connections to Postgres that several sections can set, where `SECTION` in the ENV name matches the (uppercase) name of the section: + +| Key name | Deprecated key name | ENV name | Default | Purpose | +| :------- | :------------------ | :------- | :------ | :------ | +| `sslcert` | - | `LANDSCAPE_SECTION__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | +| `sslkey` | - | `LANDSCAPE_SECTION__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | +| `sslmode` | - | `LANDSCAPE_SECTION__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | +| `sslrootcert` | - | `LANDSCAPE_SECTION__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | +| `store_password` | - | `LANDSCAPE_SECTION__STORE_PASSWORD` | `None` | Overrides the store password. | +| `store_user` | - | `LANDSCAPE_SECTION__STORE_USER` | `None` | Overrides the store username. | +| `stores` | - | `LANDSCAPE_SECTION__STORES` | `None` | The stores the service should use. | + +```{important} +The shared store settings are not mutually exclusive with the shared service settings; services can use both, if specified. +``` + ## The `[api]` section -The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. +The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_API__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | -| `base_port` | `base-port` | `LANDSCAPE_API__BASE_PORT` | `8090` | Base port number for the service. | | `cookie_encryption_key` | `cookie-encryption-key` | `LANDSCAPE_API__COOKIE_ENCRYPTION_KEY` | `None` | The key used to encrypt state and nonce cookies. | | `cors_allow_all` | `cors-allow-all` | `LANDSCAPE_API__CORS_ALLOW_ALL` | `False` | Whether to allow CORS. | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_API__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_API__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_API__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | -| `mailer` | - | `LANDSCAPE_API__MAILER` | `None` | Mailer service configuration. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_API__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | -| `oops_key` | `oops-key` | `LANDSCAPE_API__OOPS_KEY` | `None` | Key for OOPS error reporting system. | | `root_url` | `root-url` | `LANDSCAPE_API__ROOT_URL` | `None` | The API URL to use. | | `snap_store_api_url` | `snap-store-api-url` | `LANDSCAPE_API__SNAP_STORE_API_URL` | `https://api.snapcraft.io/v2` | The API for a Snap Store Proxy. By default, this is the Canonical Snap Store. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_API__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `sslcert` | - | `LANDSCAPE_API__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_API__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_API__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_API__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_API__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_API__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_API__STORES` | `None` | The stores the service should use. | -| `threads` | - | `LANDSCAPE_API__THREADS` | `None` | Number of threads for the service. | -| `workers` | - | `LANDSCAPE_API__WORKERS` | `None` | Number of worker processes for the service. | ## The `[appserver]` section @@ -51,40 +76,27 @@ The `[api]` section contains configurations for the Landscape API service, inclu The `[landscape]` section name is deprecated. The `[appserver]` section replaces the `[landscape]` section. ``` -The `[appserver]` section contains configurations for the Landscape application server, including storage paths, authentication providers, and security settings. +The `[appserver]` section contains configurations for the Landscape application server, including storage paths and authentication providers. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `access_log` | `access-log` | `LANDSCAPE_APPSERVER__ACCESS_LOG` | `None` | Path to access log file for this service. | -| `allowed_interfaces` | | `LANDSCAPE_APPSERVER__ALLOWED_INTERFACES` | `None` | Network interfaces allowed for connections. | -| `base_port` | `base-port` | `LANDSCAPE_APPSERVER__BASE_PORT` | `8090` | Base port number for the service. | | `blob_storage_root` | `blob-storage-root` | `LANDSCAPE_APPSERVER__BLOB_STORAGE_ROOT` | `/var/lib/landscape/blobs` | Root directory for blob storage. | -| `devmode` | | `LANDSCAPE_APPSERVER__DEVMODE` | `None` | Development mode settings. | | `display_consent_banner_at_each_login` | `display-consent-banner-at-each-login` | `LANDSCAPE_APPSERVER__DISPLAY_CONSENT_BANNER_AT_EACH_LOGIN` | `False` | Whether to display consent banner at each login. | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_APPSERVER__ENABLE_METRICS` | `False` | Whether to enable metrics collection. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_APPSERVER__GPG_HOME_PATH` | `None` | Path to GPG home directory. Must be used with `gpg_passphrase_path`. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_APPSERVER__GPG_PASSPHRASE_PATH` | `None` | Path to GPG passphrase file. Required when `gpg_home_path` is set. | | `juju_homes_path` | `juju-homes-path` | `LANDSCAPE_APPSERVER__JUJU_HOMES_PATH` | `/var/tmp/juju-homes` | Path to Juju home directories. | | `known_proxies` | `known-proxies` | `LANDSCAPE_APPSERVER__KNOWN_PROXIES` | `None` | Comma-separated names of known proxies. | -| `mailer` | | `LANDSCAPE_APPSERVER__MAILER` | `None` | Mailer type specification. Must be used with `mailer_path`. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_APPSERVER__MAILER_PATH` | `None` | Path to mailer executable. Required when `mailer` is set. | | `oidc_client_id` | `oidc-client-id` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_ID` | `None` | OIDC client identifier. Required when using OIDC authentication. | | `oidc_client_secret` | `oidc-client-secret` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_SECRET` | `None` | OIDC client secret. Required when using OIDC authentication. | | `oidc_issuer` | `oidc-issuer` | `LANDSCAPE_APPSERVER__OIDC_ISSUER` | `None` | OIDC issuer URL. Required when using OIDC authentication. | | `oidc_provider` | `oidc-provider` | `LANDSCAPE_APPSERVER__OIDC_PROVIDER` | `unspecified` | The name of OIDC provider to use. Must be either `google`, `okta`, or `unspecified`. | | `oidc_redirect_uri` | `oidc-redirect-uri` | `LANDSCAPE_APPSERVER__OIDC_REDIRECT_URI` | `None` | OIDC redirect URI for authentication callbacks. | -| `oops_key` | `oops-key` | `LANDSCAPE_APPSERVER__OOPS_KEY` | `None` | Key for OOPS error reporting system. | | `openid_logout_url` | `openid-logout-url` | `LANDSCAPE_APPSERVER__OPENID_LOGOUT_URL` | `None` | OpenID logout URL. Required when using OpenID authentication. | | `openid_provider_url` | `openid-provider-url` | `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` | `None` | OpenID provider URL. Required when using OpenID authentication. | | `repository_path` | `repository-path` | `LANDSCAPE_APPSERVER__REPOSITORY_PATH` | `/tmp/landscape-repository` | Path to the package repository. | | `reprepro_binary` | `reprepro-binary` | `LANDSCAPE_APPSERVER__REPREPRO_BINARY` | `None` | Path to the reprepro binary executable. | | `sanitize_delay` | `sanitize-delay` | `LANDSCAPE_APPSERVER__SANITIZE_DELAY` | `3600` | Delay in seconds for data sanitization operations. | | `secret_token` | `secret-token` | `LANDSCAPE_APPSERVER__SECRET_TOKEN` | `None` | Secret token for application security. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_APPSERVER__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `threads` | | `LANDSCAPE_APPSERVER__THREADS` | `None` | Number of threads for the service. | | `ubuntu_images_path` | `ubuntu-images-path` | `LANDSCAPE_APPSERVER__UBUNTU_IMAGES_PATH` | `/var/tmp/ubuntu-images` | Path to Ubuntu images directory. | | `ubuntu_one_redirect_url` | `ubuntu-one-redirect-url` | `LANDSCAPE_APPSERVER__UBUNTU_ONE_REDIRECT_URL` | `None` | Ubuntu One redirect URL for authentication. | -| `workers` | | `LANDSCAPE_APPSERVER__WORKERS` | `None` | Number of worker processes for the service. | ### Authentication providers @@ -114,7 +126,7 @@ These keys can still be used in their deprecated forms in `[appserver]`/`[landsc The `[async-frontend]` section name is deprecated. The `[async_frontend]` section replaces the `[async-frontend]` section. ``` -The `[async_frontend]` section contains configurations that apply to the `landscape-async-frontend` service which handles AJAX requests from the Legacy UI. It has no settings beyond those shared by all services. +The `[async_frontend]` section contains configurations that apply to the `landscape-async-frontend` service which handles AJAX requests from the Legacy UI. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. In practice, only the `base_port` setting needs to be configured for the service to operate correctly. @@ -140,33 +152,10 @@ The `[broker]` section contains configurations that describe how services connec The `[job-handler]` section name is deprecated. The `[job_handler]` section replaces the `[job-handler]` section. ``` -The `[job_handler]` section contains configurations for the `landscape-job-handler` service which runs background jobs. It has no settings beyond those shared by all services. +The `[job_handler]` section contains configurations for the `landscape-job-handler` service which runs background jobs. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. In practice, only the `base_port` setting needs to be configured for the service to operate correctly. -## The `[maintenance]` section - -The `[maintenance]` section contains configurations for running maintenance scripts. - -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_MAINTENANCE__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_MAINTENANCE__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_MAINTENANCE__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | -| `mailer` | - | `LANDSCAPE_MAINTENANCE__MAILER` | `None` | Mailer service configuration. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_MAINTENANCE__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | -| `oops_key` | `oops-key` | `LANDSCAPE_MAINTENANCE__OOPS_KEY` | `None` | Key for OOPS error reporting system. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_MAINTENANCE__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `sslcert` | - | `LANDSCAPE_MAINTENANCE__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_MAINTENANCE__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_MAINTENANCE__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_MAINTENANCE__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_MAINTENANCE__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_MAINTENANCE__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_MAINTENANCE__STORES` | `None` | The stores the service should use. | -| `threads` | - | `LANDSCAPE_MAINTENANCE__THREADS` | `None` | Number of threads for the service. | -| `workers` | - | `LANDSCAPE_MAINTENANCE__WORKERS` | `None` | Number of worker processes for the service. | - ## The `[load_shaper]` section ```{note} @@ -185,6 +174,10 @@ The default values have been chosen based on the underlying algorithm and typica | `good_duration` | `good-duration` | `LANDSCAPE_LOAD_SHAPER__GOOD_DURATION` | `60.0` | A float representing the baseline time slice (in seconds) allocated for message processing when the database load is at the good load threshold. This duration is scaled up or down based on current load. | | `good_load` | `good-load` | `LANDSCAPE_LOAD_SHAPER__GOOD_LOAD` | `3.0` | A float representing the optimal database load threshold. When load is at this value, the full good duration time slice is allocated. Load below this increases the time slice, load above this decreases it. | +## The `[maintenance]` section + +The `[maintenance]` section contains configurations for running maintenance scripts. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. + ## The `[message_server]` section ```{note} @@ -195,9 +188,7 @@ The `[message-server]` section name is deprecated. The `[message_server]` sectio The `[backoff]` section is deprecated. The settings have been moved to the `[message_server]` section. ``` -The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. - -It has the following settings beyond those shared by all services. +The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | @@ -219,80 +210,39 @@ The `[oops]` section contains configurations for the OOPS error reporting and de | `path` | - | `LANDSCAPE_OOPS__PATH` | `None` | File path for OOPS configuration. | | `reporter` | - | `LANDSCAPE_OOPS__REPORTER` | `None` | Error reporter configuration. | -## The `[schema]` section -The `[schema]` section contains configurations for updating the database schema. +The `[schema]` section contains configurations for updating the database schema. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `sslcert` | - | `LANDSCAPE_SCHEMA__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_SCHEMA__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_SCHEMA__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_SCHEMA__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_SCHEMA__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_SCHEMA__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_SCHEMA__STORES` | `None` | The stores the service should use. | -| `threads` | - | `LANDSCAPE_SCHEMA__THREADS` | `None` | Number of threads for the service. | -| `workers` | - | `LANDSCAPE_SCHEMA__WORKERS` | `None` | Number of worker processes for the service. | +## The `[package_upload]` section -## The `[scripts]` section +```{note} +The `[package-upload]` section name is deprecated. The `[package_upload]` section replaces the `[package-upload]` section. +``` -The `[scripts]` section contains configurations for the scripts service, including service operation settings, database store configurations, and SSL options. +The `[package_upload]` section contains configurations for the package upload service, including service connection settings, database store configurations, and SSL options. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_SCRIPTS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or {spellexception}`hostnames` for the service. | -| `base_port` | `base-port` | `LANDSCAPE_SCRIPTS__BASE_PORT` | `8090` | Base port number for the service. | -| `devmode` | - | `LANDSCAPE_SCRIPTS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SCRIPTS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SCRIPTS__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SCRIPTS__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | -| `mailer` | - | `LANDSCAPE_SCRIPTS__MAILER` | `None` | Mailer service configuration. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_SCRIPTS__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | -| `oops_key` | `oops-key` | `LANDSCAPE_SCRIPTS__OOPS_KEY` | `None` | Key for OOPS error reporting system. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SCRIPTS__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `sslcert` | - | `LANDSCAPE_SCRIPTS__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_SCRIPTS__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_SCRIPTS__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_SCRIPTS__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_SCRIPTS__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_SCRIPTS__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_SCRIPTS__STORES` | `None` | The stores the service should use. | -| `threads` | - | `LANDSCAPE_SCRIPTS__THREADS` | `None` | Number of threads for the service. | -| `workers` | - | `LANDSCAPE_SCRIPTS__WORKERS` | `None` | Number of worker processes for the service. | +| `port` | - | `LANDSCAPE_PACKAGE_UPLOAD__PORT` | `None` | The port the service will use. This field is required. | +| `service_path` | `root-url` | `LANDSCAPE_PACKAGE_UPLOAD__SERVICE_PATH` | `/upload/` | The relative path portion to use for the service URL. | + +## The `[scripts]` section + +The `[scripts]` section contains configurations for scripts. The section contains only the {ref}`shared service settings ` and the {ref}`shared store settings `. ## The `[secrets]` section -The `[secrets]` section contains configurations for the secrets service, including vault connection settings, service URLs, database store configurations, and SSL options. +The `[secrets]` section contains configurations for the secrets service, such as vault connection settings. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_SECRETS__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or hostnames for the service. | -| `base_port` | `base-port` | `LANDSCAPE_SECRETS__BASE_PORT` | `8090` | Base port number for the service. | -| `devmode` | - | `LANDSCAPE_SECRETS__DEVMODE` | `None` | Development mode configuration (ex. `on`). | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SECRETS__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SECRETS__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SECRETS__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | -| `mailer` | - | `LANDSCAPE_SECRETS__MAILER` | `None` | Mailer service configuration. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_SECRETS__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | -| `oops_key` | `oops-key` | `LANDSCAPE_SECRETS__OOPS_KEY` | `None` | Key for OOPS error reporting system. | | `service_url` | `secrets-service-url` | `LANDSCAPE_SECRETS__SERVICE_URL` | `None` | The URL to use for the secrets service. Must include a port. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SECRETS__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `sslcert` | - | `LANDSCAPE_SECRETS__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_SECRETS__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_SECRETS__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_SECRETS__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_SECRETS__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_SECRETS__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_SECRETS__STORES` | `None` | The stores the service should use. | -| `threads` | - | `LANDSCAPE_SECRETS__THREADS` | `None` | Number of threads for the service. | | `vault_token` | - | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `None` | The token to use for the vault instead of getting it from the secrets service. | | `vault_url` | `secrets-url` | `LANDSCAPE_SECRETS__VAULT_URL` | `http://localhost:8200` | The address of the vault to use for the secrets service. | -| `workers` | - | `LANDSCAPE_SECRETS__WORKERS` | `None` | Number of worker processes for the service. | ## The `[stores]` section -The `[stores]` section contains configurations for database store connections and SSL settings used across Landscape services. +The `[stores]` section contains configurations for database store names and connections. In addition, the this section can use the {ref}`shared store settings `. | Key name | Deprecated key name | ENV name | Default | Purpose | | :------- | :------------------ | :------- | :------ | :------ | @@ -306,14 +256,7 @@ The `[stores]` section contains configurations for database store connections an | `resource_1` | `resource-1` | `LANDSCAPE_STORES__RESOURCE_1` | `landscape-standalone-resource-1` | The first resource database name. | | `resource_2` | `resource-2` | `LANDSCAPE_STORES__RESOURCE_2` | `None` | The second resource database name. Optional and used for testing only. | | `session` | - | `LANDSCAPE_STORES__SESSION` | `landscape-standalone-session` | The session database name. | -| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with autocommit isolation. | -| `sslcert` | - | `LANDSCAPE_STORES__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_STORES__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_STORES__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_STORES__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_STORES__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_STORES__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_STORES__STORES` | `None` | The stores the service should use. | +| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with {spellexception}`autocommit` isolation. | | `user` | - | `LANDSCAPE_STORES__USER` | `landscape` | The username for database connections. | ## The `[system]` section From 9214d2451e06ef5c4ed8f3d13f730526f932ce6c Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 19 Aug 2025 18:04:30 -0500 Subject: [PATCH 078/187] add step to create and validate autoinstall file --- .../setup-landscape-for-workstation-provisioning.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 11a9c2a5..52d92e92 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -48,6 +48,19 @@ See {ref}`how-to-external-auth-oidc`. 1. Navigate to **Org settings > Identity providers**. 2. Configure an OIDC client. +## Create and validate your autoinstall file + +```{important} +Landscape requires the use of the top-level `"autoinstall"` keyword. +``` + +See [the Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) +for more details on creating an autoinstall file. + +It is strongly recommended that you test your file by provisioning a client device. +See {ref}`how-to-provision-a-workstation` for details on provisioning a client device. +Landscape injects some configuration into the autoinstall file to enable the client device to register with the server after installation. + ## Upload autoinstall file ```{note} From 1f4a69060b17e4fdc4a3afb5937673bd95e2b393 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 19 Aug 2025 18:05:28 -0500 Subject: [PATCH 079/187] bump required server version to 25.10~beta.3 --- .../setup-landscape-for-workstation-provisioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md index 52d92e92..52d30b68 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md @@ -7,7 +7,7 @@ On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. ```{note} -This feature is available from Landscape server `25.08` onwards. +This feature is available from Landscape server `25.10~beta.3` onwards. ``` ## Install the `landscape-ubuntu-installer-attach` package @@ -15,7 +15,7 @@ This feature is available from Landscape server `25.08` onwards. Landscape requires an additional service for the Ubuntu installer attach experience. ```sh -sudo add-apt-repository ppa:landscape/latest-stable +sudo add-apt-repository ppa:landscape/self-hosted-beta sudo apt update sudo apt install landscape-ubuntu-installer-attach ``` From 3a5f2d7b6fdfeb2d433263211eb63fdb714ba055 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Tue, 26 Aug 2025 10:31:10 -0700 Subject: [PATCH 080/187] feat: add apt source delete handler docs (#57) --- .../api/rest-api-endpoints/repositories.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/reference/api/rest-api-endpoints/repositories.md diff --git a/docs/reference/api/rest-api-endpoints/repositories.md b/docs/reference/api/rest-api-endpoints/repositories.md new file mode 100644 index 00000000..d6e2de88 --- /dev/null +++ b/docs/reference/api/rest-api-endpoints/repositories.md @@ -0,0 +1,23 @@ +(reference-rest-api-repositories)= +# Repositories + +These methods give access to repository management. + +## DELETE `/repository/apt-source/` + +Remove an APT source. Optionally remove associations from any repository profiles. + +Path parameters: + +- `id`: The identification number of the APT source. + +Optional query parameters: + +- `disassociate_profiles`: If true, remove associations to this APT source from repository profiles. + +Example request: + +```bash +curl -X DELETE https://landscape.canonical.com/api/v2/repository/apt-source/12 -H "Authorization: Bearer $JWT" +``` + From 3ab3231385851eece5251c34e337319ebac401e4 Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Wed, 27 Aug 2025 16:03:47 -0700 Subject: [PATCH 081/187] feat: add apt source list endpoint doc (#59) --- .../api/rest-api-endpoints/repositories.md | 41 ++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/repositories.md b/docs/reference/api/rest-api-endpoints/repositories.md index d6e2de88..e295e5a7 100644 --- a/docs/reference/api/rest-api-endpoints/repositories.md +++ b/docs/reference/api/rest-api-endpoints/repositories.md @@ -3,6 +3,46 @@ These methods give access to repository management. +## GET `/repository/apt-source` + +Gets a list of APT sources. Optionally filter by APT source name or id. + +Optional query parameters: + +- `ids`: A comma separated list of APT source ids. All of the APT sources returned will have one of these ids. +- `names`: A comma separated list of APT source names. All of the APT sources returned will have one of these names. + +Example request: + +```bash +curl -X GET "https://landscape.canonical.com/api/v2/repository/apt-source?ids=100,101" -H "Authorization: Bearer $JWT" +``` + +Example output: + +```json +{ + "results": [ + { + "id": 100, + "name": "lucid-mirror", + "access_group": "global", + "line": "deb http://archive.ubuntu.com/ubuntu lucid main", + "gpg_key": null, + "profiles": ["myprofile"], + }, + { + "id": 101, + "name": "bionic-mirror", + "access_group": "global", + "line": "deb http://archive.ubuntu.com/ubuntu bionic main", + "gpg_key": null, + "profiles": ["profile2"], + } + ], +} +``` + ## DELETE `/repository/apt-source/` Remove an APT source. Optionally remove associations from any repository profiles. @@ -20,4 +60,3 @@ Example request: ```bash curl -X DELETE https://landscape.canonical.com/api/v2/repository/apt-source/12 -H "Authorization: Bearer $JWT" ``` - From 6084cc23af799d8772d913998997b6bbcf59cdfa Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 4 Sep 2025 10:21:57 -0500 Subject: [PATCH 082/187] separate configuration and administration documents --- ...=> administer-autoinstall-provisioning.md} | 28 ++------ ...deployment-for-autoinstall-provisioning.md | 68 +++++++++++++++++++ .../ubuntu-installer-provisioning/index.md | 5 +- 3 files changed, 77 insertions(+), 24 deletions(-) rename docs/how-to-guides/ubuntu-installer-provisioning/{setup-landscape-for-workstation-provisioning.md => administer-autoinstall-provisioning.md} (71%) create mode 100644 docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/administer-autoinstall-provisioning.md similarity index 71% rename from docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md rename to docs/how-to-guides/ubuntu-installer-provisioning/administer-autoinstall-provisioning.md index 52d30b68..60e4a29c 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/setup-landscape-for-workstation-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/administer-autoinstall-provisioning.md @@ -1,5 +1,5 @@ -(how-to-ubuntu-installer-provisioning-setup-landscape)= -# How to set up Landscape for workstation provisioning +(how-to-ubuntu-installer-provisioning-administer-autoinstall-provisioning)= +# How to administer autoinstall provisioning Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. @@ -7,30 +7,14 @@ On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. ```{note} -This feature is available from Landscape server `25.10~beta.3` onwards. +This feature is available from Landscape server `25.10~beta.4` onwards. ``` -## Install the `landscape-ubuntu-installer-attach` package +## Before you start -Landscape requires an additional service for the Ubuntu installer attach experience. +If you're on SaaS, you'll need to request that this feature is enabled for your account. -```sh -sudo add-apt-repository ppa:landscape/self-hosted-beta -sudo apt update -sudo apt install landscape-ubuntu-installer-attach -``` - -## Enable the feature - -On self-hosted, you'll need to set the feature flag in your `service.conf`: - -```ini -[features] -[...] -enable-employee-management = true -``` - -On SaaS, you'll need to make a request to support. +If you're on self-hosted, you'll need to configure your deployment to enable this feature. See {ref}`how-to-ubuntu-installer-provisioning-deployment-configuration`. ## Configure OIDC diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md new file mode 100644 index 00000000..02d3d785 --- /dev/null +++ b/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -0,0 +1,68 @@ +(how-to-ubuntu-installer-provisioning-deployment-configuration)= +# How to configure a Landscape deployment for autoinstall provisioning + +Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +Your Landscape account must use OIDC authentication. + +```{note} +This feature is available from Landscape server `25.10~beta.4` onwards. +``` + +## Install the `landscape-ubuntu-installer-attach` package + +Landscape requires an additional service for the Ubuntu installer attach experience. + +```sh +sudo add-apt-repository ppa:landscape/self-hosted-beta +sudo apt update +sudo apt install landscape-ubuntu-installer-attach +``` + +## Configure the proxy + +Landscape requires the `X-FQDN` header to be set in order to properly configure the autoinstall files. + +For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: + +```text +frontend haproxy-0-grpc-ubuntu-installer + bind 0.0.0.0:50051 ssl crt /var/lib/haproxy/default.pem alpn h2 + acl host_found hdr(host) -m found + http-request set-var(req.full_fqdn) hdr(authority) if !host_found + http-request set-var(req.full_fqdn) hdr(host) if host_found + http-request set-header X-FQDN %[var(req.full_fqdn)] + default_backend landscape-ubuntu-installer-attach-messenger + +backend landscape-ubuntu-installer-attach-messenger + mode http + server landscape-ubuntu-installer-attach-messenger-0-0 localhost:53354 proto h2 +``` + +- The installer expects the service to be available at port `50051` on the proxy. +- Port `53354` is the default port for the `ubuntu-installer-attach` service. + +## Enable the feature + +Set the feature flag in your `service.conf`: + +```ini +[features] +[...] +enable-employee-management = true +``` + +## Verify the connection + +```sh +curl -i https://:50051 +``` + +```text +HTTP/2 200 +content-type: application/grpc +grpc-status: 2 +grpc-message: Bad method header +``` + +Ensure that your server can be reached using HTTPS, and that the certificate is verifiable without additional flags. +The Ubuntu installer expects a valid SSL certificate that is signed by a known CA. diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/index.md b/docs/how-to-guides/ubuntu-installer-provisioning/index.md index 427798df..05c0ad8c 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/index.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/index.md @@ -6,5 +6,6 @@ :maxdepth: 2 :glob: -Setup Landscape for Workstation Provisioning -Provision a Workstation +Configure a deployment for autoinstall provisioning +Administer autoinstall provisioning +Provision a workstation From 19e29e15b68db6fb66f1c70b4c6f637200d2725d Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 4 Sep 2025 13:01:27 -0500 Subject: [PATCH 083/187] remove oidc-provider configuration --- .../openid-connect-oidc.md | 21 ------------------- 1 file changed, 21 deletions(-) diff --git a/docs/how-to-guides/external-authentication/openid-connect-oidc.md b/docs/how-to-guides/external-authentication/openid-connect-oidc.md index 89e96d29..ae0f8cc1 100644 --- a/docs/how-to-guides/external-authentication/openid-connect-oidc.md +++ b/docs/how-to-guides/external-authentication/openid-connect-oidc.md @@ -25,27 +25,6 @@ The `oidc-issuer` is the URL of the issuer. That URL should also be a discovery The `oidc-client-id` and `oidc-client-secret` should be provided by your OIDC provider when you create the client credentials. The provider may require setting an authorization redirect URI. This should look like `https://your_landscape/login/handle-openid`. If your provider also requires a logout redirect URL, this should be the address of your Landscape server such as `https://your_landscape/`. -### (Optional) Specify your provider to enable additional features - -Certain features are available only for certain OIDC providers. -Landscape recognizes the following slugs for providers: - -- `google`: Google OAuth 2.0 -- `okta`: Okta - -```bash -[landscape] -[…] -oidc-issuer = -oidc-client-id = 000000000000-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.apps.googleusercontent.com -oidc-client-secret = a4sDFAsdfA4F52as-asDfAsd -oidc-provider = google -``` - -You will still be able to authenticate as usual without specifying an `oidc-provider`. -It is not required for basic OIDC authentication. -If you change the value of your `oidc-provider`, it will be updated on your next authentication. - ## Restart all Landscape services To restart all Landscape services, run: From 38779015edca9781fc4393c97106a4d14e33786e Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 4 Sep 2025 13:13:04 -0500 Subject: [PATCH 084/187] add X-FQDN to configuration --- ...deployment-for-autoinstall-provisioning.md | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md index 02d3d785..92085898 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -20,17 +20,17 @@ sudo apt install landscape-ubuntu-installer-attach ## Configure the proxy -Landscape requires the `X-FQDN` header to be set in order to properly configure the autoinstall files. +This feature uses gRPC and requires an upstream proxy to perform HTTP/2 and TLS termination. + +- The installer expects the service to be available at port `50051` on the proxy. +- The installer uses HTTPS by default +- Port `53354` is the default port for the `ubuntu-installer-attach` service. For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: ```text frontend haproxy-0-grpc-ubuntu-installer bind 0.0.0.0:50051 ssl crt /var/lib/haproxy/default.pem alpn h2 - acl host_found hdr(host) -m found - http-request set-var(req.full_fqdn) hdr(authority) if !host_found - http-request set-var(req.full_fqdn) hdr(host) if host_found - http-request set-header X-FQDN %[var(req.full_fqdn)] default_backend landscape-ubuntu-installer-attach-messenger backend landscape-ubuntu-installer-attach-messenger @@ -38,8 +38,26 @@ backend landscape-ubuntu-installer-attach-messenger server landscape-ubuntu-installer-attach-messenger-0-0 localhost:53354 proto h2 ``` -- The installer expects the service to be available at port `50051` on the proxy. -- Port `53354` is the default port for the `ubuntu-installer-attach` service. +### (Optional) Configure the X-FQDN header + +```{note} +This is only useful for multitenant deployments. +If you are using self-hosted, you can disregard this. +``` + +For multitenant deployments, Landscape requires an `X-FQDN` header to disambiguate the tenant. + +For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: + +```text +frontend haproxy-0-grpc-ubuntu-installer + bind 0.0.0.0:50051 ssl crt /var/lib/haproxy/default.pem alpn h2 + default_backend landscape-ubuntu-installer-attach-messenger + acl host_found hdr(host) -m found + http-request set-var(req.full_fqdn) hdr(authority) if !host_found + http-request set-var(req.full_fqdn) hdr(host) if host_found + http-request set-header X-FQDN %[var(req.full_fqdn)] +``` ## Enable the feature From dc135fe87252514c290c6cb6ef359bb574f726b6 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:37:35 -0500 Subject: [PATCH 085/187] fix ubuntu installer index --- docs/how-to-guides/index.md | 9 ++++++++- .../how-to-guides/ubuntu-installer-provisioning/index.md | 2 +- .../provision-a-workstation.md | 4 ++-- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index ce1944a3..0dba54dd 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -93,6 +93,13 @@ These how-to guides can be applied to many key operations and common tasks with - {ref}`Perform common tasks ` - {ref}`Get support ` +(how-to-index-heading-ubuntu-installer)= +## Ubuntu installer + +- {ref}`Configure Landscape for autoinstall provisioning ` +- {ref}`Administer autoinstall provisioning ` +- {ref}`Provision a workstation ` + (how-to-index-heading-security)= ## Security @@ -116,7 +123,7 @@ repository-mirrors/index web-portal/index iot-for-devices/index wsl-integration/index +ubuntu-installer-provisioning/index security/index api/index -ubuntu-installer-provisioning/index ``` diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/index.md b/docs/how-to-guides/ubuntu-installer-provisioning/index.md index 05c0ad8c..bd2a5eb3 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/index.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/index.md @@ -1,5 +1,5 @@ (how-to-guides-ubuntu-installer-provisioning-index)= -# Provisioning devices with the Ubuntu Installer +# Ubuntu installer ```{toctree} :titlesonly: diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md index 63d4a131..836fffd7 100644 --- a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md @@ -1,4 +1,4 @@ -(how-to-provision-a-workstation)= +(how-to-ubuntu-installer-provision-a-workstation)= # How to provision a workstation using Landscape and the Ubuntu installer Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. @@ -16,7 +16,7 @@ Save this for the next step. ## In Landscape -1. Navigate to the **/attach** page in Landscape. +1. Navigate to the `/attach` page in Landscape. 1. Enter your 6 digit attach code. 1. Landscape will confirm that the attach code is valid and will prompt you to log in. 1. Authenticate against your OIDC provider. From 4454171c451a17a2732a67ea7da199aefc8134ed Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:38:05 -0500 Subject: [PATCH 086/187] rename ubuntu-installer-provisioning ubuntu-installer --- docs/how-to-guides/index.md | 2 +- .../administer-autoinstall-provisioning.md | 0 ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 0 .../index.md | 0 .../provision-a-workstation.md | 0 5 files changed, 1 insertion(+), 1 deletion(-) rename docs/how-to-guides/{ubuntu-installer-provisioning => ubuntu-installer}/administer-autoinstall-provisioning.md (100%) rename docs/how-to-guides/{ubuntu-installer-provisioning => ubuntu-installer}/configure-landscape-deployment-for-autoinstall-provisioning.md (100%) rename docs/how-to-guides/{ubuntu-installer-provisioning => ubuntu-installer}/index.md (100%) rename docs/how-to-guides/{ubuntu-installer-provisioning => ubuntu-installer}/provision-a-workstation.md (100%) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 0dba54dd..316e5411 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -123,7 +123,7 @@ repository-mirrors/index web-portal/index iot-for-devices/index wsl-integration/index -ubuntu-installer-provisioning/index +ubuntu-installer/index security/index api/index ``` diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md similarity index 100% rename from docs/how-to-guides/ubuntu-installer-provisioning/administer-autoinstall-provisioning.md rename to docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md similarity index 100% rename from docs/how-to-guides/ubuntu-installer-provisioning/configure-landscape-deployment-for-autoinstall-provisioning.md rename to docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/index.md b/docs/how-to-guides/ubuntu-installer/index.md similarity index 100% rename from docs/how-to-guides/ubuntu-installer-provisioning/index.md rename to docs/how-to-guides/ubuntu-installer/index.md diff --git a/docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md similarity index 100% rename from docs/how-to-guides/ubuntu-installer-provisioning/provision-a-workstation.md rename to docs/how-to-guides/ubuntu-installer/provision-a-workstation.md From ed237f7c1aa167111381750fe8f5eb5f48c52722 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:42:19 -0500 Subject: [PATCH 087/187] Ubuntu installer (24.04+) -> recent release of the Ubuntu installer (24.04 and later) --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 2 +- ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 2 +- docs/how-to-guides/ubuntu-installer/provision-a-workstation.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index 60e4a29c..89b764af 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -1,7 +1,7 @@ (how-to-ubuntu-installer-provisioning-administer-autoinstall-provisioning)= # How to administer autoinstall provisioning -Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 92085898..cc2d788b 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -1,7 +1,7 @@ (how-to-ubuntu-installer-provisioning-deployment-configuration)= # How to configure a Landscape deployment for autoinstall provisioning -Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. Your Landscape account must use OIDC authentication. ```{note} diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index 836fffd7..6a107ac1 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -1,7 +1,7 @@ (how-to-ubuntu-installer-provision-a-workstation)= # How to provision a workstation using Landscape and the Ubuntu installer -Recent releases of the Ubuntu installer (24.04+) can use Landscape to serve an autoinstall file. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. From 7e13a84c8ebe9df9557c17312880049ff6219507 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:53:22 -0500 Subject: [PATCH 088/187] add background info to intros --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 5 +++++ ...gure-landscape-deployment-for-autoinstall-provisioning.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index 89b764af..0b9e5450 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -10,6 +10,11 @@ Your Landscape account must use OIDC authentication. This feature is available from Landscape server `25.10~beta.4` onwards. ``` +## Background information + +[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. +Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. + ## Before you start If you're on SaaS, you'll need to request that this feature is enabled for your account. diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index cc2d788b..82c8a56d 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -8,6 +8,11 @@ Your Landscape account must use OIDC authentication. This feature is available from Landscape server `25.10~beta.4` onwards. ``` +## Background information + +[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. +Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. + ## Install the `landscape-ubuntu-installer-attach` package Landscape requires an additional service for the Ubuntu installer attach experience. From d5a9b8749aa60b9661b703633cf1cb3b9add823e Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:53:36 -0500 Subject: [PATCH 089/187] add cross-link to Subiquity in intros --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 2 ++ ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index 0b9e5450..941d0b17 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -1,6 +1,8 @@ (how-to-ubuntu-installer-provisioning-administer-autoinstall-provisioning)= # How to administer autoinstall provisioning +> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) + The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and SaaS Landscape. On SaaS Landscape, your account must be hosted on a subdomain. diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 82c8a56d..9a88471b 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -1,6 +1,8 @@ (how-to-ubuntu-installer-provisioning-deployment-configuration)= # How to configure a Landscape deployment for autoinstall provisioning +> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) + The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. Your Landscape account must use OIDC authentication. From fe9c25c0520d4d55c1e1a2d548777a4a61ef73b2 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 08:55:30 -0500 Subject: [PATCH 090/187] add note about beta PPA in example --- ...onfigure-landscape-deployment-for-autoinstall-provisioning.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 9a88471b..37e5eb05 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -18,6 +18,7 @@ Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at ## Install the `landscape-ubuntu-installer-attach` package Landscape requires an additional service for the Ubuntu installer attach experience. +This example uses the Landscape Beta PPA. ```sh sudo add-apt-repository ppa:landscape/self-hosted-beta From eb97ac60d894572d327706d5a289a8222e029974 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:01:57 -0500 Subject: [PATCH 091/187] clean up HAProxy configuration section --- ...dscape-deployment-for-autoinstall-provisioning.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 37e5eb05..b4a3bff0 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -30,11 +30,15 @@ sudo apt install landscape-ubuntu-installer-attach This feature uses gRPC and requires an upstream proxy to perform HTTP/2 and TLS termination. -- The installer expects the service to be available at port `50051` on the proxy. -- The installer uses HTTPS by default -- Port `53354` is the default port for the `ubuntu-installer-attach` service. +### Requirements -For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: +- The installer connects to the proxy on port 50051. +- The installer connects using HTTPS. +- The `ubuntu-installer-attach` service listens on port 53354 by default. + +### Example configuration (HAProxy) + +For example, if you're using HAProxy, add the following to `/etc/haproxy/haproxy.cfg`: ```text frontend haproxy-0-grpc-ubuntu-installer From 3b8bfb3ac807c695ba07ba56c529adba456f7907 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:02:42 -0500 Subject: [PATCH 092/187] multitenant -> multi-tenant --- ...igure-landscape-deployment-for-autoinstall-provisioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index b4a3bff0..8dcf89f5 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -53,11 +53,11 @@ backend landscape-ubuntu-installer-attach-messenger ### (Optional) Configure the X-FQDN header ```{note} -This is only useful for multitenant deployments. +This is only useful for multi-tenant deployments. If you are using self-hosted, you can disregard this. ``` -For multitenant deployments, Landscape requires an `X-FQDN` header to disambiguate the tenant. +For multi-tenant deployments, Landscape requires an `X-FQDN` header to disambiguate the tenant. For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: From 416dddc36a5b1626fc64d977ee0a86474ce217d4 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:04:05 -0500 Subject: [PATCH 093/187] fix X-FQDN instructions to show that user should do something --- ...figure-landscape-deployment-for-autoinstall-provisioning.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 8dcf89f5..3cac94bb 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -59,7 +59,8 @@ If you are using self-hosted, you can disregard this. For multi-tenant deployments, Landscape requires an `X-FQDN` header to disambiguate the tenant. -For example, if using HAProxy, include the following in `/etc/haproxy/haproxy.cfg`: +You'll need to configure this X-FQDN in your proxy settings. +For example, if you're using HAProxy, add the following to `/etc/haproxy/haproxy.cfg`: ```text frontend haproxy-0-grpc-ubuntu-installer From 2a89ead05cd8ecde39ca278fab45d11d462b0b71 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:05:15 -0500 Subject: [PATCH 094/187] enable featre -> set configuration --- ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 3cac94bb..95c043ed 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -74,7 +74,7 @@ frontend haproxy-0-grpc-ubuntu-installer ## Enable the feature -Set the feature flag in your `service.conf`: +Set the following configuration in your `service.conf`: ```ini [features] From 4f28275db69a13a5b5f4ae61f655d7545edfea69 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:06:36 -0500 Subject: [PATCH 095/187] fix verify section --- ...dscape-deployment-for-autoinstall-provisioning.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 95c043ed..3acd60a5 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -84,16 +84,20 @@ enable-employee-management = true ## Verify the connection +You should verify the connection to ensure that your server can be reached using HTTPS, and that the certificate is verifiable without additional flags. +The Ubuntu installer expects a valid SSL certificate that is signed by a known CA. + +For example: + ```sh -curl -i https://:50051 +curl -i https://:50051 ``` +Sample output: + ```text HTTP/2 200 content-type: application/grpc grpc-status: 2 grpc-message: Bad method header ``` - -Ensure that your server can be reached using HTTPS, and that the certificate is verifiable without additional flags. -The Ubuntu installer expects a valid SSL certificate that is signed by a known CA. From df668060770445005dbf970f6c46bf489df34f13 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:12:49 -0500 Subject: [PATCH 096/187] SaaS Landscape -> Landscape SaaS --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 4 ++-- .../how-to-guides/ubuntu-installer/provision-a-workstation.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index 941d0b17..8bd5fc0c 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -4,8 +4,8 @@ > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. -This is available on self-hosted and SaaS Landscape. -On SaaS Landscape, your account must be hosted on a subdomain. +This is available on self-hosted and Landscape SaaS. +On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. ```{note} diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index 6a107ac1..3b54ce58 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -2,8 +2,8 @@ # How to provision a workstation using Landscape and the Ubuntu installer The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. -This is available on self-hosted and SaaS Landscape. -On SaaS Landscape, your account must be hosted on a subdomain. +This is available on self-hosted and Landscape SaaS. +On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. ## In the Ubuntu installer From cb70080362dea9ee7fc73fe827525e25979e8a5f Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:18:37 -0500 Subject: [PATCH 097/187] oidc client -> oidc provider --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index 8bd5fc0c..e0809849 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -37,7 +37,7 @@ See {ref}`how-to-external-auth-oidc`. ### SaaS 1. Navigate to **Org settings > Identity providers**. -2. Configure an OIDC client. +2. Configure an OIDC provider. ## Create and validate your autoinstall file From c948d2e2d6394a6330cfbaf52694a932f27e7481 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:19:24 -0500 Subject: [PATCH 098/187] use Ubuntu's... when referencing autoinstall docs --- .../ubuntu-installer/administer-autoinstall-provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md index e0809849..32ca0f01 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md @@ -45,7 +45,7 @@ See {ref}`how-to-external-auth-oidc`. Landscape requires the use of the top-level `"autoinstall"` keyword. ``` -See [the Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) +See [Ubuntu's Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) for more details on creating an autoinstall file. It is strongly recommended that you test your file by provisioning a client device. From b64c6cdd730acf6a383c91c5c360f25e2ea7fff5 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:21:10 -0500 Subject: [PATCH 099/187] administer -> set up --- docs/how-to-guides/index.md | 2 +- docs/how-to-guides/ubuntu-installer/index.md | 2 +- ...all-provisioning.md => set-up-autoinstall-provisioning.md} | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename docs/how-to-guides/ubuntu-installer/{administer-autoinstall-provisioning.md => set-up-autoinstall-provisioning.md} (95%) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 316e5411..21f09014 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -97,7 +97,7 @@ These how-to guides can be applied to many key operations and common tasks with ## Ubuntu installer - {ref}`Configure Landscape for autoinstall provisioning ` -- {ref}`Administer autoinstall provisioning ` +- {ref}`Set up autoinstall provisioning ` - {ref}`Provision a workstation ` (how-to-index-heading-security)= diff --git a/docs/how-to-guides/ubuntu-installer/index.md b/docs/how-to-guides/ubuntu-installer/index.md index bd2a5eb3..05a9c938 100644 --- a/docs/how-to-guides/ubuntu-installer/index.md +++ b/docs/how-to-guides/ubuntu-installer/index.md @@ -7,5 +7,5 @@ :glob: Configure a deployment for autoinstall provisioning -Administer autoinstall provisioning +Set up autoinstall provisioning Provision a workstation diff --git a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md similarity index 95% rename from docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md rename to docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 32ca0f01..a200b727 100644 --- a/docs/how-to-guides/ubuntu-installer/administer-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -1,5 +1,5 @@ -(how-to-ubuntu-installer-provisioning-administer-autoinstall-provisioning)= -# How to administer autoinstall provisioning +(how-to-ubuntu-installer-provisioning-set-up-autoinstall-provisioning)= +# How to set up autoinstall provisioning > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) From 6a160e653bce0ddd6bc971f26481842208c8f395 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:24:12 -0500 Subject: [PATCH 100/187] fix setup guide - create/test/upload sections --- .../set-up-autoinstall-provisioning.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index a200b727..7f5c8054 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -39,7 +39,7 @@ See {ref}`how-to-external-auth-oidc`. 1. Navigate to **Org settings > Identity providers**. 2. Configure an OIDC provider. -## Create and validate your autoinstall file +## Create and test your autoinstall file ```{important} Landscape requires the use of the top-level `"autoinstall"` keyword. @@ -48,19 +48,19 @@ Landscape requires the use of the top-level `"autoinstall"` keyword. See [Ubuntu's Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) for more details on creating an autoinstall file. -It is strongly recommended that you test your file by provisioning a client device. -See {ref}`how-to-provision-a-workstation` for details on provisioning a client device. -Landscape injects some configuration into the autoinstall file to enable the client device to register with the server after installation. +It is strongly recommended that you test your file by provisioning a workstation. +See {ref}`how-to-ubuntu-installer-provision-a-workstation` for details on provisioning a workstation. +Landscape injects some configuration into the autoinstall file to enable the workstation to register with the server after installation. ## Upload autoinstall file ```{note} Currently, only the default file can be served to users. -Ensure that you set a default file. +You can set the default file in the Landscape web portal. ``` -1. Navigate to the **Employees > Autoinstall** tab. +1. Navigate to the **Org. settings > Employees > Autoinstall files** tab. 2. Upload your autoinstall file(s) to Landscape. 3. Set the autoinstall file to be your default autoinstall file. -Only one file may be the default. +Only one file can be set as the default, but you can change this default at any time. From 8e87b1c3ad4e089f531c3a6f8e7dab8a7b1be1d6 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 09:33:54 -0500 Subject: [PATCH 101/187] fix provision a workstation guide --- .../ubuntu-installer/provision-a-workstation.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index 3b54ce58..edfb7b30 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -16,14 +16,12 @@ Save this for the next step. ## In Landscape -1. Navigate to the `/attach` page in Landscape. -1. Enter your 6 digit attach code. -1. Landscape will confirm that the attach code is valid and will prompt you to log in. -1. Authenticate against your OIDC provider. +1. Navigate to `https:///attach`. +2. Enter your 6 digit attach code. Landscape will confirm that the attach code is valid and prompt you to log in. +3. Log in with your OIDC provider. ## Back in the Ubuntu installer -1. After successful authentication, Landscape will serve an autoinstall file to the Ubuntu installer. -1. Confirm the autoinstall file. - +After successful authentication, Landscape will serve an autoinstall file to the Ubuntu installer. +You need to confirm this autoinstall file. The Ubuntu installer will use the autoinstall file to provision your device. From a731cdf22ac5e830da69fee1bfd27ebcc5067301 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 10:22:07 -0500 Subject: [PATCH 102/187] improve h1 names - more verbose --- docs/how-to-guides/index.md | 4 ++-- ...re-landscape-deployment-for-autoinstall-provisioning.md | 4 ++-- .../ubuntu-installer/provision-a-workstation.md | 2 +- .../ubuntu-installer/set-up-autoinstall-provisioning.md | 7 ++++--- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index 21f09014..9a663902 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -96,8 +96,8 @@ These how-to guides can be applied to many key operations and common tasks with (how-to-index-heading-ubuntu-installer)= ## Ubuntu installer -- {ref}`Configure Landscape for autoinstall provisioning ` -- {ref}`Set up autoinstall provisioning ` +- {ref}`Configure Landscape for autoinstall provisioning ` +- {ref}`Set up autoinstall provisioning ` - {ref}`Provision a workstation ` (how-to-index-heading-security)= diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 3acd60a5..c2a9f02d 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -1,5 +1,5 @@ -(how-to-ubuntu-installer-provisioning-deployment-configuration)= -# How to configure a Landscape deployment for autoinstall provisioning +(how-to-ubuntu-installer-configure-landscape-deployment)= +# How to configure your Landscape deployment to provision workstations with Autoinstall via the Ubuntu installer > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index edfb7b30..e0ebed5d 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -1,5 +1,5 @@ (how-to-ubuntu-installer-provision-a-workstation)= -# How to provision a workstation using Landscape and the Ubuntu installer +# How to provision a workstation with Autoinstall using Landscape and the Ubuntu installer The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and Landscape SaaS. diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 7f5c8054..7a862ddf 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -1,5 +1,5 @@ -(how-to-ubuntu-installer-provisioning-set-up-autoinstall-provisioning)= -# How to set up autoinstall provisioning +(how-to-ubuntu-installer-set-up-landscape)= +# How to set up your Landscape server to provision workstations with Autoinstall via the Ubuntu installer > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) @@ -21,7 +21,8 @@ Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at If you're on SaaS, you'll need to request that this feature is enabled for your account. -If you're on self-hosted, you'll need to configure your deployment to enable this feature. See {ref}`how-to-ubuntu-installer-provisioning-deployment-configuration`. +If you're on self-hosted, you'll need to configure your deployment to enable this feature. +See {ref}`how-to-ubuntu-installer-configure-landscape-deployment`. ## Configure OIDC From e78818a5468af55dc72cf1f5026b5b4839304aac Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 10:37:25 -0500 Subject: [PATCH 103/187] add note about setup in the workstation provisioning guide --- docs/how-to-guides/ubuntu-installer/provision-a-workstation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index e0ebed5d..6701f7b0 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -5,6 +5,7 @@ The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall This is available on self-hosted and Landscape SaaS. On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. +Your Landscape administrator must have set up your Landscape deployment for workstation provisioning. See {ref}`how-to-ubuntu-installer-set-up-landscape`. ## In the Ubuntu installer From 13ba16f6800ae404c73b0de35b838e787a30fcb5 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 10:44:14 -0500 Subject: [PATCH 104/187] enable-employee-management -> employee_management --- ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index c2a9f02d..777e7842 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -79,7 +79,7 @@ Set the following configuration in your `service.conf`: ```ini [features] [...] -enable-employee-management = true +employee_management = true ``` ## Verify the connection From 9f4faa36890da14028b0ec6d4f306a2b3ffdaa54 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 17:26:47 -0500 Subject: [PATCH 105/187] add note about SaaS feature availability --- .../ubuntu-installer/set-up-autoinstall-provisioning.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 7a862ddf..392d0bb0 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -21,6 +21,11 @@ Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at If you're on SaaS, you'll need to request that this feature is enabled for your account. +```{note} +This feature is **not generally available on SaaS yet**. +It's only available for certain beta customers at this time. +``` + If you're on self-hosted, you'll need to configure your deployment to enable this feature. See {ref}`how-to-ubuntu-installer-configure-landscape-deployment`. From dadd8aaad559c618b5fbc40a8275a1bd61a36174 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Tue, 9 Sep 2025 17:29:16 -0500 Subject: [PATCH 106/187] move 'see subiquity docs' into background info --- ...igure-landscape-deployment-for-autoinstall-provisioning.md | 4 ++-- .../ubuntu-installer/set-up-autoinstall-provisioning.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 777e7842..35fbe155 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -1,8 +1,6 @@ (how-to-ubuntu-installer-configure-landscape-deployment)= # How to configure your Landscape deployment to provision workstations with Autoinstall via the Ubuntu installer -> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) - The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. Your Landscape account must use OIDC authentication. @@ -15,6 +13,8 @@ This feature is available from Landscape server `25.10~beta.4` onwards. [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. +> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) + ## Install the `landscape-ubuntu-installer-attach` package Landscape requires an additional service for the Ubuntu installer attach experience. diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 392d0bb0..827b68cc 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -1,8 +1,6 @@ (how-to-ubuntu-installer-set-up-landscape)= # How to set up your Landscape server to provision workstations with Autoinstall via the Ubuntu installer -> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) - The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and Landscape SaaS. On Landscape SaaS, your account must be hosted on a subdomain. @@ -17,6 +15,8 @@ This feature is available from Landscape server `25.10~beta.4` onwards. [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. +> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) + ## Before you start If you're on SaaS, you'll need to request that this feature is enabled for your account. From 24a026729f401819671dadc05a1fbe83d389da5f Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 11 Sep 2025 14:44:37 -0500 Subject: [PATCH 107/187] use paragraph styling --- ...deployment-for-autoinstall-provisioning.md | 15 ++++------- .../provision-a-workstation.md | 13 +++------ .../set-up-autoinstall-provisioning.md | 27 ++++++------------- 3 files changed, 16 insertions(+), 39 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 35fbe155..9c0082a0 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -1,8 +1,7 @@ (how-to-ubuntu-installer-configure-landscape-deployment)= # How to configure your Landscape deployment to provision workstations with Autoinstall via the Ubuntu installer -The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. -Your Landscape account must use OIDC authentication. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. Your Landscape account must use OIDC authentication. ```{note} This feature is available from Landscape server `25.10~beta.4` onwards. @@ -10,15 +9,13 @@ This feature is available from Landscape server `25.10~beta.4` onwards. ## Background information -[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. -Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. +[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) ## Install the `landscape-ubuntu-installer-attach` package -Landscape requires an additional service for the Ubuntu installer attach experience. -This example uses the Landscape Beta PPA. +Landscape requires an additional service for the Ubuntu installer attach experience. This example uses the Landscape Beta PPA. ```sh sudo add-apt-repository ppa:landscape/self-hosted-beta @@ -59,8 +56,7 @@ If you are using self-hosted, you can disregard this. For multi-tenant deployments, Landscape requires an `X-FQDN` header to disambiguate the tenant. -You'll need to configure this X-FQDN in your proxy settings. -For example, if you're using HAProxy, add the following to `/etc/haproxy/haproxy.cfg`: +You'll need to configure this X-FQDN in your proxy settings. For example, if you're using HAProxy, add the following to `/etc/haproxy/haproxy.cfg`: ```text frontend haproxy-0-grpc-ubuntu-installer @@ -84,8 +80,7 @@ employee_management = true ## Verify the connection -You should verify the connection to ensure that your server can be reached using HTTPS, and that the certificate is verifiable without additional flags. -The Ubuntu installer expects a valid SSL certificate that is signed by a known CA. +You should verify the connection to ensure that your server can be reached using HTTPS, and that the certificate is verifiable without additional flags. The Ubuntu installer expects a valid SSL certificate that is signed by a known CA. For example: diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index 6701f7b0..43ac523d 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -1,19 +1,14 @@ (how-to-ubuntu-installer-provision-a-workstation)= # How to provision a workstation with Autoinstall using Landscape and the Ubuntu installer -The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. -This is available on self-hosted and Landscape SaaS. -On Landscape SaaS, your account must be hosted on a subdomain. -Your Landscape administrator must have configured an OIDC login method. -Your Landscape administrator must have set up your Landscape deployment for workstation provisioning. See {ref}`how-to-ubuntu-installer-set-up-landscape`. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and Landscape SaaS. On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. Your Landscape administrator must have set up your Landscape deployment for workstation provisioning. See {ref}`how-to-ubuntu-installer-set-up-landscape`. ## In the Ubuntu installer 1. In the Ubuntu installer menu, select **install with Landscape**. 1. Enter the URL of your Landscape deployment. -The installer will generate a 6 digit attach code for you. -Save this for the next step. +The installer will generate a 6 digit attach code for you. Save this for the next step. ## In Landscape @@ -23,6 +18,4 @@ Save this for the next step. ## Back in the Ubuntu installer -After successful authentication, Landscape will serve an autoinstall file to the Ubuntu installer. -You need to confirm this autoinstall file. -The Ubuntu installer will use the autoinstall file to provision your device. +After successful authentication, Landscape will serve an autoinstall file to the Ubuntu installer. You need to confirm this autoinstall file. The Ubuntu installer will use the autoinstall file to provision your device. diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 827b68cc..23b9d539 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -1,10 +1,7 @@ (how-to-ubuntu-installer-set-up-landscape)= # How to set up your Landscape server to provision workstations with Autoinstall via the Ubuntu installer -The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. -This is available on self-hosted and Landscape SaaS. -On Landscape SaaS, your account must be hosted on a subdomain. -Your Landscape account must use OIDC authentication. +The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and Landscape SaaS. On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape account must use OIDC authentication. ```{note} This feature is available from Landscape server `25.10~beta.4` onwards. @@ -12,8 +9,7 @@ This feature is available from Landscape server `25.10~beta.4` onwards. ## Background information -[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. -Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. +[Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. > See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) @@ -22,19 +18,16 @@ Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at If you're on SaaS, you'll need to request that this feature is enabled for your account. ```{note} -This feature is **not generally available on SaaS yet**. -It's only available for certain beta customers at this time. +This feature is **not generally available on SaaS yet**. It's only available for certain beta customers at this time. ``` -If you're on self-hosted, you'll need to configure your deployment to enable this feature. -See {ref}`how-to-ubuntu-installer-configure-landscape-deployment`. +If you're on self-hosted, you'll need to configure your deployment to enable this feature. See {ref}`how-to-ubuntu-installer-configure-landscape-deployment`. ## Configure OIDC Landscape uses OIDC authentication for the workstation provisioning experience. -Only users that are known to the OIDC provider will be able to use the provisioning experience. -A local Landscape user that logs in with username/password will not. +Only users that are known to the OIDC provider will be able to use the provisioning experience. A local Landscape user that logs in with username/password will not. ### Self-hosted @@ -51,18 +44,14 @@ See {ref}`how-to-external-auth-oidc`. Landscape requires the use of the top-level `"autoinstall"` keyword. ``` -See [Ubuntu's Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) -for more details on creating an autoinstall file. +See [Ubuntu's Autoinstall configuration reference](https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html) for more details on creating an autoinstall file. -It is strongly recommended that you test your file by provisioning a workstation. -See {ref}`how-to-ubuntu-installer-provision-a-workstation` for details on provisioning a workstation. -Landscape injects some configuration into the autoinstall file to enable the workstation to register with the server after installation. +It is strongly recommended that you test your file by provisioning a workstation. See {ref}`how-to-ubuntu-installer-provision-a-workstation` for details on provisioning a workstation. Landscape injects some configuration into the autoinstall file to enable the workstation to register with the server after installation. ## Upload autoinstall file ```{note} -Currently, only the default file can be served to users. -You can set the default file in the Landscape web portal. +Currently, only the default file can be served to users. You can set the default file in the Landscape web portal. ``` 1. Navigate to the **Org. settings > Employees > Autoinstall files** tab. From b25835bfceff192d662fecdbc1998bcccf0146a2 Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 11 Sep 2025 14:55:08 -0500 Subject: [PATCH 108/187] add self-hosted/SaaS disclaimers --- ...andscape-deployment-for-autoinstall-provisioning.md | 4 ++++ .../ubuntu-installer/provision-a-workstation.md | 8 ++++++++ .../set-up-autoinstall-provisioning.md | 10 ++++------ 3 files changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 9c0082a0..4e505560 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -7,6 +7,10 @@ The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall This feature is available from Landscape server `25.10~beta.4` onwards. ``` +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts. +``` + ## Background information [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. diff --git a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md index 43ac523d..68f94ff4 100644 --- a/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md +++ b/docs/how-to-guides/ubuntu-installer/provision-a-workstation.md @@ -3,6 +3,14 @@ The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall file. This is available on self-hosted and Landscape SaaS. On Landscape SaaS, your account must be hosted on a subdomain. Your Landscape administrator must have configured an OIDC login method. Your Landscape administrator must have set up your Landscape deployment for workstation provisioning. See {ref}`how-to-ubuntu-installer-set-up-landscape`. +```{note} +This feature is available from Landscape server `25.10~beta.4` onwards. +``` + +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts. +``` + ## In the Ubuntu installer 1. In the Ubuntu installer menu, select **install with Landscape**. diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index 23b9d539..c8151020 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -7,6 +7,10 @@ The Ubuntu installer (24.04 and later) can use Landscape to serve an autoinstall This feature is available from Landscape server `25.10~beta.4` onwards. ``` +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts. +``` + ## Background information [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. @@ -15,12 +19,6 @@ This feature is available from Landscape server `25.10~beta.4` onwards. ## Before you start -If you're on SaaS, you'll need to request that this feature is enabled for your account. - -```{note} -This feature is **not generally available on SaaS yet**. It's only available for certain beta customers at this time. -``` - If you're on self-hosted, you'll need to configure your deployment to enable this feature. See {ref}`how-to-ubuntu-installer-configure-landscape-deployment`. ## Configure OIDC From ff62cab7157e2587ec10f113e7cceec7187e9d4d Mon Sep 17 00:00:00 2001 From: Spencer Runde Date: Thu, 11 Sep 2025 15:58:34 -0500 Subject: [PATCH 109/187] fix background info - use paragraph instead of callout --- ...nfigure-landscape-deployment-for-autoinstall-provisioning.md | 2 +- .../ubuntu-installer/set-up-autoinstall-provisioning.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md index 4e505560..6a7e4eb3 100644 --- a/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/configure-landscape-deployment-for-autoinstall-provisioning.md @@ -15,7 +15,7 @@ This feature is available on self-hosted and **select accounts on SaaS**. It is [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. -> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) +See the [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) for more information. ## Install the `landscape-ubuntu-installer-attach` package diff --git a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md index c8151020..e146ccd5 100644 --- a/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md +++ b/docs/how-to-guides/ubuntu-installer/set-up-autoinstall-provisioning.md @@ -15,7 +15,7 @@ This feature is available on self-hosted and **select accounts on SaaS**. It is [Autoinstall](https://canonical-subiquity.readthedocs-hosted.com/en/latest/intro-to-autoinstall.html) is a means to automate an Ubuntu installation. Landscape integrates with the Ubuntu installer to deliver an Autoinstall file at installation time. -> See also: [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) +See the [Ubuntu installation (Subiquity) documentation](https://canonical-subiquity.readthedocs-hosted.com/en/latest/index.html) for more information. ## Before you start From 7a88f4db5eb3eec091c69a9f1dd1e0e3ed17c8ec Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Wed, 17 Sep 2025 10:48:26 -0700 Subject: [PATCH 110/187] feat: document self-service account creation endpoint (#62) --- README.md | 2 +- docs/.sphinx/.wordlist.txt | 2 + .../api/rest-api-endpoints/accounts.md | 50 +++++++++++++++++++ 3 files changed, 53 insertions(+), 1 deletion(-) create mode 100644 docs/reference/api/rest-api-endpoints/accounts.md diff --git a/README.md b/README.md index 9fb11fd0..1647cf0a 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Landscape is used by system administrators, security teams, IT managers, and com ## Project and community -Landscape is a member of the Ubuntu family. It welcomes community contributions, suggestions, fixes and constructive feedback. +Landscape is a member of the Ubuntu family. It welcomes community contributions, suggestions, fixes and constructive feedback. * [Our Code of Conduct](https://launchpad.net/codeofconduct/2.0) * [Get support](https://ubuntu.com/support/community-support) diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt index 2ede8913..116e8e7b 100644 --- a/docs/.sphinx/.wordlist.txt +++ b/docs/.sphinx/.wordlist.txt @@ -60,6 +60,8 @@ Rootfs RTD subdirectories subfolders +Subiquity +subiquity subtree TODO Ubuntu diff --git a/docs/reference/api/rest-api-endpoints/accounts.md b/docs/reference/api/rest-api-endpoints/accounts.md new file mode 100644 index 00000000..b89ef2d7 --- /dev/null +++ b/docs/reference/api/rest-api-endpoints/accounts.md @@ -0,0 +1,50 @@ +(reference-rest-api-accounts)= + +# Accounts + +The endpoints available here are related to account management. + +## POST `/account` + +Create an account for the current user. If the user already has an account, or self-service account creation is disabled, the request will fail. + +If successful, the current user will be an admin of the account. + +Path parameters: + +- None + +Required parameters: + +- `title`: The title of the organization. + +Example request: + +```bash +curl -X POST https://landscape.canonical.com/api/v2/accounts -H "Authorization: Bearer $JWT" -d '{"title": "Onward, Inc."}' +``` + +Example response: + +```json +{ + "account": "8xag1afp", + "creation_time": "2025-09-15T22:52:11Z", + "administrators": [ + { + "name": "Your Name", + "email": "yourname@example.com", + "openid": "youropenid" + } + ], + "disabled": false, + "disabled_reason": null, + "computers": 0, + "company": "Onward, Inc.", + "last_login_time": "2025-09-15T22:52:11Z", + "licenses": [], + "salesforce_account_key": null, + "enabled_features": [], + "subdomain": null +} +``` From ce3d2f306191fec0b7191b5b90d98a0a85adadce Mon Sep 17 00:00:00 2001 From: Justin Kim Date: Thu, 18 Sep 2025 10:18:08 -0700 Subject: [PATCH 111/187] feat: reference for accept invitation rest endpoint (#63) --- .../api/rest-api-endpoints/invitations.md | 39 +++++++++++++++++-- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/docs/reference/api/rest-api-endpoints/invitations.md b/docs/reference/api/rest-api-endpoints/invitations.md index 61ed5534..c4622e25 100644 --- a/docs/reference/api/rest-api-endpoints/invitations.md +++ b/docs/reference/api/rest-api-endpoints/invitations.md @@ -1,6 +1,31 @@ (reference-rest-api-invitations)= + # Invitations +## POST `/accept-invitation` + +Accept an invitation for the current user. + +Required parameters: + +- `invitation_id`: The alphanumeric string used to identify the invitation. + +Example request: + +```bash +curl -X POST "https://landscape.canonical.com/api/v2/accept-invitation" -H "Authorization: Bearer $JWT" -d '{"invitation_id": "rqRmwFduPFTM1uy5cO0tOSovS4KNGG"}' + +``` + +Example output: + +```json +{ + "account_id": 4, + "account_title": "My Account" +} +``` + ## GET `/invitations` Get all invitations for the account that the principal is associated with. @@ -14,12 +39,14 @@ Query parameters: - None Example request: + ```bash curl -X GET "https://landscape.canonical.com/api/v2/invitations" -H "Authorization: Bearer $JWT" ``` Example output: -```bash + +```json { "count": 2, "results": [ @@ -59,12 +86,14 @@ Optional parameters: - `roles`: If specified, a list of strings with the roles that the administrator will have in your account. Example request: + ```bash curl -X POST "https://landscape.canonical.com/api/v2/invitations" -H "Authorization: Bearer $JWT" -d '{"name": "Bobby", "email": "bobby@ubuntu.com", "roles": ["Auditor", "SupportAnalyst"]}' ``` Example output: -```bash + +```json { "id": 4, "secure_id": "ozVPhiV41ZfgyP53QHvlwOP3syeKel" @@ -84,6 +113,7 @@ Optional parameters: - None Example request: + ```bash curl -X DELETE "https://landscape.canonical.com/api/v2/invitations/4" -H "Authorization: Bearer $JWT" ``` @@ -101,12 +131,14 @@ Query parameters: - None Example request: + ```bash curl -X GET "https://landscape.canonical.com/api/v2/invitations/2" -H "Authorization: Bearer $JWT" ``` Example output: -```bash + +```json { "id": 2, "secure_id": "YE6XEiWr5T0HUBgMhXAwgyofwY5EKd", @@ -116,4 +148,3 @@ Example output: "creation_time": "2024-03-20T14:49:25Z" } ``` - From 6bf549b7bea730edc8a0950e1f4218c8cc76b6c4 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Fri, 19 Sep 2025 10:53:26 -0500 Subject: [PATCH 112/187] add documentation for licensing management --- docs/explanation/features/activities.md | 1 + docs/explanation/landscape/licenses.md | 6 + .../api/rest-api-endpoints/activities.md | 2 +- .../api/rest-api-endpoints/computers.md | 4 + .../rest-api-endpoints/license-management.md | 260 ++++++++++++++++++ 5 files changed, 272 insertions(+), 1 deletion(-) create mode 100644 docs/reference/api/rest-api-endpoints/license-management.md diff --git a/docs/explanation/features/activities.md b/docs/explanation/features/activities.md index 6a8ce2d1..c965a755 100644 --- a/docs/explanation/features/activities.md +++ b/docs/explanation/features/activities.md @@ -95,3 +95,4 @@ Activities can start in the `Queued`, `Scheduled`, `Waiting`, or `Blocked` state - `GenerateUsgReportActivity` - `RemoveComputerActivity` - `AttachProRequest` +- `DetachProRequest` \ No newline at end of file diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index b3fb6799..0186f4d9 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -9,6 +9,12 @@ For Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documen For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. +Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. + +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and unavailable for offline deployments. +``` + ## License type You can view the number of seats used per license type for each computer in the classic web portal. This functionality is in the **Licenses** tab. diff --git a/docs/reference/api/rest-api-endpoints/activities.md b/docs/reference/api/rest-api-endpoints/activities.md index 679562ac..63b340c0 100644 --- a/docs/reference/api/rest-api-endpoints/activities.md +++ b/docs/reference/api/rest-api-endpoints/activities.md @@ -151,7 +151,7 @@ Query parameters: Example request: ```bash -curl -X GET https://landscape.canonical.com/api/v2/activities/parents?limit=2 -H "Authorization: Bearer $JWT +curl -X GET https://landscape.canonical.com/api/v2/activities/parents?limit=2 -H "Authorization: Bearer $JWT" ``` Example output: diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 86d730cc..80a9f7d1 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -32,6 +32,10 @@ Query parameters: - `profile:wsl::`: Instances associated with the specified WSL Child Instance Profile. The `` is the database id of the profile. The `` must either be `compliant` or `noncompliant`. - `OR`: Search for computers matching term A or term B. The text `OR` must be in all-caps. - `NOT`: search for computers not matching the next term. The text `NOT` must be in all-caps. + - `license-type:`: Instances associated with the specified <`license-type`>. The `license-type` must be one of `unlicensed`, `pro`, `free_pro`, `legacy`. + - `contract:`: Instances associated with the specified <`contract-id>`. + - `contract-expires-within-days:`: Instances associated with a Ubuntu Pro contract that expires within `` days. + - `license-expires-within-days:`: Instances associated with a Legacy License that expires within `` days. - `limit`: The maximum number of results returned by the method. It defaults to 1000. - `offset`: The offset inside the list of results. - `with_alerts`: If true, includes alert information in each computer object if that alert is active. Defaults to false. diff --git a/docs/reference/api/rest-api-endpoints/license-management.md b/docs/reference/api/rest-api-endpoints/license-management.md new file mode 100644 index 00000000..c5f9dcff --- /dev/null +++ b/docs/reference/api/rest-api-endpoints/license-management.md @@ -0,0 +1,260 @@ +(license-management)= +# License Management + +## POST `/attach-token` + +Attach a provided Ubuntu Pro token to the provided computer ids. This will create an activity on each client and place them into the proper license state if the activity succeeds. + +Required parameters: + +- `computer_ids`: A list of the specified ID(s) as integers for a computer. +- `token`: The Ubuntu Pro token to attach to computers. + +Optional parameters: + +- None + +Example Request: + +```bash +curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2, 3, 4], "token": ""}' +``` + +Example Response: +```json +{ + "activity": { + "activity_status": "undelivered", + "approval_time": null, + "completion_time": null, + "creation_time": "2025-09-19T14:24:07Z", + "creator": { + "email": "john@example.com", + "id": 1, + "name": "John Smith" + }, + "deliver_delay_window": 0, + "id": 113, + "parent_id": null, + "result_code": null, + "result_text": null, + "summary": "Attach a pro token to computers", + "type": "ActivityGroup" + }, + "invalid_computer_ids": [ + 3, + 4, + 5, + 6 + ] +} +``` + +```{note} +"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist +``` + +## POST `/detach-token` + +Detach an Ubuntu Pro subscription from the provided computer ids. This will create an activity on each client and place them into the proper license state if the activity succeeds. + +```{note} +This endpoint is feature flagged behind `ubuntu_pro_licensing`. +``` + +Required parameters: + +- `computer_ids`: A list of the specified ID(s) as integers for a computer. + +Optional parameters: + +- None + +Example Request: + +```bash +curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2, 3, 4]}' +``` + +Example Response: + +```json +{ + "activity": { + "activity_status": "undelivered", + "approval_time": null, + "completion_time": null, + "creation_time": "2025-09-19T14:28:32Z", + "creator": { + "email": "john@example.com", + "id": 1, + "name": "John Smith" + }, + "deliver_delay_window": 0, + "id": 116, + "parent_id": null, + "result_code": null, + "result_text": null, + "summary": "Detach pro token from computers", + "type": "ActivityGroup" + }, + "invalid_computer_ids": [ + 3, + 4, + 5, + 6 + ] +} +``` + +```{note} +"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist +``` + +## GET `/legacy-licenses` + +Gets all information on legacy licenses associated with an account. + +Required parameters: + +- None + +Optional parameters: + +- None + +Example Request: + +```bash +curl -X GET https://your-landscape-domain.com/api/v2/legacy-licenses -H "Authorization: Bearer $JWT" +``` + +Example Response: + +```json +{ + "results": [ + { + "available_seats": 12, + "expiration_date": null, + "id": 1 + }, + { + "available_seats": 4, + "expiration_date": "2026-09-17", + "id": 8 + }, + { + "available_seats": 9, + "expiration_date": "2026-09-17", + "id": 9 + } + ] +} +``` + +## GET `/legacy-licenses/` + +Gets the specified legacy license information from provided path id. + +Required parameters: + +- None + +Optional parameters: + +- None + +Path parameters: + +- id: license id to get information on + +Example Request: + +```bash +curl -X GET https://your-landscape-domain.com/api/v2/legacy-licenses/8 -H "Authorization: Bearer $JWT" +``` + +Example Response: + +```json +{ + "available_seats": 4, + "expiration_date": "2026-09-17", + "id": 8 +} +``` + +## GET `/contracts` + +Gets all information on Ubuntu Pro Contracts associated with an account. + +Required parameters: + +- None + +Optional parameters: + +- None + +Example Request: + +```bash +curl -X GET https://your-landscape-domain.com/api/v2/contracts -H "Authorization: Bearer $JWT" +``` + +Example Response: + +```json +{ + "results": [ + { + "contract_id": "contract-id-1", + "expiration_date": "2025-12-31T00:00:00", + "id": 1 + }, + { + "contract_id": "contract-id-2", + "expiration_date": "2026-12-31T00:00:00", + "id": 2 + }, + { + "contract_id": "contract-id-3", + "expiration_date": "3000-01-01T00:00:00", + "id": 3 + } + ] +} +``` + +## GET `/contracts/` + +Gets the specified contract information from provided path id. + +Required parameters: + +- None + +Optional parameters: + +- None + +Path parameters: + +- id: contract to get information on + +Example Request: + +```bash +curl -X GET https://your-landscape-domain.com/api/v2/contracts/contract-id-1 -H "Authorization: Bearer $JWT" +``` + +Example Response: + +```json +{ + "contract_id": "contract-id-1", + "expiration_date": "2025-12-31T00:00:00", + "id": 1 +} +``` \ No newline at end of file From 2d6c2358526b1df1e696cde251211b43e9775999 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Fri, 19 Sep 2025 11:42:52 -0500 Subject: [PATCH 113/187] include optional params for licenses --- docs/reference/api/rest-api-endpoints/license-management.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/license-management.md b/docs/reference/api/rest-api-endpoints/license-management.md index c5f9dcff..52d2d87c 100644 --- a/docs/reference/api/rest-api-endpoints/license-management.md +++ b/docs/reference/api/rest-api-endpoints/license-management.md @@ -121,7 +121,8 @@ Required parameters: Optional parameters: -- None +- available_only: only include licenses that have open seats. +- active_only: only include licenses that are not expired. Example Request: From b324ed7576a0362d9e72f76890684d475b94e7a6 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Fri, 19 Sep 2025 16:21:38 -0700 Subject: [PATCH 114/187] feat: replace tables with more readable sections (#69) --- docs/.custom_wordlist.txt | 1 + docs/reference/config/service-conf.md | 187 ++++++++++++++++++++++---- 2 files changed, 163 insertions(+), 25 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index b8295926..84072ffb 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -162,6 +162,7 @@ mis miscategorized misconfigurations Mitaka +mTLS MTU MTUs Multipass diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 2fa60d49..9b3e6127 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -17,43 +17,181 @@ In addition, the names of some sections of the `service.conf` file are deprecate ``` (shared-service-settings)= + ## Shared service settings -There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service: +There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `allowed_interfaces` | - | `LANDSCAPE_SERVICE__ALLOWED_INTERFACES` | `None` | A list of allowed IP addresses or hostnames for the service. | -| `base_port` | `base-port` | `LANDSCAPE_SERVICE__BASE_PORT` | `8090` | Base port number for the service. | -| `devmode` | - | `LANDSCAPE_SERVICE__DEVMODE` | `None` | Development mode configuration (ex. `on`). | -| `enable_metrics` | `enable-metrics` | `LANDSCAPE_SERVICE__ENABLE_METRICS` | `False` | Whether to enable metrics collection for the service. | -| `gpg_home_path` | `gpg-home-path` | `LANDSCAPE_SERVICE__GPG_HOME_PATH` | `None` | Path to the GPG home directory. | -| `gpg_passphrase_path` | `gpg-passphrase-path` | `LANDSCAPE_SERVICE__GPG_PASSPHRASE_PATH` | `None` | Path to the GPG passphrase file. Required if `gpg_home_path` is set. | -| `mailer` | - | `LANDSCAPE_SERVICE__MAILER` | `None` | Mailer service configuration. | -| `mailer_path` | `mailer-path` | `LANDSCAPE_SERVICE__MAILER_PATH` | `None` | Path to the mailer executable. Required if `mailer` is set. | -| `oops_key` | `oops-key` | `LANDSCAPE_SERVICE__OOPS_KEY` | `None` | Key for OOPS error reporting system. | -| `soft_timeout` | `soft-timeout` | `LANDSCAPE_SERVICE__SOFT_TIMEOUT` | `None` | Soft timeout value in seconds for service operations. | -| `threads` | - | `LANDSCAPE_SERVICE__THREADS` | `None` | Number of threads for the service. | -| `workers` | - | `LANDSCAPE_SERVICE__WORKERS` | `None` | Number of worker processes for the service. | +### `allowed_interfaces` + +- Purpose: A list of allowed IP addresses or hostnames for the service. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__ALLOWED_INTERFACES` +- Default: `None` + +### `base_port` + +- Purpose: Workers for the service will run on ports incrementing from this base port. +- Deprecated key name: `base-port` +- ENV name: `LANDSCAPE_SERVICE__BASE_PORT` +- Default: `8090` + +### `devmode` + +- Purpose: To control development mode configuration. This setting should not be configured in production environments. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__DEVMODE` +- Default: `None` + +### `enable_metrics` + +- Purpose: Whether to enable metrics collection for the service. +- Deprecated key name: `enable-metrics` +- ENV name: `LANDSCAPE_SERVICE__ENABLE_METRICS` +- Default: `False` + +### `gpg_home_path` + +- Purpose: Sets the path to the GPG home directory. +- Deprecated key name: `gpg-home-path` +- ENV name: `LANDSCAPE_SERVICE__GPG_HOME_PATH` +- Default: `None` + +### `gpg_passphrase_path` + +- Purpose: Sets the path to the GPG passphrase file. Required if `gpg_home_path` is set. +- Deprecated key name: `gpg-passphrase-path` +- ENV name: `LANDSCAPE_SERVICE__GPG_PASSPHRASE_PATH` +- Default: `None` + +### `mailer` + +- Purpose: If set to `queue` the mailer will use the queue specified by the `mailer_path`. If set to `default` the queue will be at `/tmp/landscape-mail-queue`. If unset, no mailer will be configured for the service. Production deployments do not need to modify this setting. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__MAILER` +- Default: `None` + +### `mailer_path` + +- Purpose: Path to the mail queue. Required if `mailer` is set. +- Deprecated key name: `mailer-path` +- ENV name: `LANDSCAPE_SERVICE__MAILER_PATH` +- Default: `None` + +### `oops_key` + +- Purpose: Key for OOPS error reporting system. Production deployments do not need to modify this setting. +- Deprecated key name: `oops-key` +- ENV name: `LANDSCAPE_SERVICE__OOPS_KEY` +- Default: `None` + +### `root_url` + +- Purpose: The URL for the service. +- Deprecated key name: `root-url` +- ENV name: `LANDSCAPE_SERVICE__ROOT_URL` +- Default: `None` + +### `soft_timeout` + +- Purpose: Soft timeout value in seconds for the OOPS reporter. +- Deprecated key name: `soft-timeout` +- ENV name: `LANDSCAPE_SERVICE__SOFT_TIMEOUT` +- Default: `None` + +### `ssl_server_cert` + +- Purpose: Sets the path to the certificate to use for mTLS. If set, `ssl_private_key` must also be set. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__SSL_SERVER_CERT` +- Default: `None` + +### `ssl_private_key` + +- Purpose: Sets the path to the private key to use for mTLS. If set, `ssl_server_cert` must also be set. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__SSL_PRIVATE_KEY` +- Default: `None` + +### `ssl_ca_cert` + +- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_private_key` and `ssl_server_cert` must also be set. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__SSL_CA_CERT` +- Default: `None` + +### `threads` + +- Purpose: Number of threads for the service to use. This setting only applies to Twisted services. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__THREADS` +- Default: `None` + +### `workers` + +- Purpose: Number of worker processes for the service. If unset, the service will have a single worker. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SERVICE__WORKERS` +- Default: `None` ```{important} The shared service settings are not mutually exclusive with the shared store settings; services can use both, if specified. ``` (shared-store-settings)= + ## Shared store settings There are a set of generic settings related to databases and SSL connections to Postgres that several sections can set, where `SECTION` in the ENV name matches the (uppercase) name of the section: -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `sslcert` | - | `LANDSCAPE_SECTION__SSLCERT` | `None` | Path to the client certificate to use for SSL connection to Postgres (becomes `PGSSLCERT`). | -| `sslkey` | - | `LANDSCAPE_SECTION__SSLKEY` | `None` | Path to the private key to use for SSL connection to Postgres (becomes `PGSSLKEY`). | -| `sslmode` | - | `LANDSCAPE_SECTION__SSLMODE` | `None` | SSL mode when connecting to Postgres, for example `verify-full`. | -| `sslrootcert` | - | `LANDSCAPE_SECTION__SSLROOTCERT` | `None` | Path to the root CA certificate to use for SSL connection to Postgres (becomes `PGSSLROOTCERT`). | -| `store_password` | - | `LANDSCAPE_SECTION__STORE_PASSWORD` | `None` | Overrides the store password. | -| `store_user` | - | `LANDSCAPE_SECTION__STORE_USER` | `None` | Overrides the store username. | -| `stores` | - | `LANDSCAPE_SECTION__STORES` | `None` | The stores the service should use. | +### `sslcert` + +- Purpose: Path to the client certificate to use for SSL connection to Postgres. Landscape Server will set this as the `PGSSLCERT` environment variable for Postgres to consume. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSLCERT` +- Default: `None` + +### `sslkey` + +- Purpose: Path to the private key to use for SSL connection to Postgres. Landscape Server will set this as the `PGSSLKEY` environment variable for Postgres to consume. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSLKEY` +- Default: `None` + +### `sslmode` + +- Purpose: SSL mode to use when connecting to Postgres, for example `verify-full`. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSLMODE` +- Default: `None` + +### `sslrootcert` + +- Purpose: Path to the root CA certificate to use for SSL connection to Postgres. Landscape Server will set this as the `PGSSLROOTCERT` environment variable for Postgres to consume. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSLROOTCERT` +- Default: `None` + +### `store_password` + +- Purpose: Overrides the store password set in the `store` settings. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__STORE_PASSWORD` +- Default: `None` + +### `store_user` + +- Purpose: Overrides the store username set in the `store` settings. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__STORE_USER` +- Default: `None` + +### `stores` + +- Purpose: The stores the service should use. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__STORES` +- Default: `None` ```{important} The shared store settings are not mutually exclusive with the shared service settings; services can use both, if specified. @@ -210,7 +348,6 @@ The `[oops]` section contains configurations for the OOPS error reporting and de | `path` | - | `LANDSCAPE_OOPS__PATH` | `None` | File path for OOPS configuration. | | `reporter` | - | `LANDSCAPE_OOPS__REPORTER` | `None` | Error reporter configuration. | - The `[schema]` section contains configurations for updating the database schema. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. ## The `[package_upload]` section From b5644ec05579b3949c7bff4b8e1657a1539b7bfa Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Fri, 19 Sep 2025 16:40:48 -0700 Subject: [PATCH 115/187] refactor: update api config settings (#70) --- docs/.custom_wordlist.txt | 1 + docs/reference/config/service-conf.md | 29 +++++++++++++++++++++------ 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 84072ffb..e6b0d6d7 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -81,6 +81,7 @@ dput Entra epoll ESM +Fernet FIPS FQDN gapped diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 9b3e6127..f3ae5f80 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -201,12 +201,29 @@ The shared store settings are not mutually exclusive with the shared service set The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `cookie_encryption_key` | `cookie-encryption-key` | `LANDSCAPE_API__COOKIE_ENCRYPTION_KEY` | `None` | The key used to encrypt state and nonce cookies. | -| `cors_allow_all` | `cors-allow-all` | `LANDSCAPE_API__CORS_ALLOW_ALL` | `False` | Whether to allow CORS. | -| `root_url` | `root-url` | `LANDSCAPE_API__ROOT_URL` | `None` | The API URL to use. | -| `snap_store_api_url` | `snap-store-api-url` | `LANDSCAPE_API__SNAP_STORE_API_URL` | `https://api.snapcraft.io/v2` | The API for a Snap Store Proxy. By default, this is the Canonical Snap Store. | +### `cookie_encryption_key` + +- Purpose: The key used to encrypt state and nonce cookies. Must be 32 url-safe, base64-encoded bytes. If unset, Landscape will generate and set a key using the Fernet symmetric encryption algorithm. If the key is invalid, the `landscape-api` service will fail to start. +- Deprecated key name: `cookie-encryption-key` +- ENV name: `LANDSCAPE_API__COOKIE_ENCRYPTION_KEY` +- Default: `None` + +### `cors_allow_all` + +- Purpose: This setting should only be enabled in a development environment. If `True`, the following headers will be set in HTTP responses from the API service: + - `Access-Control-Allow-Origin: *` + - `Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS` + - `Access-Control-Allow-Credentials: true` +- Deprecated key name: `cors-allow-all` +- ENV name: `LANDSCAPE_API__CORS_ALLOW_ALL` +- Default: `False` + +### `snap_store_api_url` + +- Purpose: The API for a Snap Store Proxy. By default, this is the Canonical Snap Store. +- Deprecated key name: `snap-store-api-url` +- ENV name: `LANDSCAPE_API__SNAP_STORE_API_URL` +- Default: `https://api.snapcraft.io/v2` ## The `[appserver]` section From 17173d864e9b329175d051bbc618d47d740f79ea Mon Sep 17 00:00:00 2001 From: david-mclain Date: Mon, 22 Sep 2025 13:41:35 -0500 Subject: [PATCH 116/187] touch up some doc stuff --- docs/explanation/landscape/licenses.md | 2 +- .../api/rest-api-endpoints/license-management.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index 0186f4d9..d5c85b2e 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -9,7 +9,7 @@ For Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documen For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. -Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. +Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. For more details see {ref}`license-management`. ```{note} This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and unavailable for offline deployments. diff --git a/docs/reference/api/rest-api-endpoints/license-management.md b/docs/reference/api/rest-api-endpoints/license-management.md index 52d2d87c..efaa5b0b 100644 --- a/docs/reference/api/rest-api-endpoints/license-management.md +++ b/docs/reference/api/rest-api-endpoints/license-management.md @@ -51,7 +51,7 @@ Example Response: ``` ```{note} -"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist +"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist. This activity is only available for client versions 25.08.3 and newer. ``` ## POST `/detach-token` @@ -108,7 +108,7 @@ Example Response: ``` ```{note} -"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist +"invalid_computer_ids" in the response are for computers that do not accept the proper message type to attach pro (e.g., older client versions) or a computer id that don't exist. This activity is only available for client versions 25.08.3 and newer. ``` ## GET `/legacy-licenses` @@ -121,8 +121,8 @@ Required parameters: Optional parameters: -- available_only: only include licenses that have open seats. -- active_only: only include licenses that are not expired. +- `available_only`: only include licenses that have open seats. +- `active_only`: only include licenses that are not expired. Example Request: @@ -168,7 +168,7 @@ Optional parameters: Path parameters: -- id: license id to get information on +- `id`: license id to get information on Example Request: @@ -196,7 +196,7 @@ Required parameters: Optional parameters: -- None +- `active_only`: only include licenses that are not expired. Example Request: @@ -242,7 +242,7 @@ Optional parameters: Path parameters: -- id: contract to get information on +- `id`: contract id to get information on Example Request: From c812ffcccb10c69a4a59b23a0cd6f91fde4a68f2 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 11:47:18 -0700 Subject: [PATCH 117/187] refactor: update broker config settings (#72) --- docs/reference/config/service-conf.md | 96 +++++++++++++++++++++++---- 1 file changed, 84 insertions(+), 12 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index f3ae5f80..b5dde2ce 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -287,19 +287,91 @@ In practice, only the `base_port` setting needs to be configured for the service ## The `[broker]` section -The `[broker]` section contains configurations that describe how services connect to our message queues. +The `[broker]` section contains configurations that describe how services connect to our AMQP broker (RabbitMQ). -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `host` | - | `LANDSCAPE_BROKER__HOST` | `localhost` | The hostname or IP address of the message broker server. | -| `hostagent_command_status_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_COMMAND_STATUS_QUEUE` | `landscape-server-hostagent-command-status-queue` | Queue for sending command status updates from the hostagent server to the hostagent consumer. | -| `hostagent_ping_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_PING_QUEUE` | `landscape-server-hostagent-ping-queue` | Queue for sending pings from the hostagent server to the hostagent consumer. | -| `hostagent_task_queue` | - | `LANDSCAPE_BROKER__HOSTAGENT_TASK_QUEUE` | `landscape-server-hostagent-task-queue` | Queue for sending tasks from the hostagent consumer to the hostagent server. | -| `hostagent_virtual_host` | - | `LANDSCAPE_BROKER__HOSTAGENT_VIRTUAL_HOST` | `landscape-hostagent` | The virtual host of message queues for the hostagent message server and consumer. This provides support for Landscape integration with Ubuntu Pro for WSL. | -| `password` | - | `LANDSCAPE_BROKER__PASSWORD` | `guest` | Password used to authenticate with the message broker. | -| `port` | - | `LANDSCAPE_BROKER__PORT` | 5672 | Network port where message broker server is listening. | -| `user` | - | `LANDSCAPE_BROKER__USER` | `guest` | Username used to authenticate with the message broker. | -| `vhost` | - | `LANDSCAPE_BROKER__VHOST` | `landscape` | The virtual host namespace. | +### `host` + +- Purpose: The hostname or IP address of the AMQP broker server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__HOST` +- Default: `localhost` + +### `hostagent_command_status_queue` + +- Purpose: Queue for sending command status updates from the hostagent server to the hostagent consumer. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__HOSTAGENT_COMMAND_STATUS_QUEUE` +- Default: `landscape-server-hostagent-command-status-queue` + +### `hostagent_ping_queue` + +- Purpose: Queue for pings from registered Windows instances. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__HOSTAGENT_PING_QUEUE` +- Default: `landscape-server-hostagent-ping-queue` + +### `hostagent_task_queue` + +- Purpose: Queue for messages received from registered Windows instances. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__HOSTAGENT_TASK_QUEUE` +- Default: `landscape-server-hostagent-task-queue` + +### `hostagent_virtual_host` + +- Purpose: The virtual host of message queues for the hostagent message server and consumer. This provides support for Landscape integration with Ubuntu Pro for WSL. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__HOSTAGENT_VIRTUAL_HOST` +- Default: `landscape-hostagent` + +### `password` + +- Purpose: Password used to authenticate with the AMQP broker. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__PASSWORD` +- Default: `guest` + +### `port` + +- Purpose: Network port where the AMQP broker is listening. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__PORT` +- Default: `5672` + +### `ssl_client_cert` + +- Purpose: Path to the client certificate to use for an SSL connection to the AMQP broker. Required along with `ssl_private_key` for mTLS connections. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_CERT` +- Default: `None` + +### `ssl_private_key` + +- Purpose: Path to the private key to use for an SSL connection to the AMQP broker. Required along with `ssl_client_cert` for mTLS connections. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__SSL_PRIVATE_KEY` +- Default: `None` + +### `ssl_ca_cert` + +- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_private_key` and `ssl_server_cert` must also be set. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__SSL_CA_CERT` +- Default: `None` + +### `user` + +- Purpose: Username used to authenticate with the message broker. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__USER` +- Default: `guest` + +### `vhost` + +- Purpose: The virtual host namespace used by most of the Landscape services. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_BROKER__VHOST` +- Default: `landscape` ## The `[job_handler]` section From 61c29eff90c9599fbd7136c417336f42fd164323 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 11:47:32 -0700 Subject: [PATCH 118/187] refactor: update load shaper config settings (#73) --- docs/reference/config/service-conf.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index b5dde2ce..a83e841e 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -395,11 +395,26 @@ The `[load_shaper]` section contains configurations for controlling how many mes The default values have been chosen based on the underlying algorithm and typical workloads. Modifying these values is not advisable unless you have thoroughly tested the impact on your specific system, as changes can significantly affect performance and system stability. ``` -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `critical_load` | `critical-load` | `LANDSCAPE_LOAD_SHAPER__CRITICAL_LOAD` | `10.0` | A float representing the database load threshold at which message processing time is reduced to zero. When load reaches this value, no time slice is allocated for processing. | -| `good_duration` | `good-duration` | `LANDSCAPE_LOAD_SHAPER__GOOD_DURATION` | `60.0` | A float representing the baseline time slice (in seconds) allocated for message processing when the database load is at the good load threshold. This duration is scaled up or down based on current load. | -| `good_load` | `good-load` | `LANDSCAPE_LOAD_SHAPER__GOOD_LOAD` | `3.0` | A float representing the optimal database load threshold. When load is at this value, the full good duration time slice is allocated. Load below this increases the time slice, load above this decreases it. | +### `critical_load` + +- Purpose: A float representing the database load threshold at which message processing time is reduced to zero. When load reaches this value, no time slice is allocated for processing. +- Deprecated key name: `critical-load` +- ENV name: `LANDSCAPE_LOAD_SHAPER__CRITICAL_LOAD` +- Default: `10.0` + +### `good_duration` + +- Purpose: A float representing the baseline time slice (in seconds) allocated for message processing when the database load is at the good load threshold. This duration is scaled up or down based on current load. +- Deprecated key name: `good-duration` +- ENV name: `LANDSCAPE_LOAD_SHAPER__GOOD_DURATION` +- Default: `60.0` + +### `good_load` + +- Purpose: A float representing the optimal database load threshold. When load is at this value, the full good duration time slice is allocated. Load below this increases the time slice, load above this decreases it. +- Deprecated key name: `good-load` +- ENV name: `LANDSCAPE_LOAD_SHAPER__GOOD_LOAD` +- Default: `3.0` ## The `[maintenance]` section From edc35c96a065476ce911c12fa82145d0df050e0f Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 11:55:39 -0700 Subject: [PATCH 119/187] refactor: update appserver config settings (#71) --- docs/reference/config/service-conf.md | 137 +++++++++++++++++++++----- 1 file changed, 111 insertions(+), 26 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index a83e841e..5a07322d 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -233,25 +233,16 @@ The `[landscape]` section name is deprecated. The `[appserver]` section replaces The `[appserver]` section contains configurations for the Landscape application server, including storage paths and authentication providers. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `blob_storage_root` | `blob-storage-root` | `LANDSCAPE_APPSERVER__BLOB_STORAGE_ROOT` | `/var/lib/landscape/blobs` | Root directory for blob storage. | -| `display_consent_banner_at_each_login` | `display-consent-banner-at-each-login` | `LANDSCAPE_APPSERVER__DISPLAY_CONSENT_BANNER_AT_EACH_LOGIN` | `False` | Whether to display consent banner at each login. | -| `juju_homes_path` | `juju-homes-path` | `LANDSCAPE_APPSERVER__JUJU_HOMES_PATH` | `/var/tmp/juju-homes` | Path to Juju home directories. | -| `known_proxies` | `known-proxies` | `LANDSCAPE_APPSERVER__KNOWN_PROXIES` | `None` | Comma-separated names of known proxies. | -| `oidc_client_id` | `oidc-client-id` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_ID` | `None` | OIDC client identifier. Required when using OIDC authentication. | -| `oidc_client_secret` | `oidc-client-secret` | `LANDSCAPE_APPSERVER__OIDC_CLIENT_SECRET` | `None` | OIDC client secret. Required when using OIDC authentication. | -| `oidc_issuer` | `oidc-issuer` | `LANDSCAPE_APPSERVER__OIDC_ISSUER` | `None` | OIDC issuer URL. Required when using OIDC authentication. | -| `oidc_provider` | `oidc-provider` | `LANDSCAPE_APPSERVER__OIDC_PROVIDER` | `unspecified` | The name of OIDC provider to use. Must be either `google`, `okta`, or `unspecified`. | -| `oidc_redirect_uri` | `oidc-redirect-uri` | `LANDSCAPE_APPSERVER__OIDC_REDIRECT_URI` | `None` | OIDC redirect URI for authentication callbacks. | -| `openid_logout_url` | `openid-logout-url` | `LANDSCAPE_APPSERVER__OPENID_LOGOUT_URL` | `None` | OpenID logout URL. Required when using OpenID authentication. | -| `openid_provider_url` | `openid-provider-url` | `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` | `None` | OpenID provider URL. Required when using OpenID authentication. | -| `repository_path` | `repository-path` | `LANDSCAPE_APPSERVER__REPOSITORY_PATH` | `/tmp/landscape-repository` | Path to the package repository. | -| `reprepro_binary` | `reprepro-binary` | `LANDSCAPE_APPSERVER__REPREPRO_BINARY` | `None` | Path to the reprepro binary executable. | -| `sanitize_delay` | `sanitize-delay` | `LANDSCAPE_APPSERVER__SANITIZE_DELAY` | `3600` | Delay in seconds for data sanitization operations. | -| `secret_token` | `secret-token` | `LANDSCAPE_APPSERVER__SECRET_TOKEN` | `None` | Secret token for application security. | -| `ubuntu_images_path` | `ubuntu-images-path` | `LANDSCAPE_APPSERVER__UBUNTU_IMAGES_PATH` | `/var/tmp/ubuntu-images` | Path to Ubuntu images directory. | -| `ubuntu_one_redirect_url` | `ubuntu-one-redirect-url` | `LANDSCAPE_APPSERVER__UBUNTU_ONE_REDIRECT_URL` | `None` | Ubuntu One redirect URL for authentication. | +### Moved Configuration Keys + +The following keys have moved from the `[appserver]` section to the `[system]` section in Landscape 25.10: + +- `enable-password-authentication` → `enable_password_authentication` in `[system]` +- `enable-subdomain-accounts` → `enable_subdomain_accounts` in `[system]` +- `enable-saas-metrics` → `enable_saas_metrics` in `[system]` +- `enable-tag-script-execution` → `enable_tag_script_execution` in `[system]` + +These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape 26.04, when support will be removed and they must be configured in the `[system]` section. ### Authentication providers @@ -264,16 +255,110 @@ OIDC: - Requires `oidc_issuer`, `oidc_client_id`, and `oidc_client_secret` to be configured -### Moved Configuration Keys +### `blob_storage_root` -The following keys have moved from the `[appserver]` section to the `[system]` section in Landscape 25.10: +- Purpose: Root directory for blob storage used for USG reports. +- Deprecated key name: `blob-storage-root` +- ENV name: `LANDSCAPE_APPSERVER__BLOB_STORAGE_ROOT` +- Default: `/var/lib/landscape/blobs` -- `enable-password-authentication` → `enable_password_authentication` in `[system]` -- `enable-subdomain-accounts` → `enable_subdomain_accounts` in `[system]` -- `enable-saas-metrics` → `enable_saas_metrics` in `[system]` -- `enable-tag-script-execution` → `enable_tag_script_execution` in `[system]` +### `display_consent_banner_at_each_login` -These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape 26.04, when support will be removed and they must be configured in the `[system]` section. +- Purpose: This setting should only be enabled in DISA STIG environments. Whether to display consent banner at each login. +- Deprecated key name: `display-consent-banner-at-each-login` +- ENV name: `LANDSCAPE_APPSERVER__DISPLAY_CONSENT_BANNER_AT_EACH_LOGIN` +- Default: `False` + +### `known_proxies` + +- Purpose: Comma-separated names of known proxies to consider when updating an administrator's last login host. +- Deprecated key name: `known-proxies` +- ENV name: `LANDSCAPE_APPSERVER__KNOWN_PROXIES` +- Default: `None` + +### `oidc_client_id` + +- Purpose: OIDC client identifier. Required along with `oidc_client_secret` and `oidc_issuer` when using OIDC authentication. +- Deprecated key name: `oidc-client-id` +- ENV name: `LANDSCAPE_APPSERVER__OIDC_CLIENT_ID` +- Default: `None` + +### `oidc_client_secret` + +- Purpose: OIDC client secret. Required along with `oidc_client_id` and `oidc_issuer` when using OIDC authentication. +- Deprecated key name: `oidc-client-secret` +- ENV name: `LANDSCAPE_APPSERVER__OIDC_CLIENT_SECRET` +- Default: `None` + +### `oidc_issuer` + +- Purpose: OIDC issuer URL. Required along with `oidc_client_secret` and `oidc_client_id` when using OIDC authentication. +- Deprecated key name: `oidc-issuer` +- ENV name: `LANDSCAPE_APPSERVER__OIDC_ISSUER` +- Default: `None` + +### `oidc_provider` + +- Purpose: The name of OIDC provider to use. Must be either `google`, `okta`, or `unspecified`. +- Deprecated key name: `oidc-provider` +- ENV name: `LANDSCAPE_APPSERVER__OIDC_PROVIDER` +- Default: `unspecified` + +### `oidc_redirect_uri` + +- Purpose: OIDC redirect URI for authentication callbacks. +- Deprecated key name: `oidc-redirect-uri` +- ENV name: `LANDSCAPE_APPSERVER__OIDC_REDIRECT_URI` +- Default: `None` + +### `openid_logout_url` + +- Purpose: OpenID logout URL. Required along with `openid_provider_url` when using OpenID authentication. +- Deprecated key name: `openid-logout-url` +- ENV name: `LANDSCAPE_APPSERVER__OPENID_LOGOUT_URL` +- Default: `None` + +### `openid_provider_url` + +- Purpose: OpenID logout URL. Required along with `openid_logout_url` when using OpenID authentication. +- Deprecated key name: `openid-provider-url` +- ENV name: `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` +- Default: `None` + +### `repository_path` + +- Purpose: Path to the package repository directory. The `landscape` system user must have read and write privileges for that directory. +- Deprecated key name: `repository-path` +- ENV name: `LANDSCAPE_APPSERVER__REPOSITORY_PATH` +- Default: `/tmp/landscape-repository` + +### `reprepro_binary` + +- Purpose: Path to the reprepro binary executable. If unset the binary installed at `/usr/bin/reprepro` is used. +- Deprecated key name: `reprepro-binary` +- ENV name: `LANDSCAPE_APPSERVER__REPREPRO_BINARY` +- Default: `None` + +### `sanitize_delay` + +- Purpose: Delay in seconds before a sanitize activity is sent to a registered instance. +- Deprecated key name: `sanitize-delay` +- ENV name: `LANDSCAPE_APPSERVER__SANITIZE_DELAY` +- Default: `3600` + +### `secret_token` + +- Purpose: Secret token used as the secret key for symmetric encryption of JWTs. +- Deprecated key name: `secret-token` +- ENV name: `LANDSCAPE_APPSERVER__SECRET_TOKEN` +- Default: `None` + +### `ubuntu_one_redirect_url` + +- Purpose: Ubuntu One redirect URL for authentication. +- Deprecated key name: `ubuntu-one-redirect-url` +- ENV name: `LANDSCAPE_APPSERVER__UBUNTU_ONE_REDIRECT_URL` +- Default: `None` ## The `[async_frontend]` section From 966d3604f201084ee7e4c291b1879ba0576b1e0d Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 12:08:32 -0700 Subject: [PATCH 120/187] refactor: update message server config settings (#74) --- docs/reference/config/service-conf.md | 48 +++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 5a07322d..310b938b 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -517,13 +517,47 @@ The `[backoff]` section is deprecated. The settings have been moved to the `[mes The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `backoff_dir` | `backoff-dirpath` | `LANDSCAPE_MESSAGE_SERVER__BACKOFF_DIR` | `None` | The directory to hold the `backoff.txt` file the server uses to indicate it should back off requests. If `None`, a `config` directory within the `landscape` directory will be used. | -| `max_msg_size_bytes` | `max-msg-size-bytes` | `LANDSCAPE_MESSAGE_SERVER__MAX_MSG_SIZE_BYTES` | 30000000 (30 MB) | The maximum size, in bytes, of a message from Landscape Client that Landscape Server will accept. Messages larger than this size will be rejected. | -| `message_snippet_bytes` | `message-snippet-bytes` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SNIPPET_BYTES` | 1000 | When Landscape Server receives a message larger than `max_msg_size_bytes`, it will log an error including the first `message_snippet_bytes` of the message. | -| `message_system_url` | - | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` | `None` | The message system URL to use. | -| `ping_interval` | `ping-interval` | `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` | `None` | Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. | +### `backoff_dir` + +- Purpose: The directory to hold the `backoff.txt` file the server uses to indicate it should back off requests. If `None`, a `config` directory within the `landscape` directory will be used. +- Deprecated key name: `backoff-dirpath` +- ENV name: `LANDSCAPE_MESSAGE_SERVER__BACKOFF_DIR` +- Default: `None` + +### `check_interval` + +- Purpose: The interval in seconds at which to update knowledge of computers with outstanding messages from the database. +- Deprecated key name: `check-interval` +- ENV name: `LANDSCAPE_MESSAGE_SERVER__CHECK_INTERVAL` +- Default: `1200` + +### `max_msg_size_bytes` + +- Purpose: The maximum size, in bytes, of a message from Landscape Client that Landscape Server will accept. Messages larger than this size will be rejected. +- Deprecated key name: `max-msg-size-bytes` +- ENV name: `LANDSCAPE_MESSAGE_SERVER__MAX_MSG_SIZE_BYTES` +- Default: `30000000` (30MB) + +### `message_snippet_bytes` + +- Purpose: When Landscape Server receives a message larger than `max_msg_size_bytes`, it will log an error including the first `message_snippet_bytes` of the message. +- Deprecated key name: `message-snippet-bytes` +- ENV name: `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SNIPPET_BYTES` +- Default: `1000` + +### `message_system_url` + +- Purpose: The message system URL to use. If not set, the system root url appended with `/message-system` is used. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_MESSAGE_SERVER__MESSAGE_SYSTEM_URL` +- Default: `None` + +### `ping_interval` + +- Purpose: Landscape Server will instruct Landscape Client to send a ping message every `ping_interval` seconds. If unset, each registered client will use the value set in its own Landscape Client configuration. +- Deprecated key name: `ping-interval` +- ENV name: `LANDSCAPE_MESSAGE_SERVER__PING_INTERVAL` +- Default: `None` ## The `[oops]` section From 747d1f1ccc12d3fd26a76e9c7cffb448819e8060 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 13:35:39 -0700 Subject: [PATCH 121/187] refactor: update package upload settings (#76) --- docs/reference/config/service-conf.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 310b938b..1e5d4088 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -581,10 +581,19 @@ The `[package-upload]` section name is deprecated. The `[package_upload]` sectio The `[package_upload]` section contains configurations for the package upload service, including service connection settings, database store configurations, and SSL options. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `port` | - | `LANDSCAPE_PACKAGE_UPLOAD__PORT` | `None` | The port the service will use. This field is required. | -| `service_path` | `root-url` | `LANDSCAPE_PACKAGE_UPLOAD__SERVICE_PATH` | `/upload/` | The relative path portion to use for the service URL. | +### `base_port` + +- Purpose: Workers for the service will run on ports incrementing from this base port. +- Deprecated key names: `port`, `base-port` +- ENV name: `LANDSCAPE_PACKAGE_UPLOAD__BASE_PORT` +- Default: `9100` + +### `service_path` + +- Purpose: The relative path portion to use for the service URL. +- Deprecated key name: `root-url` +- ENV name: `LANDSCAPE_PACKAGE_UPLOAD__SERVICE_PATH` +- Default: `/upload/` ## The `[scripts]` section From cf44dcd6855fe200a43e35ebe32c497d9dfba93f Mon Sep 17 00:00:00 2001 From: david-mclain Date: Mon, 22 Sep 2025 15:45:54 -0500 Subject: [PATCH 122/187] document licensing --- docs/explanation/landscape/licenses.md | 34 +++++++++++++++++-- .../api/rest-api-endpoints/computers.md | 4 +-- docs/what-is-landscape.md | 6 ++++ 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index d5c85b2e..d8e2409c 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -7,15 +7,34 @@ For self-hosted Landscape accounts, users running version 23.03 or newer typical For Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documentation.ubuntu.com/pro/), the [Pro Client documentation](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/) and {ref}`how-to-attach-ubuntu-pro` to learn more. +## License.txt Method + For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. -Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. For more details see {ref}`license-management`. +```{tip} +New `license.txt` files become available on their start date. For renewal customers, this is the day after your old licences expire. +``` + +## Pro Client Method + +For the Pro Client Method customers running Landscape version 23.03 or newer and landscape-client version 23.03 or newer you can use this method. + +1. Ensure the Pro client is installed and attached to your Pro token on the system you wish to register to Landscape. See {ref}`how-to-attach-ubuntu-pro` for more details. + +2. Then enable Landscape to initiate the registration process. See {ref}`how-to-ubuntu-pro-enable-landscape`. + +3. Landscape will detect your Pro entitlement via the Pro token and create a licence for your machine. + + +## Ubuntu Pro Licensing Method + +Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer. For more details see {ref}`license-management`. ```{note} -This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and unavailable for offline deployments. +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments. ``` -## License type +## Legacy License types You can view the number of seats used per license type for each computer in the classic web portal. This functionality is in the **Licenses** tab. @@ -29,3 +48,12 @@ Here’s a summary of the different license types in Landscape and what they ind * These don't require the `license.txt` file to be installed or have available seats on the Landscape server * Requires `landscape-client` 23.x or higher to report the Pro attachment information to the Landscape server +## License types for Ubuntu Pro Licensing +- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management. +- **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. +- **Pro:** Computers that are licensed through Ubuntu Pro. +- **Legacy:** Computers that are licensed through a `license.txt` file. + +```{note} +A max of 5 Free Pro client machines are allowed per account or deployment. +``` \ No newline at end of file diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 80a9f7d1..3b04a795 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -32,8 +32,8 @@ Query parameters: - `profile:wsl::`: Instances associated with the specified WSL Child Instance Profile. The `` is the database id of the profile. The `` must either be `compliant` or `noncompliant`. - `OR`: Search for computers matching term A or term B. The text `OR` must be in all-caps. - `NOT`: search for computers not matching the next term. The text `NOT` must be in all-caps. - - `license-type:`: Instances associated with the specified <`license-type`>. The `license-type` must be one of `unlicensed`, `pro`, `free_pro`, `legacy`. - - `contract:`: Instances associated with the specified <`contract-id>`. + - `license-type:`: Instances associated with the specified ``. The `license-type` must be one of `unlicensed`, `pro`, `free_pro`, `legacy`. + - `contract:`: Instances associated with the specified ``. - `contract-expires-within-days:`: Instances associated with a Ubuntu Pro contract that expires within `` days. - `license-expires-within-days:`: Instances associated with a Legacy License that expires within `` days. - `limit`: The maximum number of results returned by the method. It defaults to 1000. diff --git a/docs/what-is-landscape.md b/docs/what-is-landscape.md index 29be7125..32ae0c34 100644 --- a/docs/what-is-landscape.md +++ b/docs/what-is-landscape.md @@ -72,3 +72,9 @@ For self-hosted installations, there are multiple ways to install Landscape Serv For more details on self-hosted Landscape installations, see our {ref}`explanation-about-self-hosted` page. Organizations interested in using self-hosted Landscape at enterprise-scale should [contact Canonical Sales](https://ubuntu.com/landscape#get-in-touch). + +## Useful Links + +- [Knowledge Base - Landscape Section](https://support-portal.canonical.com/knowledge-base?topic=Landscape): content published by Canonical Support, typically addressing FAQs and providing workarounds for bugs + +- [GitHub - script repository for Landscape](https://github.com/canonical/landscape-scripts): a collection of scripts to make Landscape more powerful. From 541fe952827d61cfc445c8db8addb1fb451c9463 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Mon, 22 Sep 2025 15:49:40 -0500 Subject: [PATCH 123/187] include snap/core mention --- docs/explanation/landscape/licenses.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index d8e2409c..5016af9a 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -31,7 +31,7 @@ For the Pro Client Method customers running Landscape version 23.03 or newer and Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer. For more details see {ref}`license-management`. ```{note} -This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments. +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. ``` ## Legacy License types From 5e46f4695bfbc8b496502fed7d2ad5fce4d8380d Mon Sep 17 00:00:00 2001 From: david-mclain Date: Mon, 22 Sep 2025 16:04:50 -0500 Subject: [PATCH 124/187] spelling error --- docs/explanation/landscape/licenses.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index 5016af9a..f8aafd66 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -12,7 +12,7 @@ For Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documen For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. ```{tip} -New `license.txt` files become available on their start date. For renewal customers, this is the day after your old licences expire. +New `license.txt` files become available on their start date. For renewal customers, this is the day after your old licenses expire. ``` ## Pro Client Method @@ -23,7 +23,7 @@ For the Pro Client Method customers running Landscape version 23.03 or newer and 2. Then enable Landscape to initiate the registration process. See {ref}`how-to-ubuntu-pro-enable-landscape`. -3. Landscape will detect your Pro entitlement via the Pro token and create a licence for your machine. +3. Landscape will detect your Pro entitlement via the Pro token and create a license for your machine. ## Ubuntu Pro Licensing Method From 7f444a64c57f087d9f9c85d980af03f9996c0305 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 14:05:11 -0700 Subject: [PATCH 125/187] refactor: update oops settings (#75) --- docs/reference/config/service-conf.md | 29 ++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 1e5d4088..6e898474 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -563,13 +563,28 @@ The `[message_server]` section contains configurations that apply to the `landsc The `[oops]` section contains configurations for the OOPS error reporting and debugging system used for logging and traceback collection. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `amqp_exchange` | `amqp-exchange` | `LANDSCAPE_OOPS__AMQP_EXCHANGE` | `None` | AMQP exchange name for error reporting. | -| `amqp_key` | `amqp-key` | `LANDSCAPE_OOPS__AMQP_KEY` | `None` | AMQP routing key for error messages. Requires `amqp_exchange` to be set. | -| `directory` | - | `LANDSCAPE_OOPS__DIRECTORY` | `None` | Directory path for OOPS error report storage. | -| `path` | - | `LANDSCAPE_OOPS__PATH` | `None` | File path for OOPS configuration. | -| `reporter` | - | `LANDSCAPE_OOPS__REPORTER` | `None` | Error reporter configuration. | +### `amqp_exchange` + +- Purpose: AMQP exchange name for error reporting. +- Deprecated key name: `amqp-exchange` +- ENV name: `LANDSCAPE_OOPS__AMQP_EXCHANGE` +- Default: `""` + +### `amqp_key` + +- Purpose: AMQP routing key for error messages. Requires `amqp_exchange` to be set. +- Deprecated key name: `amqp-key` +- ENV name: `LANDSCAPE_OOPS__AMQP_KEY` +- Default: `landscape-oops` + +### `path` + +- Purpose: File path for local OOPS publishing. If set, overrides the value set by `LANDSCAPE_SYSTEM__OOPS_PATH`. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_OOPS__PATH` +- Default: `None` + +## The `[schema]` section The `[schema]` section contains configurations for updating the database schema. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. From fb2c632eb328bd48ada4df5c488dd85d299630ac Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 16:05:38 -0700 Subject: [PATCH 126/187] refactor: update secrets settings (#77) refactor: fix secrets settings --- docs/reference/config/service-conf.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 6e898474..e29c49de 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -618,11 +618,26 @@ The `[scripts]` section contains configurations for scripts. The section contain The `[secrets]` section contains configurations for the secrets service, such as vault connection settings. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `service_url` | `secrets-service-url` | `LANDSCAPE_SECRETS__SERVICE_URL` | `None` | The URL to use for the secrets service. Must include a port. | -| `vault_token` | - | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `None` | The token to use for the vault instead of getting it from the secrets service. | -| `vault_url` | `secrets-url` | `LANDSCAPE_SECRETS__VAULT_URL` | `http://localhost:8200` | The address of the vault to use for the secrets service. | +### `service_url` + +- Purpose: The URL to use for the secrets service. Must include a port. +- Deprecated key name: `secrets-service-url` +- ENV name: `LANDSCAPE_SECRETS__SERVICE_URL` +- Default: `None` + +### `vault_token` + +- Purpose: The token to use for the vault instead of getting it from the secrets service. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECRETS__VAULT_TOKEN` +- Default: `None` + +### `vault_url` + +- Purpose: The address of the vault to use for the secrets service. +- Deprecated key name: `secrets-url` +- ENV name: `LANDSCAPE_SECRETS__VAULT_URL` +- Default: `http://localhost:8200` ## The `[stores]` section From 4fd666549f18bafcb1fc964940963a383cefd409 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 16:09:55 -0700 Subject: [PATCH 127/187] refactor: update stores settings (#78) --- docs/reference/config/service-conf.md | 97 +++++++++++++++++++++++---- 1 file changed, 83 insertions(+), 14 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index e29c49de..403584e4 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -643,20 +643,89 @@ The `[secrets]` section contains configurations for the secrets service, such as The `[stores]` section contains configurations for database store names and connections. In addition, the this section can use the {ref}`shared store settings `. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `account_1` | `account-1` | `LANDSCAPE_STORES__ACCOUNT_1` | `landscape-standalone-account-1` | The first account database store name. | -| `account_2` | `account-2` | `LANDSCAPE_STORES__ACCOUNT_2` | `None` | The second account database store name. Optional. | -| `host` | - | `LANDSCAPE_STORES__HOST` | `localhost` | The hostname or IP address of the database server. | -| `knowledge` | - | `LANDSCAPE_STORES__KNOWLEDGE` | `landscape-standalone-knowledge` | The knowledge database name. | -| `main` | - | `LANDSCAPE_STORES__MAIN` | `landscape-standalone-main` | The main database name. | -| `package` | - | `LANDSCAPE_STORES__PACKAGE` | `landscape-standalone-package` | The package database name. | -| `password` | - | `LANDSCAPE_STORES__PASSWORD` | `None` | The password for database connections. | -| `resource_1` | `resource-1` | `LANDSCAPE_STORES__RESOURCE_1` | `landscape-standalone-resource-1` | The first resource database name. | -| `resource_2` | `resource-2` | `LANDSCAPE_STORES__RESOURCE_2` | `None` | The second resource database name. Optional and used for testing only. | -| `session` | - | `LANDSCAPE_STORES__SESSION` | `landscape-standalone-session` | The session database name. | -| `session_autocommit` | `session-autocommit` | `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` | `landscape-standalone-session` | The name of the session database with {spellexception}`autocommit` isolation. | -| `user` | - | `LANDSCAPE_STORES__USER` | `landscape` | The username for database connections. | +### `account_1` + +- Purpose: The account database store name. +- Deprecated key name: `account-1` +- ENV name: `LANDSCAPE_STORES__ACCOUNT_1` +- Default: `landscape-standalone-account-1` + +### `account_2` + +- Purpose: The second account database store name. In practice this settings should be left unset as it is used only by tests. +- Deprecated key name: `account-2` +- ENV name: `LANDSCAPE_STORES__ACCOUNT_2` +- Default: `None` + +### `host` + +- Purpose: The hostname or IP address of the database server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__HOST` +- Default: `localhost` + +### `knowledge` + +- Purpose: The knowledge database name. The knowledge database is deprecated and will be dropped in a future release of Landscape Server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__KNOWLEDGE` +- Default: `landscape-standalone-knowledge` + +### `main` + +- Purpose: The main database name. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__MAIN` +- Default: `landscape-standalone-main` + +### `package` + +- Purpose: The package database name. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__PACKAGE` +- Default: `landscape-standalone-package` + +### `password` + +- Purpose: The password for database connections by the configured `user`. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__PASSWORD` +- Default: `None` + +### `resource_1` + +- Purpose: The resource database name. +- Deprecated key name: `resource-1` +- ENV name: `LANDSCAPE_STORES__RESOURCE_1` +- Default: `landscape-standalone-resource-1` + +### `resource_2` + +- Purpose: The second resource database name. In practice this settings should be left unset as it is used only by tests. +- Deprecated key name: `resource-2` +- ENV name: `LANDSCAPE_STORES__RESOURCE_2` +- Default: `None` + +### `session` + +- Purpose: The session database name. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_STORES__SESSION` +- Default: `landscape-standalone-session` + +### `session_autocommit` + +- Purpose: The name of the session database with `autocommit` isolation. +- Deprecated key name: `session-autocommit` +- ENV name: `LANDSCAPE_STORES__SESSION_AUTOCOMMIT` +- Default: `landscape-standalone-session` + +### `user` + +- Purpose: The username for database connections. +- Deprecated key name: `session-autocommit` +- ENV name: `LANDSCAPE_STORES__USER` +- Default: `landscape` ## The `[system]` section From 30819c38a29b7d432d1ffc7ce103112dd60f5902 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Mon, 22 Sep 2025 16:33:20 -0700 Subject: [PATCH 128/187] refactor: update system settings (#79) --- docs/.custom_wordlist.txt | 1 + docs/reference/config/service-conf.md | 148 ++++++++++++++++++++++---- 2 files changed, 128 insertions(+), 21 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index e6b0d6d7..4326d21e 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -156,6 +156,7 @@ MAAS maas Mailjet ManualInstallation +mebibytes microSD middleware milli diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 403584e4..9a6d6dc1 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -735,24 +735,130 @@ The `[global]` section name is deprecated. The `[system]` section replaces the ` The `[system]` section contains configurations that apply across many or all of Landscape's services. -| Key name | Deprecated key name | ENV name | Default | Purpose | -| :------- | :------------------ | :------- | :------ | :------ | -| `analytics_id` | - | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | -| `apt_port` | - | `LANDSCAPE_SYSTEM__APT_PORT` | 8085 | The port the `landscape_apt` service should use. | -| `audit_retention_period` | `audit-retention-period` | `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` | `-1` | The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. | -| `deployment_mode` | `deployment-mode` | `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` | `standalone` | Used only for development. The default value is appropriate for self-hosted Landscape. | -| `enable_password_authentication` | - | `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` | `False` | Whether to enable password-based authentication or not. | -| `enable_query_debug` | - | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `False` | Whether to enable query introspection and debugging middleware or not. | -| `enable_saas_metrics` | - | `LANDSCAPE_SYSTEM__ENABLE_SAAS_METRICS` | `False` | Whether to enable metrics on SaaS or not. | -| `enable_subdomain_accounts` | - | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `False` | Whether to enable subdomain accounts or not. | -| `enable_tag_script_execution` | - | `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` | `False` | Whether to enable tag-based script execution or not. | -| `fqdn` | - | `LANDSCAPE_SYSTEM__FQDN` | `None` | Sets the root URL using the FQDN. | -| `gpg_home_dir` | - | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the keyrings. | -| `license_file` | - | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `/etc/landscape/license.txt` | The file path location of the license file. | -| {spellexception}`pidfile_directory` | {spellexception}`pidfile-directory` | {spellexception}`LANDSCAPE_SYSTEM__PIDFILE_DIRECTORY` | `/tmp/landscape` | Unused | -| `max_service_memory` | `max-service-memory` | `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` | `0` | An upper limit (in {spellexception}`mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. | -| `middleware` | - | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | -| `offline` | - | `LANDSCAPE_SYSTEM__OFFLINE` | `None` | Set `True` if Landscape is deployed in an air-gapped environment. | -| `oops_path` | `oops-path` | `LANDSCAPE_SYSTEM__OOPS_PATH` | `/var/lib/landscape/landscape-oops` | The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. | -| `root_url` | `root-url` | `LANDSCAPE_SYSTEM__ROOT_URL` | `http://localhost:8080` | Landscape Server's root URL path. | -| `syslog_address` | `syslog-address` | `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` | `/dev/log` | Path to the system's syslog logger. | +### `analytics_id` + +- Purpose: Google Analytics tracker ID for the deployment. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ANALYTICS_ID` +- Default: `UA-1018242-60` + +### `apt_port` + +- Purpose: The port the `landscape_apt` service should use. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__APT_PORT` +- Default: `8085` + +### `audit_retention_period` + +- Purpose: The time period in days to retain security profile audit records. A negative value means that records should be retained indefinitely. +- Deprecated key name: `audit-retention-period` +- ENV name: `LANDSCAPE_SYSTEM__AUDIT_RETENTION_PERIOD` +- Default: `-1` + +### `deployment_mode` + +- Purpose: Used only for development. The default value is appropriate for self-hosted Landscape Server. +- Deprecated key name: `deployment-mode` +- ENV name: `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` +- Default: `standalone` + +### `enable_password_authentication` + +- Purpose: Whether to enable password-based authentication or not. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` +- Default: `False` + +### `enable_query_debug` + +- Purpose: Whether to enable query introspection and debugging middleware or not. The default value is appropriate for self-hosted Landscape Server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` +- Default: `False` + +### `enable_saas_metrics` + +- Purpose: Whether to enable metrics on SaaS or not. The default value is appropriate for self-hosted Landscape Server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ENABLE_SAAS_METRICS` +- Default: `False` + +### `enable_subdomain_accounts` + +- Purpose: Whether to enable subdomain accounts or not. The default value is appropriate for self-hosted Landscape Server. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` +- Default: `False` + +### `enable_tag_script_execution` + +- Purpose: Whether to enable tag-based script execution or not. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` +- Default: `False` + +### `gpg_home_dir` + +- Purpose: The directory containing GnuPG config files and the keyrings. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__GPG_HOME_DIR` +- Default: `/var/lib/landscape-server/gnupg` + +### `license_file` + +- Purpose: The file path location of the license file. The `landscape` system user must be able to read this file. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__LICENSE_FILE` +- Default: `/etc/landscape/license.txt` + +### `max_service_memory` + +- Purpose: An upper limit (in `mebibytes`) for the memory usage by a Landscape service. Services exceeding this limit will restart. A value of `0` means there is no limit. +- Deprecated key name: `max-service-memory` +- ENV name: `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` +- Default: `0` + +### `middleware` + +- Purpose: The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. This setting should remain unset in production environments. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__MIDDLEWARE` +- Default: `None` + +### `offline` + +- Purpose: Set `True` if Landscape is deployed in an air-gapped environment. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SYSTEM__OFFLINE` +- Default: `None` + +### `oops_path` + +- Purpose: The directory where OOPS reports are stored. The `landscape` system user must have read/write access to the specified directory. +- Deprecated key name: `oops-path` +- ENV name: `LANDSCAPE_SYSTEM__OOPS_PATH` +- Default: `/var/lib/landscape/landscape-oops` + +### `root_url` + +- Purpose: Landscape Server's root URL path. +- Deprecated key name: `root-url` +- ENV name: `LANDSCAPE_SYSTEM__ROOT_URL` +- Default: `http://localhost:8080` + +### `syslog_address` + +- Purpose: Path to the system's syslog logger. +- Deprecated key name: `syslog-address` +- ENV name: `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` +- Default: `/dev/log` + + From 81979eed0f74f41e24d49f695946899af153d0a8 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Wed, 24 Sep 2025 18:37:54 -0500 Subject: [PATCH 129/187] address feedback for the most part --- docs/explanation/landscape/licenses.md | 29 +++++------ .../rest-api-endpoints/license-management.md | 48 ++++++++----------- docs/what-is-landscape.md | 4 +- 3 files changed, 34 insertions(+), 47 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index f8aafd66..55870f46 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -1,30 +1,27 @@ (explanation-licenses)= # Landscape licenses -Most Landscape accounts have a licensing mechanism; either Ubuntu Pro or a `license.txt` file. For Landscape SaaS accounts, the Ubuntu Pro license is already included in your subscription. +Landscape's main licensing mechanism is Ubuntu Pro. For Landscape SaaS accounts, the Ubuntu Pro license is already included in your subscription. You can also get a free Landscape SaaS account with Ubuntu Pro, which allows you to manage up to 5 machines for free. Most self-hosted Landscape accounts also use Ubuntu Pro. -For self-hosted Landscape accounts, users running version 23.03 or newer typically have Ubuntu Pro subscriptions. Users with older versions (or offline deployments) may use our older licensing mechanism. This older method involves manually downloading a `license.txt` file and applying it during the configuration process. +For more information on Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documentation.ubuntu.com/pro/), the [Ubuntu Pro Client documentation](https://documentation.ubuntu.com/pro-client/en/latest/) and {ref}`how-to-attach-ubuntu-pro`. The Ubuntu Pro Client is a command-line tool that helps you manage your Ubuntu Pro subscription. -For Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documentation.ubuntu.com/pro/), the [Pro Client documentation](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/) and {ref}`how-to-attach-ubuntu-pro` to learn more. +Users with older versions of Landscape (or offline deployments) may use our legacy licensing mechanism. This older method involves manually downloading a `license.txt` file and applying it during the configuration process. -## License.txt Method +## Ubuntu Pro subscription -For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. - -```{tip} -New `license.txt` files become available on their start date. For renewal customers, this is the day after your old licenses expire. -``` +To use Ubuntu Pro with Landscape, you must be running Landscape Server version 23.03 or newer, and Landscape Client version 23.03 or newer. We have the following guides to help you get started: -## Pro Client Method +1. {ref}`how-to-attach-ubuntu-pro` -For the Pro Client Method customers running Landscape version 23.03 or newer and landscape-client version 23.03 or newer you can use this method. +2. {ref}`how-to-ubuntu-pro-enable-landscape` -1. Ensure the Pro client is installed and attached to your Pro token on the system you wish to register to Landscape. See {ref}`how-to-attach-ubuntu-pro` for more details. +After you've enabled Landscape, Landscape will detect your Pro entitlement via the Pro token and create a license for your machine. -2. Then enable Landscape to initiate the registration process. See {ref}`how-to-ubuntu-pro-enable-landscape`. +## License.txt method -3. Landscape will detect your Pro entitlement via the Pro token and create a license for your machine. +For the `license.txt` method, you get your first `license.txt` file from Canonical and manually upload the file to your server: `/etc/landscape/license.txt`. You’ll need to re-upload your license every time you renew, but you can download your new license in your Landscape account from `https://landscape.canonical.com/account//self-hosted`. +Note that new `license.txt` files become available on their start date. For renewal customers, the start date is the day after your old licenses expire. ## Ubuntu Pro Licensing Method @@ -34,9 +31,9 @@ Along with the `license.txt` method and Ubuntu Pro subscription, Landscape intro This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. ``` -## Legacy License types +## License types (classic web portal) -You can view the number of seats used per license type for each computer in the classic web portal. This functionality is in the **Licenses** tab. +In the classic web portal, you can view the number of seats used per license type for each computer from the **Licenses** tab. Here’s a summary of the different license types in Landscape and what they indicate: diff --git a/docs/reference/api/rest-api-endpoints/license-management.md b/docs/reference/api/rest-api-endpoints/license-management.md index efaa5b0b..9b96a373 100644 --- a/docs/reference/api/rest-api-endpoints/license-management.md +++ b/docs/reference/api/rest-api-endpoints/license-management.md @@ -1,4 +1,4 @@ -(license-management)= +(reference-rest-api-license-management)= # License Management ## POST `/attach-token` @@ -14,17 +14,17 @@ Optional parameters: - None -Example Request: +Example request: ```bash -curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2, 3, 4], "token": ""}' +curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2], "token": ""}' ``` -Example Response: +Example response: ```json { "activity": { - "activity_status": "undelivered", + "activity_status": "queued", "approval_time": null, "completion_time": null, "creation_time": "2025-09-19T14:24:07Z", @@ -41,12 +41,7 @@ Example Response: "summary": "Attach a pro token to computers", "type": "ActivityGroup" }, - "invalid_computer_ids": [ - 3, - 4, - 5, - 6 - ] + "invalid_computer_ids": [] } ``` @@ -70,18 +65,18 @@ Optional parameters: - None -Example Request: +Example request: ```bash -curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2, 3, 4]}' +curl -X POST https://your-landscape-domain.com/api/v2/attach-token -H "Authorization: Bearer $JWT" -d '{"computer_ids": [1, 2]}' ``` -Example Response: +Example response: ```json { "activity": { - "activity_status": "undelivered", + "activity_status": "queued", "approval_time": null, "completion_time": null, "creation_time": "2025-09-19T14:28:32Z", @@ -98,12 +93,7 @@ Example Response: "summary": "Detach pro token from computers", "type": "ActivityGroup" }, - "invalid_computer_ids": [ - 3, - 4, - 5, - 6 - ] + "invalid_computer_ids": [] } ``` @@ -124,13 +114,13 @@ Optional parameters: - `available_only`: only include licenses that have open seats. - `active_only`: only include licenses that are not expired. -Example Request: +Example request: ```bash curl -X GET https://your-landscape-domain.com/api/v2/legacy-licenses -H "Authorization: Bearer $JWT" ``` -Example Response: +Example response: ```json { @@ -170,13 +160,13 @@ Path parameters: - `id`: license id to get information on -Example Request: +Example request: ```bash curl -X GET https://your-landscape-domain.com/api/v2/legacy-licenses/8 -H "Authorization: Bearer $JWT" ``` -Example Response: +Example response: ```json { @@ -198,13 +188,13 @@ Optional parameters: - `active_only`: only include licenses that are not expired. -Example Request: +Example request: ```bash curl -X GET https://your-landscape-domain.com/api/v2/contracts -H "Authorization: Bearer $JWT" ``` -Example Response: +Example response: ```json { @@ -244,13 +234,13 @@ Path parameters: - `id`: contract id to get information on -Example Request: +Example request: ```bash curl -X GET https://your-landscape-domain.com/api/v2/contracts/contract-id-1 -H "Authorization: Bearer $JWT" ``` -Example Response: +Example response: ```json { diff --git a/docs/what-is-landscape.md b/docs/what-is-landscape.md index 32ae0c34..c86f3f9e 100644 --- a/docs/what-is-landscape.md +++ b/docs/what-is-landscape.md @@ -75,6 +75,6 @@ For more details on self-hosted Landscape installations, see our {ref}`explanati ## Useful Links -- [Knowledge Base - Landscape Section](https://support-portal.canonical.com/knowledge-base?topic=Landscape): content published by Canonical Support, typically addressing FAQs and providing workarounds for bugs +- [Knowledge Base - Landscape Section](https://support-portal.canonical.com/knowledge-base?topic=Landscape): Content published by Canonical Support, typically addressing FAQs and providing workarounds for bugs. You need to have a Support contract to access this content. -- [GitHub - script repository for Landscape](https://github.com/canonical/landscape-scripts): a collection of scripts to make Landscape more powerful. +- [GitHub - script repository for Landscape](https://github.com/canonical/landscape-scripts): A collection of scripts to make Landscape more powerful. From 4723ff1438dbf785cb042cf2c874d848bc4366eb Mon Sep 17 00:00:00 2001 From: david-mclain Date: Wed, 24 Sep 2025 18:45:00 -0500 Subject: [PATCH 130/187] fix ref and hyperlink --- docs/explanation/landscape/licenses.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index 55870f46..6f3ce5de 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -1,7 +1,7 @@ (explanation-licenses)= # Landscape licenses -Landscape's main licensing mechanism is Ubuntu Pro. For Landscape SaaS accounts, the Ubuntu Pro license is already included in your subscription. You can also get a free Landscape SaaS account with Ubuntu Pro, which allows you to manage up to 5 machines for free. Most self-hosted Landscape accounts also use Ubuntu Pro. +Landscape's main licensing mechanism is [Ubuntu Pro](https://ubuntu.com/pro). For Landscape SaaS accounts, the Ubuntu Pro license is already included in your subscription. You can also get a free Landscape SaaS account with Ubuntu Pro, which allows you to manage up to 5 machines for free. Most self-hosted Landscape accounts also use Ubuntu Pro. For more information on Ubuntu Pro subscriptions, see the [Ubuntu Pro documentation](https://documentation.ubuntu.com/pro/), the [Ubuntu Pro Client documentation](https://documentation.ubuntu.com/pro-client/en/latest/) and {ref}`how-to-attach-ubuntu-pro`. The Ubuntu Pro Client is a command-line tool that helps you manage your Ubuntu Pro subscription. @@ -25,7 +25,7 @@ Note that new `license.txt` files become available on their start date. For rene ## Ubuntu Pro Licensing Method -Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer. For more details see {ref}`license-management`. +Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer. For more details see {ref}`reference-rest-api-license-management`. ```{note} This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. From 69d592d92a1b14470937897df1d59ff77269bd90 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Fri, 26 Sep 2025 16:42:59 -0500 Subject: [PATCH 131/187] fix docs --- docs/explanation/landscape/licenses.md | 25 ++++++++----------- .../ubuntu-pro/attach-ubuntu-pro.md | 23 +++++++++++++++-- 2 files changed, 32 insertions(+), 16 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index 6f3ce5de..7309e815 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -23,14 +23,6 @@ For the `license.txt` method, you get your first `license.txt` file from Canonic Note that new `license.txt` files become available on their start date. For renewal customers, the start date is the day after your old licenses expire. -## Ubuntu Pro Licensing Method - -Along with the `license.txt` method and Ubuntu Pro subscription, Landscape introduced a feature to accept clients without any valid licensing available in versions `25.10x` or newer. This will place clients into an `unlicensed` state where they are unable to be managed however, you can run an activity on the client to attach a Pro token, in turn licensing the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer. For more details see {ref}`reference-rest-api-license-management`. - -```{note} -This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. -``` - ## License types (classic web portal) In the classic web portal, you can view the number of seats used per license type for each computer from the **Licenses** tab. @@ -45,12 +37,17 @@ Here’s a summary of the different license types in Landscape and what they ind * These don't require the `license.txt` file to be installed or have available seats on the Landscape server * Requires `landscape-client` 23.x or higher to report the Pro attachment information to the Landscape server -## License types for Ubuntu Pro Licensing -- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management. +## New licensing states + +For Landscape Server versions `25.10x` or greater there will be new licensing states. These states will allow for a user to register a client with Landscape without having any proper licensing mechanisms (e.g., Ubuntu Pro and `license.txt`). In this new unlicensed state client machine management will be limited, only allowing for operations to license that instance. This will allow for users to register client machines with Landscape, then attach Ubuntu Pro to desired client machines without needing to perform operation on each individual instance. + +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. +``` + +### Client states + +- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management operations. - **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. - **Pro:** Computers that are licensed through Ubuntu Pro. - **Legacy:** Computers that are licensed through a `license.txt` file. - -```{note} -A max of 5 Free Pro client machines are allowed per account or deployment. -``` \ No newline at end of file diff --git a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md index 50fddc78..7e899c66 100644 --- a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md +++ b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md @@ -11,7 +11,9 @@ The following instructions explain how to attach your Ubuntu Pro subscription to Ubuntu Pro isn't just for enterprise customers. Anyone can get [a personal Ubuntu Pro subscription](https://ubuntu.com/pro) for free on up to 5 machines, or 50 if you are an [official Ubuntu Community member](https://wiki.ubuntu.com/Membership). ``` -## Step 1: Install the Ubuntu Pro Client +## Manual attachment + +### Step 1: Install the Ubuntu Pro Client ```{note} You must be running Landscape Server 23.03 or above and Landscape Client 23.02 or above to use the Ubuntu Pro Client to attach your Pro subscription to Landscape. @@ -27,7 +29,7 @@ sudo apt update && sudo apt install ubuntu-advantage-tools If you already have `ubuntu-advantage-tools` installed, this install command will upgrade the package to the latest version. -## Step 2: Attach your subscription +### Step 2: Attach your subscription To attach your machine to a subscription, run the following command in your terminal: @@ -75,6 +77,23 @@ When the machine has successfully been attached, you will also see a summary of Available services can be enabled or disabled on the command line with `pro enable ` and `pro disable ` after you have attached. +## Through Landscape Server + +### Ubuntu Pro licensing method + +Outside of manually attaching Pro to a client machine, Landscape introduced a feature to attach Pro to client machines at scale. To do this navigate to `Pro Services` on the `instances` page and select attach pro. This will create an activity on the client machines to attach a pro token and when it succeeds it will properly license the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer and is not limited to unlicensed instances. For more details see {ref}`reference-rest-api-license-management`. + +```{note} +This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. +``` + +### Licensing states for clients + +- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management. +- **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. +- **Pro:** Computers that are licensed through Ubuntu Pro. +- **Legacy:** Computers that are licensed through a `license.txt` file. + ## Related topics - [Ubuntu Pro Client documentation](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/) From 8d7725de3ff567e4cb1264a5bf38d16072e56240 Mon Sep 17 00:00:00 2001 From: Yanisa Haley Scherber Date: Thu, 9 Oct 2025 13:11:57 -0500 Subject: [PATCH 132/187] Final draft review (#87) * language changes * Update immutable-settings.md Here's a sample for the ENV page * move table to list format * alphabetize and restructure config that can only be set in environment variables * addressed wck0 comments * added notes for read/write access for `landscape` user * removed dev-only configs and added note to `deployment_mode` that users shouldn't edit it * changes to ssl-related cert names in service section, moved schema section and added config * note on landscape system user * added ubuntu_pro_contract_server_url * removed dev-only configs * changed [broker] ssl config names and added a env value for store_superuser --------- Co-authored-by: Bill Kronholm --- docs/reference/config/immutable-settings.md | 170 +++++++++++++++---- docs/reference/config/service-conf.md | 171 +++++++++----------- docs/reference/index.md | 2 +- 3 files changed, 216 insertions(+), 127 deletions(-) diff --git a/docs/reference/config/immutable-settings.md b/docs/reference/config/immutable-settings.md index 50c34460..751e72a6 100644 --- a/docs/reference/config/immutable-settings.md +++ b/docs/reference/config/immutable-settings.md @@ -1,31 +1,145 @@ (reference-immutable-settings)= - # Immutable configuration settings -The following immutable configurations can be set in `service.conf` or through environment variables: - -| Deprecated ENV name | New ENV name | Deprecated section of `service.conf` | Section of `service.conf` | Deprecated key name in `service.conf` | Key name in `service.conf` | Default value | Purpose | -| :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | -| `LANDSCAPE_ANALYTICS_ID` | `LANDSCAPE_SYSTEM__ANALYTICS_ID` | `N/A` | `system` | `N/A` | `analytics_id` | `UA-1018242-60` | Google Analytics tracker ID for the deployment. | -| `LANDSCAPE_APT_PORT` | `LANDSCAPE_SYSTEM__APT_PORT` | `N/A` | `system` | `N/A` | `apt_port` | 8085 | The port the `landscape_apt` service should use. | -| `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` | `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` | `landscape` | `system` | `enable-password-authentication` | `enable_password_authentication` | `False` | Whether users are allowed to log in with email/password or not. | -| `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` | `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` | `landscape` | `system` | `enable-subdomain-accounts` | `enable_subdomain_accounts` | `False` | Whether subdomain-based functionality is enabled or not. | -| `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` | `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` | `landscape` | `system` | `enable-tag-script-execution` | `enable_tag_script_execution` | `False` | Whether to enable tag-based script execution. | -| `LANDSCAPE_FQDN` | `LANDSCAPE_SYSTEM__FQDN` | `N/A` | `system` | `N/A` | `fqdn` | `None` | Sets the root URL using the FQDN. | -| `LANDSCAPE_GPG_HOME` | `LANDSCAPE_SYSTEM__GPG_HOME_DIR` | `N/A` | `system` | `N/A` | `gpg_home_dir` | `/var/lib/landscape-server/gnupg` | The directory containing GnuPG config files and the {spellexception}`keyrings`. | -| `LANDSCAPE_LICENSE_FILE` | `LANDSCAPE_SYSTEM__LICENSE_FILE` | `N/A` | `system` | `N/A` | `license_file` | `/etc/landscape/license.txt` | The file path location of the license file. | -| `LANDSCAPE_MESSAGE_URL` | `LANDSCAPE_MESSAGE_SERVER__MESSAGE_URL` | `N/A` | `message_system` | `N/A` | `message_system_url` | The HTTP version of the root URL with `/message-system` appended. | The message system URL to use. | -| `LANDSCAPE_MIDDLEWARE` | `LANDSCAPE_SYSTEM__MIDDLEWARE` | `N/A` | `system` | `N/A` | `middleware` | `None` | The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. | -| `LANDSCAPE_OFFLINE` | `LANDSCAPE_SYSTEM__OFFLINE` | `global` | `system` | `offline` | `offline` | `None` | Whether offline mode is set or not (only relevant for standalone setups). | -| `LANDSCAPE_QUERY_DEBUG` | `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` | `N/A` | `system` | `N/A` | `enable_query_debug` | `False` | Whether to enable query introspection and debugging middleware for Landscape or not. | -| `LANDSCAPE_ROOT_URL` | `LANDSCAPE_SYSTEM__ROOT_URL` | `global` | `system` | `root-url` | `root_url` | `None` | The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. | -| `LANDSCAPE_TESTRUN` | `LANDSCAPE_TESTING__TESTRUN` | `N/A` | `testing` | `N/A` | `test_run` | `False` | If true, do not replace the importer with the import guardian to speed up the tests. | -| `LANDSCAPE_TEST_RUNNER` | `LANDSCAPE_TESTING__TEST_RUNNER` | `N/A` | `testing` | `N/A` | `test_runner` | `trial` | The `twisted` test runner to use for the `trial` script in `/dev`. | -| `VAULT_ADDR` | `LANDSCAPE_SECRETS__VAULT_URL` | `secrets` | `secrets` | `secrets-url` | `vault_url` | `http://localhost:8200` | The address of the vault to use for the secrets service. | -| `VAULT_TOKEN` | `LANDSCAPE_SECRETS__VAULT_TOKEN` | `N/A` | `secrets` | `N/A` | `vault_token` | `None` | The token to use for the vault instead of getting it from the secrets service. | - -The following immutable configurations can be set through environment variables only: - -| ENV name | Default value | Purpose | -| :---- | :---- | :---- | -| `LANDSCAPE_CONFIG_FILE` | `/etc/landscape/service.conf` | File path location of the `service.conf` file. | +The following immutable configurations can be set in `service.conf` or through environment variables. + +## `LANDSCAPE_CONFIG_FILE` + +```{note} +This configuration can be set through environment variables only. +``` + +- Purpose: File path location of the `service.conf` file. The `landscape` user must have read/write privileges to the file. +- Default value: `/etc/landscape/service.conf` + +## `LANDSCAPE_MESSAGE_SERVER__MESSAGE_URL` + +- Purpose: The message system URL to use. +- Default value: The HTTP version of the root URL with `/message-system` appended. +- Section: `message_system` +- Key: `message_system_url` +- Deprecated ENV name: `LANDSCAPE_MESSAGE_URL` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__ANALYTICS_ID` + +- Purpose: The Google Analytics ID for the deployment. +- Default value: `UA-1018242-60` +- Section: `system` +- Key: `analytics_id` +- Deprecated ENV name: `LANDSCAPE_ANALYTICS_ID` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__APT_PORT` + +- Purpose: The port the `landscape_apt` service should use. +- Default value: 8085 +- Section: `system` +- Key: `apt_port` +- Deprecated ENV name: `LANDSCAPE_APT_PORT` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` + +- Purpose: Whether users are allowed to log in with email/password or not. +- Default value: `False` +- Section: `system` +- Key: `enable_password_authentication` +- Deprecated ENV name: `LANDSCAPE_ENABLE_PASSWORD_AUTHENTICATION` +- Deprecated section: `landscape` +- Deprecated key: `enable-password-authentication` + +## `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` + +- Purpose: Whether subdomain-based functionality is enabled or not. +- Default value: `False` +- Section: `system` +- Key: `enable_subdomain_accounts` +- Deprecated ENV name: `LANDSCAPE_ENABLE_SUBDOMAIN_ACCOUNTS` +- Deprecated section: `landscape` +- Deprecated key: `enable-subdomain-accounts` + +## `LANDSCAPE_SYSTEM__ENABLE_TAG_SCRIPT_EXECUTION` + +- Purpose: Whether to enable tag-based script execution. +- Default value: `False` +- Section: `system` +- Key: `enable_tag_script_execution` +- Deprecated ENV name: `LANDSCAPE_ENABLE_TAG_SCRIPT_EXECUTION` +- Deprecated section: `landscape` +- Deprecated key: `enable-tag-script-execution` + +## `LANDSCAPE_SYSTEM__FQDN` + +- Purpose: Sets the root URL using the FQDN. +- Default value: `None` +- Section: `system` +- Key: `fqdn` +- Deprecated ENV name: `LANDSCAPE_FQDN` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__GPG_HOME_DIR` + +- Purpose: The directory containing GnuPG config files and the keyrings. The `landscape` user must have read/write privileges to the directory. +- Default value: `/var/lib/landscape-server/gnupg` +- Section: `system` +- Key: `gpg_home_dir` +- Deprecated ENV name: `LANDSCAPE_GPG_HOME` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__LICENSE_FILE` + +- Purpose: The file path location of the legacy license file. The `landscape` user must have read/write privileges to the file. +- Default value: `/etc/landscape/license.txt` +- Section: `system` +- Key: `license_file` +- Deprecated ENV name: `LANDSCAPE_LICENSE_FILE` +- Deprecated section: N/A +- Deprecated key: N/A + +## `LANDSCAPE_SYSTEM__OFFLINE` + +- Purpose: Whether offline mode is set or not (only relevant for standalone setups). +- Default value: `None` +- Section: `system` +- Key: `offline` +- Deprecated ENV name: `LANDSCAPE_OFFLINE` +- Deprecated section: `global` +- Deprecated key: `offline` + +## `LANDSCAPE_SYSTEM__ROOT_URL` + +- Purpose: The Landscape Server’s root URL path. HTTP requests are expected to be made to this path. +- Default value: `None` +- Section: `system` +- Key: `root_url` +- Deprecated ENV name: `LANDSCAPE_ROOT_URL` +- Deprecated section: `global` +- Deprecated key: `root-url` + +## `LANDSCAPE_SECRETS__VAULT_URL` + +- Purpose: The address of the vault to use for the Secrets service. +- Default value: `http://localhost:8200` +- Section: `secrets` +- Key: `vault_url` +- Deprecated ENV name: `VAULT_ADDR` +- Deprecated section: N/A +- Deprecated key: `secrets-url` + +## `LANDSCAPE_SECRETS__VAULT_TOKEN` + +- Purpose: The token to use for the vault instead of getting it from the secrets service. +- Default value: `None` +- Section: `secrets` +- Key: `vault_token` +- Deprecated ENV name: `VAULT_TOKEN` +- Deprecated section: N/A +- Deprecated key: N/A + + diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 9a6d6dc1..f2ac65fd 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -1,27 +1,31 @@ (reference-service-conf)= - # The `service.conf` file All Landscape service configurations are defined in the `service.conf` file. This file follows the `INI` file format. The default location for this file is `/etc/landscape/service.conf`. You can override that by setting the `LANDSCAPE_SERVICE_CONF` environment variable with the file path location of the `service.conf` file. -Changes to the `service.conf` file only take affect once you restart the relevant service(s). +Changes to the `service.conf` file only take affect once you restart the relevant service(s). Any file paths referenced throughout this document must be readable by the `landscape` system user. Starting with Landscape 25.10, every entry in the `service.conf` file can be overridden by a corresponding environment variable. These variables have the following general structure: `LANDSCAPE_SECTION_NAME__KEY_NAME`. The sections below contain information about the key-value pairs that can be set in each section, the corresponding environment variable, the default value (if any), and the purpose of the entry. ```{note} -The usage of the `-` character in section names and key names is deprecated in Landscape Server 25.10 in favor of the `_` character. Support for the `-` character will be removed in Landscape Server 26.04. +The usage of the `-` character in section names and key names was deprecated in Landscape Server 25.10 in favor of the `_` character. Support for the `-` character is expected to be removed in Landscape Server 26.04 LTS. + +In addition, the names of some sections of the `service.conf` file were deprecated in Landscape Server 25.10. These sections and their new names are detailed below. Support for the deprecated names is expected to be removed in Landscape Server 26.04 LTS. -In addition, the names of some sections of the `service.conf` file are deprecated in Landscape Server 25.10. The new names are detailed below. Support for the deprecated names will be removed in Landscape Server 26.04. +Upgrades to Landscape Server 25.10 or later will include migrating these names. ``` (shared-service-settings)= - ## Shared service settings There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service. +```{important} +The shared service settings are not mutually exclusive with the shared store settings; services can use both, if specified. +``` + ### `allowed_interfaces` - Purpose: A list of allowed IP addresses or hostnames for the service. @@ -36,13 +40,6 @@ There are a set of generic settings that all services can set, where `SERVICE` i - ENV name: `LANDSCAPE_SERVICE__BASE_PORT` - Default: `8090` -### `devmode` - -- Purpose: To control development mode configuration. This setting should not be configured in production environments. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__DEVMODE` -- Default: `None` - ### `enable_metrics` - Purpose: Whether to enable metrics collection for the service. @@ -66,7 +63,7 @@ There are a set of generic settings that all services can set, where `SERVICE` i ### `mailer` -- Purpose: If set to `queue` the mailer will use the queue specified by the `mailer_path`. If set to `default` the queue will be at `/tmp/landscape-mail-queue`. If unset, no mailer will be configured for the service. Production deployments do not need to modify this setting. +- Purpose: If set to `queue`, the mailer will use the queue specified by the `mailer_path`. If set to `default`, the queue will be at `/tmp/landscape-mail-queue`. If unset, no mailer will be configured for the service. Production deployments do not need to modify this setting. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SERVICE__MAILER` - Default: `None` @@ -99,25 +96,25 @@ There are a set of generic settings that all services can set, where `SERVICE` i - ENV name: `LANDSCAPE_SERVICE__SOFT_TIMEOUT` - Default: `None` -### `ssl_server_cert` +### `ssl_client_cert` -- Purpose: Sets the path to the certificate to use for mTLS. If set, `ssl_private_key` must also be set. +- Purpose: Sets the path to the certificate to use for mTLS. If set, `ssl_client_private_key` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_SERVER_CERT` +- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_CERT` - Default: `None` -### `ssl_private_key` +### `ssl_client_private_key` -- Purpose: Sets the path to the private key to use for mTLS. If set, `ssl_server_cert` must also be set. +- Purpose: Sets the path to the private key to use for mTLS. If set, `ssl_client_cert` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_PRIVATE_KEY` +- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_PRIVATE_KEY` - Default: `None` -### `ssl_ca_cert` +### `ssl_client_ca_cert` -- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_private_key` and `ssl_server_cert` must also be set. +- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_client_private_key` and `ssl_client_cert` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_CA_CERT` +- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_CA_CERT` - Default: `None` ### `threads` @@ -134,15 +131,14 @@ There are a set of generic settings that all services can set, where `SERVICE` i - ENV name: `LANDSCAPE_SERVICE__WORKERS` - Default: `None` -```{important} -The shared service settings are not mutually exclusive with the shared store settings; services can use both, if specified. -``` - (shared-store-settings)= - ## Shared store settings -There are a set of generic settings related to databases and SSL connections to Postgres that several sections can set, where `SECTION` in the ENV name matches the (uppercase) name of the section: +There are a set of generic settings related to databases and SSL connections to Postgres that several sections can set, where `SECTION` in the ENV name matches the (uppercase) name of the section. + +```{important} +The shared store settings are not mutually exclusive with the shared service settings; services can use both, if specified. +``` ### `sslcert` @@ -160,7 +156,7 @@ There are a set of generic settings related to databases and SSL connections to ### `sslmode` -- Purpose: SSL mode to use when connecting to Postgres, for example `verify-full`. +- Purpose: SSL mode to use when connecting to Postgres, for example `verify-full`. See [PostgreSQL's documentation for the list of valid options](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS). - Deprecated key name: N/A - ENV name: `LANDSCAPE_SECTION__SSLMODE` - Default: `None` @@ -174,14 +170,14 @@ There are a set of generic settings related to databases and SSL connections to ### `store_password` -- Purpose: Overrides the store password set in the `store` settings. +- Purpose: Overrides the store password set in the `stores` settings. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SECTION__STORE_PASSWORD` - Default: `None` ### `store_user` -- Purpose: Overrides the store username set in the `store` settings. +- Purpose: Overrides the store username set in the `stores` settings. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SECTION__STORE_USER` - Default: `None` @@ -193,10 +189,6 @@ There are a set of generic settings related to databases and SSL connections to - ENV name: `LANDSCAPE_SECTION__STORES` - Default: `None` -```{important} -The shared store settings are not mutually exclusive with the shared service settings; services can use both, if specified. -``` - ## The `[api]` section The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -220,7 +212,7 @@ The `[api]` section contains configurations for the Landscape API service, inclu ### `snap_store_api_url` -- Purpose: The API for a Snap Store Proxy. By default, this is the Canonical Snap Store. +- Purpose: The API for an Enterprise Store (formerly known as Snap Store Proxy). By default, this is the Canonical Snap Store. - Deprecated key name: `snap-store-api-url` - ENV name: `LANDSCAPE_API__SNAP_STORE_API_URL` - Default: `https://api.snapcraft.io/v2` @@ -228,21 +220,21 @@ The `[api]` section contains configurations for the Landscape API service, inclu ## The `[appserver]` section ```{note} -The `[landscape]` section name is deprecated. The `[appserver]` section replaces the `[landscape]` section. +The `[landscape]` section name was deprecated in Landscape Server 25.10. The `[appserver]` section replaces the `[landscape]` section. ``` The `[appserver]` section contains configurations for the Landscape application server, including storage paths and authentication providers. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. ### Moved Configuration Keys -The following keys have moved from the `[appserver]` section to the `[system]` section in Landscape 25.10: +Beginning in Landscape Server 25.10, the following keys have moved from the `[appserver]` section to the `[system]` section: - `enable-password-authentication` → `enable_password_authentication` in `[system]` - `enable-subdomain-accounts` → `enable_subdomain_accounts` in `[system]` - `enable-saas-metrics` → `enable_saas_metrics` in `[system]` - `enable-tag-script-execution` → `enable_tag_script_execution` in `[system]` -These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape 26.04, when support will be removed and they must be configured in the `[system]` section. +These keys can still be used in their deprecated forms in `[appserver]`/`[landscape]` until Landscape Server 26.04 LTS, when support is expected to be removed and they must be configured in the `[system]` section. Note that upgrades of Landscape Server 25.10 and later includes automated migration of these names. ### Authentication providers @@ -257,7 +249,7 @@ OIDC: ### `blob_storage_root` -- Purpose: Root directory for blob storage used for USG reports. +- Purpose: Root directory for blob storage used for Ubuntu Security Guide (USG) reports. - Deprecated key name: `blob-storage-root` - ENV name: `LANDSCAPE_APPSERVER__BLOB_STORAGE_ROOT` - Default: `/var/lib/landscape/blobs` @@ -320,7 +312,7 @@ OIDC: ### `openid_provider_url` -- Purpose: OpenID logout URL. Required along with `openid_logout_url` when using OpenID authentication. +- Purpose: OpenID provider URL. Required along with `openid_logout_url` when using OpenID authentication. - Deprecated key name: `openid-provider-url` - ENV name: `LANDSCAPE_APPSERVER__OPENID_PROVIDER_URL` - Default: `None` @@ -334,7 +326,7 @@ OIDC: ### `reprepro_binary` -- Purpose: Path to the reprepro binary executable. If unset the binary installed at `/usr/bin/reprepro` is used. +- Purpose: Path to the reprepro binary executable. If unset, the binary installed at `/usr/bin/reprepro` is used. - Deprecated key name: `reprepro-binary` - ENV name: `LANDSCAPE_APPSERVER__REPREPRO_BINARY` - Default: `None` @@ -363,7 +355,7 @@ OIDC: ## The `[async_frontend]` section ```{note} -The `[async-frontend]` section name is deprecated. The `[async_frontend]` section replaces the `[async-frontend]` section. +The `[async-frontend]` section name was deprecated in Landscape Server 25.10. The `[async_frontend]` section replaces the `[async-frontend]` section. ``` The `[async_frontend]` section contains configurations that apply to the `landscape-async-frontend` service which handles AJAX requests from the Legacy UI. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -425,23 +417,23 @@ The `[broker]` section contains configurations that describe how services connec ### `ssl_client_cert` -- Purpose: Path to the client certificate to use for an SSL connection to the AMQP broker. Required along with `ssl_private_key` for mTLS connections. +- Purpose: Path to the client certificate to use for an SSL connection to the AMQP broker. Required along with `ssl_client_private_key` for mTLS connections. - Deprecated key name: N/A - ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_CERT` - Default: `None` -### `ssl_private_key` +### `ssl_client_private_key` - Purpose: Path to the private key to use for an SSL connection to the AMQP broker. Required along with `ssl_client_cert` for mTLS connections. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_BROKER__SSL_PRIVATE_KEY` +- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_PRIVATE_KEY` - Default: `None` -### `ssl_ca_cert` +### `ssl_client_ca_cert` -- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_private_key` and `ssl_server_cert` must also be set. +- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_client_private_key` and `ssl_client_cert` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_BROKER__SSL_CA_CERT` +- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_CA_CERT` - Default: `None` ### `user` @@ -461,7 +453,7 @@ The `[broker]` section contains configurations that describe how services connec ## The `[job_handler]` section ```{note} -The `[job-handler]` section name is deprecated. The `[job_handler]` section replaces the `[job-handler]` section. +The `[job-handler]` section name was deprecated in Landscape Server 25.10. The `[job_handler]` section replaces the `[job-handler]` section. ``` The `[job_handler]` section contains configurations for the `landscape-job-handler` service which runs background jobs. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -471,7 +463,7 @@ In practice, only the `base_port` setting needs to be configured for the service ## The `[load_shaper]` section ```{note} -The `[load-shaper]` section name is deprecated. The `[load_shaper]` section replaces the `[load-shaper]` section. +The `[load-shaper]` section name was deprecated in Landscape Server 25.10. The `[load_shaper]` section replaces the `[load-shaper]` section. ``` The `[load_shaper]` section contains configurations for controlling how many messages are processed in each message exchange. It allots a time window for message processing based on the current database load. @@ -508,11 +500,9 @@ The `[maintenance]` section contains configurations for running maintenance scri ## The `[message_server]` section ```{note} -The `[message-server]` section name is deprecated. The `[message_server]` section replaces the `[message-server]` section. -``` +The `[message-server]` section name was deprecated in Landscape Server 25.10. The `[message_server]` section replaces the `[message-server]` section. -```{note} -The `[backoff]` section is deprecated. The settings have been moved to the `[message_server]` section. +The `[backoff]` section was also deprecated in Landscape Server 25.10. The settings have been moved to the `[message_server]` section. ``` The `[message_server]` section contains configurations that apply to the `landscape-message-server` service that handles messages from instances running Landscape Client. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -584,14 +574,10 @@ The `[oops]` section contains configurations for the OOPS error reporting and de - ENV name: `LANDSCAPE_OOPS__PATH` - Default: `None` -## The `[schema]` section - -The `[schema]` section contains configurations for updating the database schema. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. - ## The `[package_upload]` section ```{note} -The `[package-upload]` section name is deprecated. The `[package_upload]` section replaces the `[package-upload]` section. +The `[package-upload]` section name was deprecated in Landscape Server 25.10. The `[package_upload]` section replaces the `[package-upload]` section. ``` The `[package_upload]` section contains configurations for the package upload service, including service connection settings, database store configurations, and SSL options. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -610,6 +596,17 @@ The `[package_upload]` section contains configurations for the package upload se - ENV name: `LANDSCAPE_PACKAGE_UPLOAD__SERVICE_PATH` - Default: `/upload/` +## The `[schema]` section + +The `[schema]` section contains configurations for updating the database schema. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. + +### `store_superuser` + +- Purpose: If the set_user PostgreSQL extension is installed, Landscape will connect to PG as the `store_user`, then escalate to the `store_superuser`. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SCHEMA__STORE_SUPERUSER` +- Default: None + ## The `[scripts]` section The `[scripts]` section contains configurations for scripts. The section contains only the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -641,7 +638,7 @@ The `[secrets]` section contains configurations for the secrets service, such as ## The `[stores]` section -The `[stores]` section contains configurations for database store names and connections. In addition, the this section can use the {ref}`shared store settings `. +The `[stores]` section contains configurations for database store names and connections. In addition, this section can use the {ref}`shared store settings `. ### `account_1` @@ -650,13 +647,6 @@ The `[stores]` section contains configurations for database store names and conn - ENV name: `LANDSCAPE_STORES__ACCOUNT_1` - Default: `landscape-standalone-account-1` -### `account_2` - -- Purpose: The second account database store name. In practice this settings should be left unset as it is used only by tests. -- Deprecated key name: `account-2` -- ENV name: `LANDSCAPE_STORES__ACCOUNT_2` -- Default: `None` - ### `host` - Purpose: The hostname or IP address of the database server. @@ -666,7 +656,11 @@ The `[stores]` section contains configurations for database store names and conn ### `knowledge` -- Purpose: The knowledge database name. The knowledge database is deprecated and will be dropped in a future release of Landscape Server. +```{note} +The knowledge database was deprecated in Landscape Server 25.10 and will be dropped in a future release of Landscape Server. +``` + +- Purpose: The knowledge database name. - Deprecated key name: N/A - ENV name: `LANDSCAPE_STORES__KNOWLEDGE` - Default: `landscape-standalone-knowledge` @@ -699,13 +693,6 @@ The `[stores]` section contains configurations for database store names and conn - ENV name: `LANDSCAPE_STORES__RESOURCE_1` - Default: `landscape-standalone-resource-1` -### `resource_2` - -- Purpose: The second resource database name. In practice this settings should be left unset as it is used only by tests. -- Deprecated key name: `resource-2` -- ENV name: `LANDSCAPE_STORES__RESOURCE_2` -- Default: `None` - ### `session` - Purpose: The session database name. @@ -723,14 +710,14 @@ The `[stores]` section contains configurations for database store names and conn ### `user` - Purpose: The username for database connections. -- Deprecated key name: `session-autocommit` +- Deprecated key name: N/A - ENV name: `LANDSCAPE_STORES__USER` - Default: `landscape` ## The `[system]` section ```{note} -The `[global]` section name is deprecated. The `[system]` section replaces the `[global]` section. +The `[global]` section name was deprecated in Landscape Server 25.10. The `[system]` section replaces the `[global]` section. ``` The `[system]` section contains configurations that apply across many or all of Landscape's services. @@ -758,7 +745,11 @@ The `[system]` section contains configurations that apply across many or all of ### `deployment_mode` -- Purpose: Used only for development. The default value is appropriate for self-hosted Landscape Server. +```{note} +**Do not change the `deployment_mode` default value.** +``` + +- Purpose: Used only for development. The default value is appropriate for self-hosted Landscape Server. Users should never change this setting. - Deprecated key name: `deployment-mode` - ENV name: `LANDSCAPE_SYSTEM__DEPLOYMENT_MODE` - Default: `standalone` @@ -770,23 +761,16 @@ The `[system]` section contains configurations that apply across many or all of - ENV name: `LANDSCAPE_SYSTEM__ENABLE_PASSWORD_AUTHENTICATION` - Default: `False` -### `enable_query_debug` - -- Purpose: Whether to enable query introspection and debugging middleware or not. The default value is appropriate for self-hosted Landscape Server. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_SYSTEM__ENABLE_QUERY_DEBUG` -- Default: `False` - ### `enable_saas_metrics` -- Purpose: Whether to enable metrics on SaaS or not. The default value is appropriate for self-hosted Landscape Server. +- Purpose: Whether to enable metrics on SaaS or not. The default value is appropriate for self-hosted Landscape Server. Users generally shouldn't change this setting. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SYSTEM__ENABLE_SAAS_METRICS` - Default: `False` ### `enable_subdomain_accounts` -- Purpose: Whether to enable subdomain accounts or not. The default value is appropriate for self-hosted Landscape Server. +- Purpose: Whether to enable subdomain accounts or not. The default value is appropriate for self-hosted Landscape Server. Users generally shouldn't change this setting. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SYSTEM__ENABLE_SUBDOMAIN_ACCOUNTS` - Default: `False` @@ -807,7 +791,7 @@ The `[system]` section contains configurations that apply across many or all of ### `license_file` -- Purpose: The file path location of the license file. The `landscape` system user must be able to read this file. +- Purpose: The file path location of the legacy license file. Ubuntu Pro users don't need to set this. The `landscape` system user must be able to read this file. - Deprecated key name: N/A - ENV name: `LANDSCAPE_SYSTEM__LICENSE_FILE` - Default: `/etc/landscape/license.txt` @@ -819,13 +803,6 @@ The `[system]` section contains configurations that apply across many or all of - ENV name: `LANDSCAPE_SYSTEM__MAX_SERVICE_MEMORY` - Default: `0` -### `middleware` - -- Purpose: The python dotted name to the middleware function or class to use. Multiple values can be provided by separating them with a comma. This setting should remain unset in production environments. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_SYSTEM__MIDDLEWARE` -- Default: `None` - ### `offline` - Purpose: Set `True` if Landscape is deployed in an air-gapped environment. @@ -854,11 +831,9 @@ The `[system]` section contains configurations that apply across many or all of - ENV name: `LANDSCAPE_SYSTEM__SYSLOG_ADDRESS` - Default: `/dev/log` - diff --git a/docs/reference/index.md b/docs/reference/index.md index c8f0f9f7..01130f73 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -9,8 +9,8 @@ This section includes technical information you may need to reference when using :glob: api/index -config/index release-notes/index +config/index logs/index networking/index terms/index From db1afac8d0b03f32bb856a2b31195c82494f9702 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Thu, 9 Oct 2025 12:29:10 -0700 Subject: [PATCH 133/187] feat: add hostagent-* settings sections (#81) --- docs/reference/config/service-conf.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index f2ac65fd..eb8fb0e1 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -450,6 +450,26 @@ The `[broker]` section contains configurations that describe how services connec - ENV name: `LANDSCAPE_BROKER__VHOST` - Default: `landscape` +## The `[hostagent_consumer]` section + +```{note} +The `[hostagent-consumer]` section name is deprecated. The `[hostagent_consumer]` section replaces the `[hostagent-consumer]` section. +``` + +The `[hostagent_consumer]` section contains settings for the `landscape-hostagent-consumer` service that processes messages related to Ubuntu Pro for WSL. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. + +This entire section is optional. Omitting the `[hostagent_consumer]` section entirely will cause the `landscape-hostagent-consumer` service to stop immediately after it starts. + +## The `[hostagent_messenger]` section + +```{note} +The `[hostagent-messenger]` section name is deprecated. The `[hostagent_messenger]` section replaces the `[hostagent-messenger]` section. +``` + +The `[hostagent_messenger]` section contains settings for the `landscape-hostagent-messenger` service that communicates with Ubuntu Pro for WSL. It has no settings beyond the {ref}`shared service settings ` and the {ref}`shared store settings `. + +This entire section is optional. Omitting the `[hostagent_messenger]` section entirely will cause the `landscape-hostagent-messenger` service to stop immediately after it starts. + ## The `[job_handler]` section ```{note} From c3ee754e70a3d9fe558775367bcd0e88af25e25a Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Thu, 9 Oct 2025 14:04:22 -0700 Subject: [PATCH 134/187] fix: typo in header (#91) --- docs/reference/api/rest-api-endpoints/accounts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/api/rest-api-endpoints/accounts.md b/docs/reference/api/rest-api-endpoints/accounts.md index b89ef2d7..59853b11 100644 --- a/docs/reference/api/rest-api-endpoints/accounts.md +++ b/docs/reference/api/rest-api-endpoints/accounts.md @@ -4,7 +4,7 @@ The endpoints available here are related to account management. -## POST `/account` +## POST `/accounts` Create an account for the current user. If the user already has an account, or self-service account creation is disabled, the request will fail. From 6b1430eef18a53fcecacbf9081b0a46aebb88c8e Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Thu, 9 Oct 2025 14:54:40 -0700 Subject: [PATCH 135/187] feat: add package search settings section (#80) --- docs/reference/config/service-conf.md | 38 +++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index eb8fb0e1..1c3f8605 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -594,6 +594,44 @@ The `[oops]` section contains configurations for the OOPS error reporting and de - ENV name: `LANDSCAPE_OOPS__PATH` - Default: `None` +## The `[package_search]` section + +```{note} +The `[package-search]` section name is deprecated. The `[package_search]` section replaces the `[package-search]` section. +``` + +The `[package_search]` section contains the configuration for the package search service. In a manual installation, the pre-configured settings should suffice. In a Juju deployment, many of these settings are managed by the Landscape Server charm. + +In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. + +### `account_threshold` + +- Purpose: The number of registered computers in an account required for the account to use the package search service. Self-hosted Landscape Server deployments should keep the default value to ensure the package search service is always used. +- Deprecated key name: `account-threshold` +- ENV name: `LANDSCAPE_PACKAGE_SEARCH__ACCOUNT_THRESHOLD` +- Default: `0` + +### `host` + +- Purpose: The hostname or IP address of the machine where the package search service runs. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_PACKAGE_SEARCH__HOST` +- Default: `localhost` + +### `pid_path` + +- Purpose: The file path for the `.pid` file for the package search service. The `landscape` system user must have read/write access to this file. +- Deprecated key name: `pid-path` +- ENV name: `LANDSCAPE_PACKAGE_SEARCH__PID_PATH` +- Default: `/var/run/landscape-packagesearch-1.pid` + +### `port` + +- Purpose: The port the package search service will listen on. This setting has no default value and is required. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_PACKAGE_SEARCH__PORT` +- Default: There is no default value. One must be set for the system to run. + ## The `[package_upload]` section ```{note} From d50de269d2b3aae318c2b1d067a7d4e19d6f4463 Mon Sep 17 00:00:00 2001 From: Bill Kronholm Date: Thu, 9 Oct 2025 16:05:55 -0700 Subject: [PATCH 136/187] feat: add pingserver settings (#82) --- docs/reference/config/service-conf.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index 1c3f8605..f673ac59 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -20,7 +20,7 @@ Upgrades to Landscape Server 25.10 or later will include migrating these names. (shared-service-settings)= ## Shared service settings -There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service. +There are a set of generic settings that all services can set, where `SERVICE` in the ENV name matches the (uppercase) name of the service. For example, the `LANDSCAPE_PINGSERVER__BASE_PORT` sets the `base_port` for the `[pingserver]` service, whereas the `LANDSCAPE_API__BASE_PORT` sets the `base_port` for the `[api]` service. ```{important} The shared service settings are not mutually exclusive with the shared store settings; services can use both, if specified. @@ -654,6 +654,31 @@ The `[package_upload]` section contains configurations for the package upload se - ENV name: `LANDSCAPE_PACKAGE_UPLOAD__SERVICE_PATH` - Default: `/upload/` +## The `[pingserver]` section + +The `[pingserver]` section contains configurations for the `pingserver` service that communicates with registered clients, notifying the clients about available messages. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. + +### `database_check_interval` + +- Purpose: Interval in seconds to check the database for computers with outstanding messages. +- Deprecated key name: `database-check-interval` +- ENV name: `LANDSCAPE_PINGSERVER__DATABASE_CHECK_INTERVAL` +- Default: `30` + +### `database_write_interval` + +- Purpose: Interval in seconds between database writes of accumulated pings. +- Deprecated key name: `database-write-interval` +- ENV name: `LANDSCAPE_PINGSERVER__DATABASE_WRITE_INTERVAL` +- Default: `60` + +### `ping_url` + +- Purpose: The `pingserver` service handles HTTP request from this URL. If unset, the http version of the configured root URL appended by `ping` is used. +- Deprecated key name: `ping-url` +- ENV name: `LANDSCAPE_PINGSERVER__PING_URL` +- Default: `None` + ## The `[schema]` section The `[schema]` section contains configurations for updating the database schema. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. From 85f086e7cea1ca11b698bf613d78b545275fce2d Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Thu, 9 Oct 2025 17:36:32 -0600 Subject: [PATCH 137/187] feat: docs for generic tls client settings (rabbit/vault) (#92) --- docs/reference/config/service-conf.md | 69 ++++++++++++++------------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/docs/reference/config/service-conf.md b/docs/reference/config/service-conf.md index f673ac59..01b4751d 100644 --- a/docs/reference/config/service-conf.md +++ b/docs/reference/config/service-conf.md @@ -96,25 +96,25 @@ The shared service settings are not mutually exclusive with the shared store set - ENV name: `LANDSCAPE_SERVICE__SOFT_TIMEOUT` - Default: `None` -### `ssl_client_cert` +### `ssl_server_cert` -- Purpose: Sets the path to the certificate to use for mTLS. If set, `ssl_client_private_key` must also be set. +- Purpose: Sets the path to the certificate to use when listening with mTLS. If set, `ssl_server_private_key` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_CERT` +- ENV name: `LANDSCAPE_SERVICE__SSL_SERVER_CERT` - Default: `None` -### `ssl_client_private_key` +### `ssl_server_private_key` -- Purpose: Sets the path to the private key to use for mTLS. If set, `ssl_client_cert` must also be set. +- Purpose: Sets the path to the private key to use when listening with mTLS. If set, `ssl_server_cert` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_PRIVATE_KEY` +- ENV name: `LANDSCAPE_SERVICE__SSL_SERVER_PRIVATE_KEY` - Default: `None` -### `ssl_client_ca_cert` +### `ssl_server_ca_cert` -- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_client_private_key` and `ssl_client_cert` must also be set. +- Purpose: Sets the path to the CA certificate to use when listening with mTLS. If set, both `ssl_server_private_key` and `ssl_server_cert` must also be set. - Deprecated key name: N/A -- ENV name: `LANDSCAPE_SERVICE__SSL_CLIENT_CA_CERT` +- ENV name: `LANDSCAPE_SERVICE__SSL_SERVER_CA_CERT` - Default: `None` ### `threads` @@ -189,6 +189,32 @@ The shared store settings are not mutually exclusive with the shared service set - ENV name: `LANDSCAPE_SECTION__STORES` - Default: `None` +(shared-tls-client-settings)= +## Shared TLS client settings + +These are generic TLS client certificate settings to connect to external services, such as RabbitMQ and HashiCorp Vault, with mTLS, where `SECTION` in the ENV name matches the (uppercase) name of the section. + +### `ssl_client_cert` + +- Purpose: Path to the client certificate to use for an mTLS connection to the external server. Required along with `ssl_client_private_key` for mTLS connections. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSL_CLIENT_CERT` +- Default: `None` + +### `ssl_client_private_key` + +- Purpose: Path to the private key to use for an mTLS connection to the external server. Required along with `ssl_client_cert` for mTLS connections. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSL_CLIENT_PRIVATE_KEY` +- Default: `None` + +### `ssl_client_ca_cert` + +- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_client_private_key` and `ssl_client_cert` must also be set. +- Deprecated key name: N/A +- ENV name: `LANDSCAPE_SECTION__SSL_CLIENT_CA_CERT` +- Default: `None` + ## The `[api]` section The `[api]` section contains configurations for the Landscape API service, including service connection settings and database store configurations. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. @@ -364,7 +390,7 @@ In practice, only the `base_port` setting needs to be configured for the service ## The `[broker]` section -The `[broker]` section contains configurations that describe how services connect to our AMQP broker (RabbitMQ). +The `[broker]` section contains configurations that describe how services connect to our AMQP broker (RabbitMQ). In addition to the following, this section can use the {ref}`shared TLS client settings ` to connect to a RabbitMQ server with mTLS. ### `host` @@ -415,27 +441,6 @@ The `[broker]` section contains configurations that describe how services connec - ENV name: `LANDSCAPE_BROKER__PORT` - Default: `5672` -### `ssl_client_cert` - -- Purpose: Path to the client certificate to use for an SSL connection to the AMQP broker. Required along with `ssl_client_private_key` for mTLS connections. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_CERT` -- Default: `None` - -### `ssl_client_private_key` - -- Purpose: Path to the private key to use for an SSL connection to the AMQP broker. Required along with `ssl_client_cert` for mTLS connections. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_PRIVATE_KEY` -- Default: `None` - -### `ssl_client_ca_cert` - -- Purpose: Sets the path to the CA to use for mTLS. If set, both `ssl_client_private_key` and `ssl_client_cert` must also be set. -- Deprecated key name: N/A -- ENV name: `LANDSCAPE_BROKER__SSL_CLIENT_CA_CERT` -- Default: `None` - ### `user` - Purpose: Username used to authenticate with the message broker. @@ -696,7 +701,7 @@ The `[scripts]` section contains configurations for scripts. The section contain ## The `[secrets]` section -The `[secrets]` section contains configurations for the secrets service, such as vault connection settings. In addition to the following, this section can use the {ref}`shared service settings ` and the {ref}`shared store settings `. +The `[secrets]` section contains configurations for the secrets service, such as HashiCorp Vault connection settings. In addition to the following, this section can use the {ref}`shared service settings `, the {ref}`shared store settings `, and the {ref}`shared TLS client settings ` to connect to a Vault server with mTLS. ### `service_url` From 061315f0fb351acfde4049276270591324762503 Mon Sep 17 00:00:00 2001 From: Jan <77344313+jansdhillon@users.noreply.github.com> Date: Thu, 9 Oct 2025 18:09:23 -0600 Subject: [PATCH 138/187] feat: document how to use mTLS with RabbitMQ/broker, secrets-service, async-frontend (#85) --- docs/.custom_wordlist.txt | 2 +- .../security/harden-your-deployment.md | 158 ++++++++++++++++++ 2 files changed, 159 insertions(+), 1 deletion(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index fc7bb41d..650f0c47 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -101,7 +101,7 @@ frontend HAProxy HashiCorp hardcoded -Hashicorp +HashiCorp’s hashid Hashids heredoc diff --git a/docs/how-to-guides/security/harden-your-deployment.md b/docs/how-to-guides/security/harden-your-deployment.md index 2c5567ef..ee69451e 100644 --- a/docs/how-to-guides/security/harden-your-deployment.md +++ b/docs/how-to-guides/security/harden-your-deployment.md @@ -69,3 +69,161 @@ Ubuntu LTS releases with Ubuntu Pro can take advantage of the [Ubuntu Security G ## Harden Juju If you used Juju to deploy Landscape, you can follow [Juju's hardening guide](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-juju-deployment/harden-your-juju-deployment/#harden-your-deployment) to harden the Juju aspects of your deployment. + +## mTLS in Landscape + +The transport-layer security (TLS) protocol secures communication by requiring the server to present a certificate and private key. With mutual TLS (mTLS), clients must also present a certificate issued by the same certificate authority (CA), so both sides authenticate each other. + +Landscape can be configured to use mTLS for its internal services, and for connections to external services like RabbitMQ and HashiCorp Vault. + + +```{note} +Standard TLS connections that do not enforce mTLS are not supported. +``` + +### CA Certificate + +You will need the CA certificate used to sign your certificates. Ensure it has the following permissions: + +```sh +sudo chmod 644 /path/to/ca/ca-cert.pem +sudo chown root:root /path/to/ca/ca-cert.pem +``` + +### RabbitMQ + +Obtain TLS server credentials and the CA certificate for the RabbitMQ server and provide their paths in `/etc/rabbitmq/rabbitmq.conf`, along with other required fields: + +```ini +listeners.tcp = none +listeners.ssl.default = 5672 +ssl_options.certfile = /path/to/rabbitmq/server-cert.pem +ssl_options.keyfile = /path/to/rabbitmq/server-key.pem +ssl_options.cacertfile = /path/to/ca/ca-cert.pem +ssl_options.verify = verify_peer +ssl_options.fail_if_no_peer_cert = true +auth_mechanisms.1 = EXTERNAL +ssl_cert_login_from = common_name +``` + +Additionally, edit `/etc/rabbitmq/enabled_plugins`: + +```ini +[rabbitmq_auth_mechanism_ssl]. +``` + +Set ownership and permissions: + +```sh +sudo chown rabbitmq:rabbitmq /path/to/rabbitmq/server-cert.pem /path/to/rabbitmq/server-key.pem +sudo chmod 600 /path/to/rabbitmq/server-key.pem +sudo chmod 644 /path/to/rabbitmq/server-cert.pem +``` + +Restart RabbitMQ: + +```sh +sudo systemctl restart rabbitmq-server +``` + +Landscape connects to RabbitMQ via the credentials defined in the `[broker]` section of your `service.conf` file. +Since RabbitMQ is listening using mTLS, delete the `password` field from the section if present and provide the paths to TLS credentials to enable TLS certificate-based authentication: + +```ini +[broker] +ssl_client_cert = /path/to/broker/client-cert.pem +ssl_client_private_key = /path/to/broker/client-key.pem +ssl_client_ca_cert = /path/to/ca/ca-cert.pem +``` + +Ensure the broker credentials are owned by the `landscape` user: + +```sh +sudo chown landscape:landscape /path/to/broker/client-cert.pem /path/to/broker/client-key.pem +sudo chmod 600 /path/to/broker/client-key.pem +sudo chmod 644 /path/to/broker/client-cert.pem +``` + +Restart Landscape: + +```sh +sudo lsctl restart +``` + +### Landscape services + +The following Landscape services can be configured to use mTLS: + +* `landscape-async-frontend` +* `landscape-secrets-service` + +Each service can have its own server certificate and can be configured to require clients to authenticate via their own TLS credentials. +The `secrets-service` can additionally be configured to connect to HashiCorp Vault as a client via mTLS. + +#### Async Frontend + +The `async-frontend` service can listen using mTLS for incoming connections. + +Obtain TLS server credentials, and add the paths in the `[async_frontend]` section in `service.conf`: + +```ini +ssl_server_cert = /path/to/async_frontend/server-cert.pem +ssl_server_private_key = /path/to/async_frontend/server-key.pem +ssl_server_ca_cert = /path/to/ca/ca-cert.pem +``` + +Set ownership and permissions: + +```sh +sudo chown landscape:landscape /path/to/async_frontend/server-cert.pem /path/to/async_frontend/server-key.pem +sudo chmod 600 /path/to/async_frontend/server-key.pem +sudo chmod 644 /path/to/async_frontend/server-cert.pem +``` + +Restart Landscape: + +```sh +sudo lsctl restart +``` + +#### Secrets Service (with HashiCorp Vault) + +The `secrets-service` can listen using mTLS for incoming connections, and it can connect to a Vault server using mTLS. See HashiCorp's guide on [hardening your Vault server](https://developer.hashicorp.com/vault/docs/concepts/production-hardening). + +Update the `vault_url` field in the `[secrets]` section of your `service.conf`, and make sure both URLs are using HTTPS: + +```ini +[secrets] +service_url = https://localhost:26155 +vault_url = https://localhost:8200 +``` + +Since Vault is enforcing mTLS, you must also obtain or generate client TLS credentials issued by the same CA and append them to the section: + +```ini +ssl_client_private_key = /path/to/client/client-key.pem +ssl_client_cert = /path/to/client/client-cert.pem +ssl_client_ca_cert = /path/to/ca/ca-cert.pem +``` + +To make the Secrets Service listen using mTLS, provide the paths to the certificate and the private key in the `[secrets]` section of your `service.conf`: + +```ini +ssl_server_private_key = /path/to/secrets/server-key.pem +ssl_server_cert = /path/to/secrets/server-cert.pem +ssl_server_ca_cert = /path/to/ca/ca-cert.pem +``` + +Set ownership and permissions: + +```sh +sudo chown landscape:landscape /path/to/secrets/server-cert.pem /path/to/secrets/server-key.pem +sudo chmod 600 /path/to/secrets/server-key.pem +sudo chmod 644 /path/to/secrets/server-cert.pem +``` + +Restart Landscape: + +```sh +sudo lsctl restart +``` From c9dafea76cf8fa051eec94c470d0b42fb123eaea Mon Sep 17 00:00:00 2001 From: David Date: Fri, 10 Oct 2025 03:46:49 -0500 Subject: [PATCH 139/187] Update docs/explanation/landscape/licenses.md Co-authored-by: Yanisa Haley Scherber --- docs/explanation/landscape/licenses.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index 7309e815..a78cc83f 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -37,12 +37,12 @@ Here’s a summary of the different license types in Landscape and what they ind * These don't require the `license.txt` file to be installed or have available seats on the Landscape server * Requires `landscape-client` 23.x or higher to report the Pro attachment information to the Landscape server -## New licensing states +## License types -For Landscape Server versions `25.10x` or greater there will be new licensing states. These states will allow for a user to register a client with Landscape without having any proper licensing mechanisms (e.g., Ubuntu Pro and `license.txt`). In this new unlicensed state client machine management will be limited, only allowing for operations to license that instance. This will allow for users to register client machines with Landscape, then attach Ubuntu Pro to desired client machines without needing to perform operation on each individual instance. +For Landscape Server versions `25.10` and later, there are the following license types. ```{note} -This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. +The **Unlicensed** license type is available for self-hosted 25.10 and later and **select accounts on SaaS**. License management activities associated with this type are unavailable for the Landscape Client snap, Core devices, and offline Client deployments. ``` ### Client states From 116620fff53a7b635700ae66465efca52c1a9df4 Mon Sep 17 00:00:00 2001 From: David Date: Fri, 10 Oct 2025 03:47:40 -0500 Subject: [PATCH 140/187] Update docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md Co-authored-by: Yanisa Haley Scherber --- docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md index 7e899c66..dff95064 100644 --- a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md +++ b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md @@ -77,7 +77,7 @@ When the machine has successfully been attached, you will also see a summary of Available services can be enabled or disabled on the command line with `pro enable ` and `pro disable ` after you have attached. -## Through Landscape Server +## Automated attachment across multiple clients ### Ubuntu Pro licensing method From fc7fe994619ba681edee290589a1cfaee1119868 Mon Sep 17 00:00:00 2001 From: David Date: Fri, 10 Oct 2025 03:47:54 -0500 Subject: [PATCH 141/187] Update docs/explanation/landscape/licenses.md Co-authored-by: Yanisa Haley Scherber --- docs/explanation/landscape/licenses.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index a78cc83f..e5dad037 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -45,8 +45,6 @@ For Landscape Server versions `25.10` and later, there are the following license The **Unlicensed** license type is available for self-hosted 25.10 and later and **select accounts on SaaS**. License management activities associated with this type are unavailable for the Landscape Client snap, Core devices, and offline Client deployments. ``` -### Client states - - **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management operations. - **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. - **Pro:** Computers that are licensed through Ubuntu Pro. From 9897bd1352df74835db173f79d9f7afc4acbb4fd Mon Sep 17 00:00:00 2001 From: David Date: Fri, 10 Oct 2025 03:48:57 -0500 Subject: [PATCH 142/187] Update docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md Co-authored-by: Yanisa Haley Scherber --- docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md index dff95064..b3abdc75 100644 --- a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md +++ b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md @@ -87,12 +87,6 @@ Outside of manually attaching Pro to a client machine, Landscape introduced a fe This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. ``` -### Licensing states for clients - -- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management. -- **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. -- **Pro:** Computers that are licensed through Ubuntu Pro. -- **Legacy:** Computers that are licensed through a `license.txt` file. ## Related topics From d1ab0fd317a8f64aa56d7460519e7c3bbf7ed275 Mon Sep 17 00:00:00 2001 From: david-mclain Date: Fri, 17 Oct 2025 02:05:43 -0500 Subject: [PATCH 143/187] reword some stuff --- docs/explanation/landscape/licenses.md | 13 ------------- docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md | 14 +++++++++++--- docs/reference/api/rest-api-endpoints/computers.md | 1 + .../api/rest-api-endpoints/license-management.md | 10 ++++++---- 4 files changed, 18 insertions(+), 20 deletions(-) diff --git a/docs/explanation/landscape/licenses.md b/docs/explanation/landscape/licenses.md index e5dad037..0b8ff3b5 100644 --- a/docs/explanation/landscape/licenses.md +++ b/docs/explanation/landscape/licenses.md @@ -36,16 +36,3 @@ Here’s a summary of the different license types in Landscape and what they ind - **Pro:** License for any client machine that's attached to Ubuntu Pro under an active contract (Physical or Virtual) * These don't require the `license.txt` file to be installed or have available seats on the Landscape server * Requires `landscape-client` 23.x or higher to report the Pro attachment information to the Landscape server - -## License types - -For Landscape Server versions `25.10` and later, there are the following license types. - -```{note} -The **Unlicensed** license type is available for self-hosted 25.10 and later and **select accounts on SaaS**. License management activities associated with this type are unavailable for the Landscape Client snap, Core devices, and offline Client deployments. -``` - -- **Unlicensed:** Computers that are not licensed and cannot be managed outside of license management operations. -- **Free Pro:** Computers that are licensed through an Ubuntu Pro Free Subscription. -- **Pro:** Computers that are licensed through Ubuntu Pro. -- **Legacy:** Computers that are licensed through a `license.txt` file. diff --git a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md index b3abdc75..e4d11d98 100644 --- a/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md +++ b/docs/how-to-guides/ubuntu-pro/attach-ubuntu-pro.md @@ -11,7 +11,7 @@ The following instructions explain how to attach your Ubuntu Pro subscription to Ubuntu Pro isn't just for enterprise customers. Anyone can get [a personal Ubuntu Pro subscription](https://ubuntu.com/pro) for free on up to 5 machines, or 50 if you are an [official Ubuntu Community member](https://wiki.ubuntu.com/Membership). ``` -## Manual attachment +## Manual attachment per-client ### Step 1: Install the Ubuntu Pro Client @@ -79,9 +79,17 @@ Available services can be enabled or disabled on the command line with `pro enab ## Automated attachment across multiple clients -### Ubuntu Pro licensing method +### Step 1: Register clients with landscape server -Outside of manually attaching Pro to a client machine, Landscape introduced a feature to attach Pro to client machines at scale. To do this navigate to `Pro Services` on the `instances` page and select attach pro. This will create an activity on the client machines to attach a pro token and when it succeeds it will properly license the instance. License management activities are only available for `landscape-client` versions `25.08.3` and newer and is not limited to unlicensed instances. For more details see {ref}`reference-rest-api-license-management`. +```{note} +You must be running Landscape Server 25.10 or above and Landscape Client 25.10 or above to use automated attachment on clients for licensing. +``` + +This step will place clients into an unlicensed state where Landscape is aware of the instance to manage Ubuntu Pro. + +### Step 2: Attach Ubuntu Pro to instances. + +Navigate to the instances page and select instances you would like to attach an Ubuntu Pro subscription to. Select `Pro Services` in the UI and select `Attach Token`, then providing your token and selecting `Attach`. This will then send an activity to the client to attach Ubuntu Pro and on success will properly license the instance. ```{note} This feature is available on self-hosted and **select accounts on SaaS**. It is not generally available to all SaaS accounts and the licensing management activities are unavailable for offline client deployments as well as snap and core devices. diff --git a/docs/reference/api/rest-api-endpoints/computers.md b/docs/reference/api/rest-api-endpoints/computers.md index 3b04a795..884fc354 100644 --- a/docs/reference/api/rest-api-endpoints/computers.md +++ b/docs/reference/api/rest-api-endpoints/computers.md @@ -36,6 +36,7 @@ Query parameters: - `contract:`: Instances associated with the specified ``. - `contract-expires-within-days:`: Instances associated with a Ubuntu Pro contract that expires within `` days. - `license-expires-within-days:`: Instances associated with a Legacy License that expires within `` days. + - `has-pro-management: