Merge ~lamoura/ubuntu/+source/ubuntu-advantage-tools:upload-29-mantic into ubuntu/+source/ubuntu-advantage-tools:ubuntu/devel
- Git
- lp:~lamoura/ubuntu/+source/ubuntu-advantage-tools
- upload-29-mantic
- Merge into ubuntu/devel
Status: | Merged |
---|---|
Merge reported by: | Andreas Hasenack |
Merged at revision: | 8380832503fb8750973606fdd2aec380bf63f7ca |
Proposed branch: | ~lamoura/ubuntu/+source/ubuntu-advantage-tools:upload-29-mantic |
Merge into: | ubuntu/+source/ubuntu-advantage-tools:ubuntu/devel |
Diff against target: |
30422 lines (+11104/-4457) 207 files modified
.github/PULL_REQUEST_TEMPLATE.md (+1/-1) .github/actions/bug-refs/index.js (+30/-3) .github/actions/release-changelog-bug-refs/action.yml (+9/-0) .github/actions/release-changelog-bug-refs/index.js (+44/-0) .github/actions/release-changelog-bug-refs/package-lock.json (+430/-0) .github/actions/release-changelog-bug-refs/package.json (+10/-0) .github/workflows/ci-base.yaml (+0/-2) .github/workflows/ci-integration.yaml (+5/-2) .github/workflows/release-checks.yaml (+22/-0) .gitignore (+51/-0) .readthedocs.yaml (+5/-7) CONTRIBUTING.md (+17/-17) README.md (+4/-4) debian/README.source (+38/-0) debian/changelog (+35/-0) debian/control (+2/-2) debian/copyright (+3/-3) debian/source/lintian-overrides (+0/-3) debian/ubuntu-advantage-tools.lintian-overrides (+10/-0) debian/ubuntu-advantage-tools.postinst (+29/-6) debian/ubuntu-advantage-tools.postrm (+1/-1) dev/null (+0/-474) features/_version.feature (+2/-2) features/airgapped.feature (+3/-2) features/anbox.feature (+136/-0) features/api.feature (+2/-2) features/api_fix_plan.feature (+239/-0) features/api_packages.feature (+1/-1) features/api_unattended_upgrades.feature (+1/-1) features/apt_messages.feature (+109/-28) features/attach_invalidtoken.feature (+18/-16) features/attach_validtoken.feature (+4/-3) features/attached_commands.feature (+77/-130) features/attached_enable.feature (+34/-105) features/attached_status.feature (+6/-1) features/collect_logs.feature (+2/-2) features/config.feature (+3/-2) features/daemon.feature (+4/-4) features/environment.py (+25/-8) features/fix.feature (+134/-1) features/i8n.feature (+1/-1) features/install_uninstall.feature (+3/-3) features/landscape.feature (+257/-0) features/livepatch.feature (+4/-4) features/logs.feature (+4/-3) features/magic_attach.feature (+3/-4) features/motd_messages.feature (+2/-1) features/proxy_config.feature (+116/-0) features/schemas/anbox_cloud_credentials.json (+18/-0) features/schemas/cve_fix_plan.json (+91/-0) features/schemas/usn_fix_plan.json (+107/-0) features/security_status.feature (+11/-7) features/steps/files.py (+10/-0) features/steps/landscape.py (+69/-0) features/steps/machines.py (+31/-2) features/steps/output.py (+42/-19) features/steps/packages.py (+4/-5) features/steps/shell.py (+22/-13) features/steps/snap.py (+31/-0) features/steps/ubuntu_advantage_tools.py (+24/-13) features/timer.feature (+3/-2) features/ubuntu_pro.feature (+39/-30) features/ubuntu_pro_fips.feature (+24/-24) features/ubuntu_upgrade.feature (+2/-2) features/ubuntu_upgrade_unattached.feature (+5/-5) features/unattached_commands.feature (+44/-43) features/unattached_status.feature (+68/-31) features/util.py (+56/-11) help_data.yaml (+22/-0) lib/apt_news.py (+1/-3) lib/auto_attach.py (+12/-13) lib/daemon.py (+13/-4) lib/esm_cache.py (+2/-4) lib/patch_status_json.py (+5/-3) lib/reboot_cmds.py (+18/-14) lib/timer.py (+3/-2) lib/upgrade_lts_contract.py (+2/-1) preferences.d/ubuntu-pro-esm-apps (+8/-0) preferences.d/ubuntu-pro-esm-infra (+8/-0) setup.py (+2/-1) sru/README.md (+1/-1) sru/_archive/release-28/azure_auto_attach_on_boot.sh (+108/-0) sru/_archive/release-28/test-esm-infra-key-rename.sh (+78/-0) sru/release-29/test-esm-pinning.sh (+177/-0) tools/build.py (+20/-2) tools/create-lp-release-branches.sh (+1/-1) tools/refresh-keyrings.sh (+2/-2) tools/run-integration-tests.py (+5/-5) tools/setup_sbuild.sh (+1/-1) tools/ua.bash (+2/-2) tox.ini (+5/-8) types-requirements.txt (+1/-0) uaclient/actions.py (+44/-14) uaclient/api/__init__.py (+4/-0) uaclient/api/api.py (+87/-34) uaclient/api/tests/test_api.py (+80/-10) uaclient/api/tests/test_api_u_pro_attach_auto_full_auto_attach_v1.py (+25/-0) uaclient/api/tests/test_api_u_pro_security_status_get_package_manifest.py (+61/-21) uaclient/api/tests/test_api_u_pro_security_status_reboot_required_v1.py (+296/-11) uaclient/api/tests/test_api_u_unattended_upgrades_status_v1.py (+10/-4) uaclient/api/tests/test_fix.py (+833/-0) uaclient/api/u/apt_news/__init__.py (+0/-0) uaclient/api/u/apt_news/current_news/__init__.py (+0/-0) uaclient/api/u/apt_news/current_news/v1.py (+32/-0) uaclient/api/u/pro/attach/auto/full_auto_attach/v1.py (+4/-1) uaclient/api/u/pro/security/fix/__init__.py (+720/-0) uaclient/api/u/pro/security/fix/cve/__init__.py (+0/-0) uaclient/api/u/pro/security/fix/cve/plan/__init__.py (+0/-0) uaclient/api/u/pro/security/fix/cve/plan/v1.py (+88/-0) uaclient/api/u/pro/security/fix/usn/__init__.py (+0/-0) uaclient/api/u/pro/security/fix/usn/plan/__init__.py (+0/-0) uaclient/api/u/pro/security/fix/usn/plan/v1.py (+88/-0) uaclient/api/u/pro/security/status/reboot_required/v1.py (+136/-4) uaclient/api/u/security/package_manifest/v1.py (+3/-3) uaclient/api/u/unattended_upgrades/status/v1.py (+5/-4) uaclient/apt.py (+11/-10) uaclient/apt_news.py (+46/-50) uaclient/cli.py (+80/-47) uaclient/clouds/aws.py (+26/-26) uaclient/clouds/azure.py (+17/-10) uaclient/clouds/gcp.py (+30/-45) uaclient/clouds/identity.py (+5/-3) uaclient/clouds/tests/test_aws.py (+83/-40) uaclient/clouds/tests/test_azure.py (+56/-29) uaclient/clouds/tests/test_gcp.py (+60/-27) uaclient/config.py (+28/-30) uaclient/conftest.py (+21/-6) uaclient/contract.py (+276/-198) uaclient/daemon/__init__.py (+8/-5) uaclient/daemon/poll_for_pro_license.py (+1/-1) uaclient/daemon/retry_auto_attach.py (+6/-20) uaclient/daemon/tests/test_retry_auto_attach.py (+2/-14) uaclient/data_types.py (+1/-1) uaclient/defaults.py (+3/-0) uaclient/entitlements/__init__.py (+4/-0) uaclient/entitlements/anbox.py (+85/-0) uaclient/entitlements/base.py (+154/-11) uaclient/entitlements/cc.py (+1/-1) uaclient/entitlements/cis.py (+1/-1) uaclient/entitlements/esm.py (+2/-2) uaclient/entitlements/fips.py (+3/-6) uaclient/entitlements/landscape.py (+142/-0) uaclient/entitlements/livepatch.py (+18/-50) uaclient/entitlements/realtime.py (+1/-1) uaclient/entitlements/repo.py (+20/-14) uaclient/entitlements/ros.py (+1/-1) uaclient/entitlements/tests/test_base.py (+217/-6) uaclient/entitlements/tests/test_cc.py (+3/-26) uaclient/entitlements/tests/test_cis.py (+1/-17) uaclient/entitlements/tests/test_fips.py (+2/-2) uaclient/entitlements/tests/test_landscape.py (+272/-0) uaclient/entitlements/tests/test_livepatch.py (+35/-92) uaclient/entitlements/tests/test_repo.py (+1/-1) uaclient/exceptions.py (+74/-66) uaclient/files/files.py (+8/-1) uaclient/files/notices.py (+2/-2) uaclient/files/state_files.py (+51/-0) uaclient/gpg.py (+4/-2) uaclient/http/__init__.py (+388/-0) uaclient/http/serviceclient.py (+36/-71) uaclient/http/tests/test_http.py (+461/-0) uaclient/http/tests/test_serviceclient.py (+22/-69) uaclient/livepatch.py (+25/-34) uaclient/lock.py (+2/-2) uaclient/messages.py (+145/-47) uaclient/security.py (+45/-33) uaclient/security_status.py (+4/-61) uaclient/snap.py (+127/-42) uaclient/status.py (+1/-1) uaclient/system.py (+107/-38) uaclient/testing/fakes.py (+11/-4) uaclient/testing/helpers.py (+8/-0) uaclient/tests/test_actions.py (+249/-37) uaclient/tests/test_apt.py (+14/-14) uaclient/tests/test_apt_news.py (+151/-151) uaclient/tests/test_cli.py (+29/-202) uaclient/tests/test_cli_api.py (+19/-2) uaclient/tests/test_cli_attach.py (+47/-67) uaclient/tests/test_cli_auto_attach.py (+5/-3) uaclient/tests/test_cli_collect_logs.py (+2/-1) uaclient/tests/test_cli_config.py (+1/-1) uaclient/tests/test_cli_config_set.py (+13/-13) uaclient/tests/test_cli_disable.py (+8/-3) uaclient/tests/test_cli_enable.py (+33/-15) uaclient/tests/test_cli_refresh.py (+14/-16) uaclient/tests/test_cli_status.py (+5/-4) uaclient/tests/test_config.py (+25/-19) uaclient/tests/test_contract.py (+844/-584) uaclient/tests/test_esm_cache.py (+13/-10) uaclient/tests/test_gpg.py (+2/-2) uaclient/tests/test_lib_auto_attach.py (+1/-8) uaclient/tests/test_livepatch.py (+89/-13) uaclient/tests/test_log.py (+4/-3) uaclient/tests/test_security.py (+67/-24) uaclient/tests/test_security_status.py (+5/-170) uaclient/tests/test_snap.py (+194/-73) uaclient/tests/test_status.py (+13/-1) uaclient/tests/test_system.py (+215/-23) uaclient/tests/test_util.py (+74/-279) uaclient/timer/__init__.py (+2/-2) uaclient/timer/tests/test_update_messaging.py (+3/-6) uaclient/timer/update_contract_info.py (+1/-1) uaclient/timer/update_messaging.py (+16/-51) uaclient/upgrade_lts_contract.py (+11/-8) uaclient/util.py (+34/-152) uaclient/version.py (+1/-1) uaclient/yaml.py (+6/-3) |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Robie Basak | Needs Fixing | ||
Sergio Durigan Junior (community) | Approve | ||
Canonical Server Reporter | Pending | ||
Review via email: mp+448239@code.launchpad.net |
Commit message
Description of the change
Release version 29 for ubuntu-
More information can be found on the following SRU bug:
https:/
See the CHANGELOG and related bugs for more information.
Lucas Albuquerque Medeiros de Moura (lamoura) wrote : | # |
Sergio Durigan Junior (sergiodj) wrote : | # |
Thank you, Lucas.
Here's my review. I focused on the Debian packaging stuff, but also tried to review the overall changes to the source code. Also, some of the points I raise below can be considered nitpicky/wishlist.
## dep8 tests
Before I forget: I triggered the dep8 tests for Mantic. Here's the result:
Results: (from http://
ubuntu-
02.08.23 19:27:59 Log 🗒️ ✅ Triggers: ubuntu-
ubuntu-
02.08.23 19:48:24 Log 🗒️ ✅ Triggers: ubuntu-
ubuntu-
02.08.23 19:23:09 Log 🗒️ ✅ Triggers: ubuntu-
ubuntu-
02.08.23 20:17:12 Log 🗒️ ✅ Triggers: ubuntu-
ubuntu-
02.08.23 19:36:43 Log 🗒️ ✅ Triggers: ubuntu-
## lintian messages
I noticed that you do read the lintian messages (good!) and take care to handle them when needed, so I decided to comment on some of the existing messages that I believe could be addressed as well.
- maintainer-
- possible-
- command-
- package-
- systemd-
There are two override flags that can probably be dropped (invalid-
## d/changelog
- The new README file is called d/README.source (you missed the ".source" suffix).
- Typo: subsctiption
- The text after "- proxy:" starts with a capital "A". It should follow the convention and start with lowercase "a".
- Nitpick: you might also mention the d/copyright update here, just for completeness sake. No need to rebase the branch just for that, though.
I still have to look deeper into the contents of d/changelog vs. the commits.
## d/README.source
LGTM, but I have a question:
- According to the discussion on https:/
## d/*postinst
- Nitpick: you co...
- ac83297... by Renan Rodrigo
-
d/changelog: fix typos and add missing d/copyright entry
Signed-off-by: Renan Rodrigo <email address hidden>
- 097d33b... by Renan Rodrigo
-
chore: tweak messages in the preferences files
Following release review suggestions
Signed-off-by: Renan Rodrigo <email address hidden>
Renan Rodrigo (renanrodrigo) wrote : | # |
Hello, sergiodj, thanks much for this first round of feedback - appreciated.
So,
> - According to the discussion on https:/
Sorry, this is on me - I updated the Jira ticket, but not the (public and available) GH issue :/
We have decided to completely remove the documentation bits from the tarball, so anyone packaging/
- 8137d60... by Lucas Albuquerque Medeiros de Moura
-
lintian: add overrides to some known warnings
- 3b619ce... by Lucas Albuquerque Medeiros de Moura
-
postinst: change systemctl to deb-systemd-invoke
Calling systemctl on the postinst script generates a lintian warning.
We are replacing it for deb-systemd-invoke to silence it - 8380832... by Lucas Albuquerque Medeiros de Moura
-
postinst: use for loop to rename gpg keys
Sergio Durigan Junior (sergiodj) wrote : | # |
> Hello, sergiodj, thanks much for this first round of feedback - appreciated.
>
> So,
>
> > - According to the discussion on https:/
> client/issues/2463, you had decided to keep the documentation bits as part of
> the tarball but mention that they're not actually used to generate the binary
> package. However, df505d4643a20a7
> that you decided to move the documentation out of the tarball. Is that
> correct? Is this why I don't see a mention to the documentation part in the
> "Particularities" section here?
>
> Sorry, this is on me - I updated the Jira ticket, but not the (public and
> available) GH issue :/
> We have decided to completely remove the documentation bits from the tarball,
> so anyone packaging/
> process. We would include it in the readme if we had decided to keep those
> around, but given we removed it, we also don't mention it in the readme.
Thanks for the reply and for clarifying this part, Renan.
Lucas Albuquerque Medeiros de Moura (lamoura) wrote : | # |
Hi Sergio,
Thanks for the review. I have updated the MR addressing all of the suggested changes.
Regarding b33fb5e3, this is an issue generated by a previous release. What I did was at least to remove the duplicated code generated by it.
But please let me know if you identify anything else that needs improvement/
Sergio Durigan Junior (sergiodj) wrote : | # |
Thank you, Lucas et al.
I did a second pass to verify the points that I raised, and confirmed that they've been properly addressed.
Everything else LGTM, so I'm approving this MP and uploading the package. Thank you again!
$ dput ubuntu-
Trying to upload package to ubuntu
Checking signature on .changes
gpg: /home/sergio/
Checking signature on .dsc
gpg: /home/sergio/
Uploading to ubuntu (via ftp to upload.ubuntu.com):
Uploading ubuntu-
Uploading ubuntu-
Uploading ubuntu-
Uploading ubuntu-
Successfully uploaded packages.
Robie Basak (racb) wrote : | # |
> b33fb5e3 lock: alert the user about corrupted lock
[Comment only] This seems to have no relation to the change, and the referenced bug is already fixed?
> 31572946 refactor: implementation-
[Comment only] On what you describe in the commit message: in Python, I'm dubious about failures being presented by return codes instead of via exceptions. It's not the normal pattern, and thus seems error-prone in that a caller is more likely to fail to check and for that to be missed in future reviews.
> 296edca3 chore: rename repo GPG keys from -advantage to -pro
> 83808325 postinst: use for loop to rename gpg keys
[Comment only] I'm not sure why this is labelled as "chore". I don't subscribe to "semantic commit messages" but even then this is absolutely a user-visible change!
[Needs Information] Why are we renaming these keys at all? We're not renaming the package name, and the prefix /etc/apt/
> 7c2f481b http: use pycurl for tls-in-tls requests
[Comment only]
Note that you are depending on ca-certificates (due to /etc/ssl/
IIRC this is also an issue for plain Python SSL. I remember it coming up but don't remember how we handled it. It might be worth verifying that there are tests to ensure that behaviour is reasonable when ca-certificates is not installed - both for the Python and pycurl cases.
> fead7d19 contract: support requiredPackages directive
[Needs Information] Under what circumstances are these directives provided? Just when a service is being enabled, or is it wider than this?
> c2a7f7ab landscape: support enabling and disabling landscape-client
[Comment only] I asked why is help_data.yaml in /etc, and understand that you are planning to move it out.
> 1162f56f esm: pin repositories to a higher priority using static files
> 21c28f36 esm: add comment to preference files
> 097d33bf chore: tweak messages in the preferences files
[Needs Fixing]
1. Could you please add a test to ensure that a regular archive package not from ESM remains *not* pinned (ie. priority 500)? Unless I'm missing something, I looked at features/
Sergio Durigan Junior (sergiodj) wrote : | # |
On Thursday, August 17 2023, Robie Basak wrote:
>> 3b619ce9 postinst: change systemctl to deb-systemd-invoke
>
> [Needs Information]
>
> Did you do this because lintian told you to? deb-systemd-invoke is
> documented as only supporting start|stop|restart and I'm not sure
> policy-rc.d makes sense for daemon-reload or reset-failed anyway. But
> I tested this on Mantic and it seems to work. I'm OK with the change,
> but as it's in a less common upgrade path, do we have an ongoing test
> that validates that it will work into the future please? Alternatively
> this seems like a lintian bug that should allow "--system
> daemon-reload" and "reset-failed" and might be worth a bug report (and
> additionally a blanket "use deb-systemd-invoke" claim contradicts the
> command's own usage notice that only permits it for
> start|stop|
> already[1]. See also the scoped overrides I mentioned above.
>
> Please either: 1) defer the change; or 2) ensure an ongoing test exists for the purposes of exercising this code path (this might already exist; I didn't check; if you say there is one then that's good enough for me).
>
> I suggest also specific lintian overrides and a bug to lintian upstream.
>
> [1] https:/
Hey Robie,
Thanks for the extra review. This change was done because of a request
I made after building the package noticing the lintian warning.
My rationale here is that even though "deb-systemd-
explicitly document support actions other than start|stop|restart, there
is code in place to support deferring any other command to "systemctl"
directly:
https:/
This code (or other versions of it) has been there since the start, so
we should be covered when dealing with Xenial.
It is indeed arguable whether "deb-systemd-
for the actions mentioned above; the manpage's SYNOPSIS indicates that,
but the DESCRIPTION is more generic and doesn't impose the same limits.
Anyway, this is a really small change and I'm absolutely fine if Lucas
decides to revert it, although he also told me that they do have tests
to cover this code path, but I will let him elaborate more on that.
Thanks,
--
Sergio
GPG key ID: E92F D0B3 6B14 F1F4 D8E0 EB2F 106D A1C8 C3CB BF14
Lucas Albuquerque Medeiros de Moura (lamoura) wrote : | # |
Hi Robie, thanks for the review.
Let me address all of the comments here:
> b33fb5e3 lock: alert the user about corrupted lock
This commit is just trying to fix a rebase issue we had in the past. It just deletes duplicated lines on the messages module. It is not ideal, but I think this can be ignored for the release.
> 31572946 refactor: implementation-
Yes, since the libraries we support now have those differences between how they raise the exception, we have tried to follow a pattern similar to what request does:
https:/
But we understand that we need to be careful on the review regarding new code that perform any type of requests
> 296edca3 chore: rename repo GPG keys from -advantage to -pro
> 83808325 postinst: use for loop to rename gpg keys
> Why are we renaming these keys at all?
we plan to rename the package before 24.04 and we are already addressing some parts of the code earlier, to make this change more incremental.
> And there are further complications: these are in /etc, so could be modified or removed by users, so we have to consider that type of case - at least to review to ensure that the maintainer scripts cannot explode. Further, even though mv_conffile is not appropriate in this case, it demonstrates the error rollbacks that are not implemented here, so a failure somewhere else in the postinst could lead to a user's system ending up in a broken state due to this part not being rolled back correctly, and that requires further thought, review and possible implementation. Is this worth the regression risk and review effort?
Regarding user modifications, I believe we shouldn't worry. Those files are only created once the service is enabled and the key there isn unique for each service. Therefore, modifications are definitely unsupported.
Regarding failures, the only impact is that we will end up with a key that was not renamed. In that situation, the service will still work as expected and the only side-effect is that during disable, we will
not remove the old key. But I will of course create a test script that demonstrate that
> 7c2f481b http: use pycurl for tls-in-tls requests
Great catch, we need to better alert the user about ca-certificates. I will add a commit addressing this.
> fead7d19 contract: support requiredPackages directive
[Needs Information] Under what circumstances are these directives provided? Just when a service is being enabled, or is it wider than this?
We will only read and act upon this directive when a service is enabled. Also this directive is currently only present for the Landscape service
[Needs Fixing]
Yes, I will update the test and update the comment on the pin file too
Andreas Hasenack (ahasenack) wrote : | # |
Some version of this eventually landed in mantic-proposed[1], but was superseeded by multiple follow-up uploads.
I'll mark this MP as merged due to that.
1. https:/
Preview Diff
1 | diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md |
2 | index 7faa407..a652232 100644 |
3 | --- a/.github/PULL_REQUEST_TEMPLATE.md |
4 | +++ b/.github/PULL_REQUEST_TEMPLATE.md |
5 | @@ -45,7 +45,7 @@ sudo pro new-sub-command --new-flag |
6 | that apply. --> |
7 | - [ ] I have updated or added any unit tests accordingly |
8 | - [ ] I have updated or added any integration tests accordingly |
9 | - - [ ] I have updated or added any documentation accordingly |
10 | + - [ ] Changes here need to be documented, and this was done in: <!-- Insert PR number here if the box is checked (ex. #1234) --> |
11 | |
12 | ## Does this PR require extra reviews? |
13 | <!-- Should people outside of the team see and approve these changes before the |
14 | diff --git a/.github/actions/bug-refs/index.js b/.github/actions/bug-refs/index.js |
15 | index b603793..c873aca 100644 |
16 | --- a/.github/actions/bug-refs/index.js |
17 | +++ b/.github/actions/bug-refs/index.js |
18 | @@ -3,7 +3,7 @@ const github = require('@actions/github'); |
19 | |
20 | const commentHeader = "<!-- ubuntu-pro-client-bug-refs -->"; |
21 | |
22 | -function createCommentBody(commits, title) { |
23 | +function createCommentBody(commits, title, body) { |
24 | let newComment = ""; |
25 | newComment += commentHeader; |
26 | newComment += "\n"; |
27 | @@ -49,6 +49,19 @@ function createCommentBody(commits, title) { |
28 | } |
29 | newComment += "\n"; |
30 | |
31 | + newComment += "Documentation:"; |
32 | + if (!body.includes('[x] Changes here need to be documented')){ |
33 | + newComment += " The changes in this PR do not require documentation changes."; |
34 | + } else { |
35 | + docsPullMatch = body.match(/and this was done in: (#\d+)/) |
36 | + if (docsPullMatch){ |
37 | + newComment += ` Documentation changes addressed in ${docsPullMatch[1]}`; |
38 | + } else { |
39 | + newComment += " The changes in this PR do require documentation changes, but those were not addressed yet."; |
40 | + } |
41 | + } |
42 | + newComment += "\n\n"; |
43 | + |
44 | newComment += "👍 this comment to confirm that this is correct."; |
45 | |
46 | return newComment; |
47 | @@ -80,7 +93,11 @@ async function run() { |
48 | if (theComment) { |
49 | // comment already exists, update it appropriately |
50 | const existingBody = theComment.body; |
51 | - const newBody = createCommentBody(commits.data, context.payload.pull_request.title); |
52 | + const newBody = createCommentBody( |
53 | + commits.data, |
54 | + context.payload.pull_request.title, |
55 | + context.payload.pull_request.body |
56 | + ); |
57 | if (existingBody !== newBody) { |
58 | client.rest.issues.updateComment({ |
59 | owner: context.issue.owner, |
60 | @@ -91,13 +108,23 @@ async function run() { |
61 | } |
62 | } else { |
63 | // first run, comment doesn't exist yet |
64 | - const newBody = createCommentBody(commits.data, context.payload.pull_request.title); |
65 | + const newBody = createCommentBody( |
66 | + commits.data, |
67 | + context.payload.pull_request.title, |
68 | + context.payload.pull_request.body |
69 | + ); |
70 | client.rest.issues.createComment({ |
71 | owner: context.issue.owner, |
72 | repo: context.issue.repo, |
73 | issue_number: context.issue.number, |
74 | body: newBody, |
75 | }); |
76 | + client.rest.reactions.createForIssue({ |
77 | + owner: context.issue.owner, |
78 | + repo: context.issue.repo, |
79 | + issue_number: context.issue.number, |
80 | + content: "eyes" |
81 | + }); |
82 | } |
83 | } |
84 | |
85 | diff --git a/.github/actions/release-changelog-bug-refs/action.yml b/.github/actions/release-changelog-bug-refs/action.yml |
86 | new file mode 100644 |
87 | index 0000000..edd4ca1 |
88 | --- /dev/null |
89 | +++ b/.github/actions/release-changelog-bug-refs/action.yml |
90 | @@ -0,0 +1,9 @@ |
91 | +name: 'Ensure Release Changelog has Bug References' |
92 | +description: "Block releases if bug references in commits aren't in the proposed changelog entry" |
93 | +inputs: |
94 | + repo-token: |
95 | + description: 'Token for the repository. Can be passed in using {{ secrets.GITHUB_TOKEN }}' |
96 | + required: true |
97 | +runs: |
98 | + using: 'node16' |
99 | + main: 'index.js' |
100 | diff --git a/.github/actions/release-changelog-bug-refs/index.js b/.github/actions/release-changelog-bug-refs/index.js |
101 | new file mode 100644 |
102 | index 0000000..5c8a494 |
103 | --- /dev/null |
104 | +++ b/.github/actions/release-changelog-bug-refs/index.js |
105 | @@ -0,0 +1,44 @@ |
106 | +const fs = require('fs/promises'); |
107 | +const core = require('@actions/core'); |
108 | +const github = require('@actions/github'); |
109 | + |
110 | +async function run() { |
111 | + const context = github.context; |
112 | + if (context.eventName !== "pull_request") { |
113 | + console.log( |
114 | + 'The event that triggered this action was not a pull request, skipping.' |
115 | + ); |
116 | + return; |
117 | + } |
118 | + |
119 | + const client = github.getOctokit( |
120 | + core.getInput('repo-token', {required: true}) |
121 | + ); |
122 | + const commits = await client.rest.pulls.listCommits({ |
123 | + owner: context.issue.owner, |
124 | + repo: context.issue.repo, |
125 | + pull_number: context.issue.number, |
126 | + }); |
127 | + let lpBugs = []; |
128 | + let ghIssues = []; |
129 | + commits.data.forEach(commit => { |
130 | + const message = commit.commit.message.toLocaleUpperCase(); |
131 | + lpBugs = lpBugs.concat(Array.from(message.matchAll(/LP: #(\d+)/g)).map(m => m[1])); |
132 | + ghIssues = ghIssues.concat(Array.from(message.matchAll(/FIXES: #(\d+)/g)).map(m => m[1])); |
133 | + ghIssues = ghIssues.concat(Array.from(message.matchAll(/CLOSES: #(\d+)/g)).map(m => m[1])); |
134 | + }); |
135 | + const changelog = await fs.readFile("./debian/changelog", { encoding: "utf8" }); |
136 | + const changelogEntries = changelog.split("ubuntu-advantage-tools"); |
137 | + const newEntry = changelogEntries[1]; |
138 | + const missingLpBugs = lpBugs.filter(bug => !newEntry.includes(`LP: #${bug}`)); |
139 | + const missingGhIssues = ghIssues.filter(issue => !newEntry.includes(`GH: #${issue}`)); |
140 | + |
141 | + if (missingLpBugs.length > 0 || missingGhIssues.length > 0) { |
142 | + core.setFailed({ missingLpBugs, missingGhIssues }); |
143 | + } |
144 | +} |
145 | + |
146 | +run().catch(error => { |
147 | + console.error(error); |
148 | + core.setFailed(error.message); |
149 | +}) |
150 | diff --git a/.github/actions/release-changelog-bug-refs/package-lock.json b/.github/actions/release-changelog-bug-refs/package-lock.json |
151 | new file mode 100644 |
152 | index 0000000..f9ad26b |
153 | --- /dev/null |
154 | +++ b/.github/actions/release-changelog-bug-refs/package-lock.json |
155 | @@ -0,0 +1,430 @@ |
156 | +{ |
157 | + "name": "bug-refs", |
158 | + "version": "1.0.0", |
159 | + "lockfileVersion": 2, |
160 | + "requires": true, |
161 | + "packages": { |
162 | + "": { |
163 | + "name": "bug-refs", |
164 | + "version": "1.0.0", |
165 | + "dependencies": { |
166 | + "@actions/core": "^1.10.0", |
167 | + "@actions/github": "^5.1.1" |
168 | + } |
169 | + }, |
170 | + "node_modules/@actions/core": { |
171 | + "version": "1.10.0", |
172 | + "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz", |
173 | + "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==", |
174 | + "dependencies": { |
175 | + "@actions/http-client": "^2.0.1", |
176 | + "uuid": "^8.3.2" |
177 | + } |
178 | + }, |
179 | + "node_modules/@actions/github": { |
180 | + "version": "5.1.1", |
181 | + "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.1.1.tgz", |
182 | + "integrity": "sha512-Nk59rMDoJaV+mHCOJPXuvB1zIbomlKS0dmSIqPGxd0enAXBnOfn4VWF+CGtRCwXZG9Epa54tZA7VIRlJDS8A6g==", |
183 | + "dependencies": { |
184 | + "@actions/http-client": "^2.0.1", |
185 | + "@octokit/core": "^3.6.0", |
186 | + "@octokit/plugin-paginate-rest": "^2.17.0", |
187 | + "@octokit/plugin-rest-endpoint-methods": "^5.13.0" |
188 | + } |
189 | + }, |
190 | + "node_modules/@actions/http-client": { |
191 | + "version": "2.1.0", |
192 | + "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.1.0.tgz", |
193 | + "integrity": "sha512-BonhODnXr3amchh4qkmjPMUO8mFi/zLaaCeCAJZqch8iQqyDnVIkySjB38VHAC8IJ+bnlgfOqlhpyCUZHlQsqw==", |
194 | + "dependencies": { |
195 | + "tunnel": "^0.0.6" |
196 | + } |
197 | + }, |
198 | + "node_modules/@octokit/auth-token": { |
199 | + "version": "2.5.0", |
200 | + "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.5.0.tgz", |
201 | + "integrity": "sha512-r5FVUJCOLl19AxiuZD2VRZ/ORjp/4IN98Of6YJoJOkY75CIBuYfmiNHGrDwXr+aLGG55igl9QrxX3hbiXlLb+g==", |
202 | + "dependencies": { |
203 | + "@octokit/types": "^6.0.3" |
204 | + } |
205 | + }, |
206 | + "node_modules/@octokit/core": { |
207 | + "version": "3.6.0", |
208 | + "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.6.0.tgz", |
209 | + "integrity": "sha512-7RKRKuA4xTjMhY+eG3jthb3hlZCsOwg3rztWh75Xc+ShDWOfDDATWbeZpAHBNRpm4Tv9WgBMOy1zEJYXG6NJ7Q==", |
210 | + "dependencies": { |
211 | + "@octokit/auth-token": "^2.4.4", |
212 | + "@octokit/graphql": "^4.5.8", |
213 | + "@octokit/request": "^5.6.3", |
214 | + "@octokit/request-error": "^2.0.5", |
215 | + "@octokit/types": "^6.0.3", |
216 | + "before-after-hook": "^2.2.0", |
217 | + "universal-user-agent": "^6.0.0" |
218 | + } |
219 | + }, |
220 | + "node_modules/@octokit/endpoint": { |
221 | + "version": "6.0.12", |
222 | + "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz", |
223 | + "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==", |
224 | + "dependencies": { |
225 | + "@octokit/types": "^6.0.3", |
226 | + "is-plain-object": "^5.0.0", |
227 | + "universal-user-agent": "^6.0.0" |
228 | + } |
229 | + }, |
230 | + "node_modules/@octokit/graphql": { |
231 | + "version": "4.8.0", |
232 | + "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.8.0.tgz", |
233 | + "integrity": "sha512-0gv+qLSBLKF0z8TKaSKTsS39scVKF9dbMxJpj3U0vC7wjNWFuIpL/z76Qe2fiuCbDRcJSavkXsVtMS6/dtQQsg==", |
234 | + "dependencies": { |
235 | + "@octokit/request": "^5.6.0", |
236 | + "@octokit/types": "^6.0.3", |
237 | + "universal-user-agent": "^6.0.0" |
238 | + } |
239 | + }, |
240 | + "node_modules/@octokit/openapi-types": { |
241 | + "version": "12.11.0", |
242 | + "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-12.11.0.tgz", |
243 | + "integrity": "sha512-VsXyi8peyRq9PqIz/tpqiL2w3w80OgVMwBHltTml3LmVvXiphgeqmY9mvBw9Wu7e0QWk/fqD37ux8yP5uVekyQ==" |
244 | + }, |
245 | + "node_modules/@octokit/plugin-paginate-rest": { |
246 | + "version": "2.21.3", |
247 | + "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.21.3.tgz", |
248 | + "integrity": "sha512-aCZTEf0y2h3OLbrgKkrfFdjRL6eSOo8komneVQJnYecAxIej7Bafor2xhuDJOIFau4pk0i/P28/XgtbyPF0ZHw==", |
249 | + "dependencies": { |
250 | + "@octokit/types": "^6.40.0" |
251 | + }, |
252 | + "peerDependencies": { |
253 | + "@octokit/core": ">=2" |
254 | + } |
255 | + }, |
256 | + "node_modules/@octokit/plugin-rest-endpoint-methods": { |
257 | + "version": "5.16.2", |
258 | + "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.16.2.tgz", |
259 | + "integrity": "sha512-8QFz29Fg5jDuTPXVtey05BLm7OB+M8fnvE64RNegzX7U+5NUXcOcnpTIK0YfSHBg8gYd0oxIq3IZTe9SfPZiRw==", |
260 | + "dependencies": { |
261 | + "@octokit/types": "^6.39.0", |
262 | + "deprecation": "^2.3.1" |
263 | + }, |
264 | + "peerDependencies": { |
265 | + "@octokit/core": ">=3" |
266 | + } |
267 | + }, |
268 | + "node_modules/@octokit/request": { |
269 | + "version": "5.6.3", |
270 | + "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.3.tgz", |
271 | + "integrity": "sha512-bFJl0I1KVc9jYTe9tdGGpAMPy32dLBXXo1dS/YwSCTL/2nd9XeHsY616RE3HPXDVk+a+dBuzyz5YdlXwcDTr2A==", |
272 | + "dependencies": { |
273 | + "@octokit/endpoint": "^6.0.1", |
274 | + "@octokit/request-error": "^2.1.0", |
275 | + "@octokit/types": "^6.16.1", |
276 | + "is-plain-object": "^5.0.0", |
277 | + "node-fetch": "^2.6.7", |
278 | + "universal-user-agent": "^6.0.0" |
279 | + } |
280 | + }, |
281 | + "node_modules/@octokit/request-error": { |
282 | + "version": "2.1.0", |
283 | + "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz", |
284 | + "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==", |
285 | + "dependencies": { |
286 | + "@octokit/types": "^6.0.3", |
287 | + "deprecation": "^2.0.0", |
288 | + "once": "^1.4.0" |
289 | + } |
290 | + }, |
291 | + "node_modules/@octokit/types": { |
292 | + "version": "6.41.0", |
293 | + "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.41.0.tgz", |
294 | + "integrity": "sha512-eJ2jbzjdijiL3B4PrSQaSjuF2sPEQPVCPzBvTHJD9Nz+9dw2SGH4K4xeQJ77YfTq5bRQ+bD8wT11JbeDPmxmGg==", |
295 | + "dependencies": { |
296 | + "@octokit/openapi-types": "^12.11.0" |
297 | + } |
298 | + }, |
299 | + "node_modules/before-after-hook": { |
300 | + "version": "2.2.3", |
301 | + "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz", |
302 | + "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ==" |
303 | + }, |
304 | + "node_modules/deprecation": { |
305 | + "version": "2.3.1", |
306 | + "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz", |
307 | + "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ==" |
308 | + }, |
309 | + "node_modules/is-plain-object": { |
310 | + "version": "5.0.0", |
311 | + "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz", |
312 | + "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==", |
313 | + "engines": { |
314 | + "node": ">=0.10.0" |
315 | + } |
316 | + }, |
317 | + "node_modules/node-fetch": { |
318 | + "version": "2.6.9", |
319 | + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.9.tgz", |
320 | + "integrity": "sha512-DJm/CJkZkRjKKj4Zi4BsKVZh3ValV5IR5s7LVZnW+6YMh0W1BfNA8XSs6DLMGYlId5F3KnA70uu2qepcR08Qqg==", |
321 | + "dependencies": { |
322 | + "whatwg-url": "^5.0.0" |
323 | + }, |
324 | + "engines": { |
325 | + "node": "4.x || >=6.0.0" |
326 | + }, |
327 | + "peerDependencies": { |
328 | + "encoding": "^0.1.0" |
329 | + }, |
330 | + "peerDependenciesMeta": { |
331 | + "encoding": { |
332 | + "optional": true |
333 | + } |
334 | + } |
335 | + }, |
336 | + "node_modules/once": { |
337 | + "version": "1.4.0", |
338 | + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", |
339 | + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", |
340 | + "dependencies": { |
341 | + "wrappy": "1" |
342 | + } |
343 | + }, |
344 | + "node_modules/tr46": { |
345 | + "version": "0.0.3", |
346 | + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", |
347 | + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" |
348 | + }, |
349 | + "node_modules/tunnel": { |
350 | + "version": "0.0.6", |
351 | + "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz", |
352 | + "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==", |
353 | + "engines": { |
354 | + "node": ">=0.6.11 <=0.7.0 || >=0.7.3" |
355 | + } |
356 | + }, |
357 | + "node_modules/universal-user-agent": { |
358 | + "version": "6.0.0", |
359 | + "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz", |
360 | + "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w==" |
361 | + }, |
362 | + "node_modules/uuid": { |
363 | + "version": "8.3.2", |
364 | + "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz", |
365 | + "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==", |
366 | + "bin": { |
367 | + "uuid": "dist/bin/uuid" |
368 | + } |
369 | + }, |
370 | + "node_modules/webidl-conversions": { |
371 | + "version": "3.0.1", |
372 | + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", |
373 | + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" |
374 | + }, |
375 | + "node_modules/whatwg-url": { |
376 | + "version": "5.0.0", |
377 | + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", |
378 | + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", |
379 | + "dependencies": { |
380 | + "tr46": "~0.0.3", |
381 | + "webidl-conversions": "^3.0.0" |
382 | + } |
383 | + }, |
384 | + "node_modules/wrappy": { |
385 | + "version": "1.0.2", |
386 | + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", |
387 | + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==" |
388 | + } |
389 | + }, |
390 | + "dependencies": { |
391 | + "@actions/core": { |
392 | + "version": "1.10.0", |
393 | + "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz", |
394 | + "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==", |
395 | + "requires": { |
396 | + "@actions/http-client": "^2.0.1", |
397 | + "uuid": "^8.3.2" |
398 | + } |
399 | + }, |
400 | + "@actions/github": { |
401 | + "version": "5.1.1", |
402 | + "resolved": "https://registry.npmjs.org/@actions/github/-/github-5.1.1.tgz", |
403 | + "integrity": "sha512-Nk59rMDoJaV+mHCOJPXuvB1zIbomlKS0dmSIqPGxd0enAXBnOfn4VWF+CGtRCwXZG9Epa54tZA7VIRlJDS8A6g==", |
404 | + "requires": { |
405 | + "@actions/http-client": "^2.0.1", |
406 | + "@octokit/core": "^3.6.0", |
407 | + "@octokit/plugin-paginate-rest": "^2.17.0", |
408 | + "@octokit/plugin-rest-endpoint-methods": "^5.13.0" |
409 | + } |
410 | + }, |
411 | + "@actions/http-client": { |
412 | + "version": "2.1.0", |
413 | + "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.1.0.tgz", |
414 | + "integrity": "sha512-BonhODnXr3amchh4qkmjPMUO8mFi/zLaaCeCAJZqch8iQqyDnVIkySjB38VHAC8IJ+bnlgfOqlhpyCUZHlQsqw==", |
415 | + "requires": { |
416 | + "tunnel": "^0.0.6" |
417 | + } |
418 | + }, |
419 | + "@octokit/auth-token": { |
420 | + "version": "2.5.0", |
421 | + "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-2.5.0.tgz", |
422 | + "integrity": "sha512-r5FVUJCOLl19AxiuZD2VRZ/ORjp/4IN98Of6YJoJOkY75CIBuYfmiNHGrDwXr+aLGG55igl9QrxX3hbiXlLb+g==", |
423 | + "requires": { |
424 | + "@octokit/types": "^6.0.3" |
425 | + } |
426 | + }, |
427 | + "@octokit/core": { |
428 | + "version": "3.6.0", |
429 | + "resolved": "https://registry.npmjs.org/@octokit/core/-/core-3.6.0.tgz", |
430 | + "integrity": "sha512-7RKRKuA4xTjMhY+eG3jthb3hlZCsOwg3rztWh75Xc+ShDWOfDDATWbeZpAHBNRpm4Tv9WgBMOy1zEJYXG6NJ7Q==", |
431 | + "requires": { |
432 | + "@octokit/auth-token": "^2.4.4", |
433 | + "@octokit/graphql": "^4.5.8", |
434 | + "@octokit/request": "^5.6.3", |
435 | + "@octokit/request-error": "^2.0.5", |
436 | + "@octokit/types": "^6.0.3", |
437 | + "before-after-hook": "^2.2.0", |
438 | + "universal-user-agent": "^6.0.0" |
439 | + } |
440 | + }, |
441 | + "@octokit/endpoint": { |
442 | + "version": "6.0.12", |
443 | + "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-6.0.12.tgz", |
444 | + "integrity": "sha512-lF3puPwkQWGfkMClXb4k/eUT/nZKQfxinRWJrdZaJO85Dqwo/G0yOC434Jr2ojwafWJMYqFGFa5ms4jJUgujdA==", |
445 | + "requires": { |
446 | + "@octokit/types": "^6.0.3", |
447 | + "is-plain-object": "^5.0.0", |
448 | + "universal-user-agent": "^6.0.0" |
449 | + } |
450 | + }, |
451 | + "@octokit/graphql": { |
452 | + "version": "4.8.0", |
453 | + "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-4.8.0.tgz", |
454 | + "integrity": "sha512-0gv+qLSBLKF0z8TKaSKTsS39scVKF9dbMxJpj3U0vC7wjNWFuIpL/z76Qe2fiuCbDRcJSavkXsVtMS6/dtQQsg==", |
455 | + "requires": { |
456 | + "@octokit/request": "^5.6.0", |
457 | + "@octokit/types": "^6.0.3", |
458 | + "universal-user-agent": "^6.0.0" |
459 | + } |
460 | + }, |
461 | + "@octokit/openapi-types": { |
462 | + "version": "12.11.0", |
463 | + "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-12.11.0.tgz", |
464 | + "integrity": "sha512-VsXyi8peyRq9PqIz/tpqiL2w3w80OgVMwBHltTml3LmVvXiphgeqmY9mvBw9Wu7e0QWk/fqD37ux8yP5uVekyQ==" |
465 | + }, |
466 | + "@octokit/plugin-paginate-rest": { |
467 | + "version": "2.21.3", |
468 | + "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-2.21.3.tgz", |
469 | + "integrity": "sha512-aCZTEf0y2h3OLbrgKkrfFdjRL6eSOo8komneVQJnYecAxIej7Bafor2xhuDJOIFau4pk0i/P28/XgtbyPF0ZHw==", |
470 | + "requires": { |
471 | + "@octokit/types": "^6.40.0" |
472 | + } |
473 | + }, |
474 | + "@octokit/plugin-rest-endpoint-methods": { |
475 | + "version": "5.16.2", |
476 | + "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-5.16.2.tgz", |
477 | + "integrity": "sha512-8QFz29Fg5jDuTPXVtey05BLm7OB+M8fnvE64RNegzX7U+5NUXcOcnpTIK0YfSHBg8gYd0oxIq3IZTe9SfPZiRw==", |
478 | + "requires": { |
479 | + "@octokit/types": "^6.39.0", |
480 | + "deprecation": "^2.3.1" |
481 | + } |
482 | + }, |
483 | + "@octokit/request": { |
484 | + "version": "5.6.3", |
485 | + "resolved": "https://registry.npmjs.org/@octokit/request/-/request-5.6.3.tgz", |
486 | + "integrity": "sha512-bFJl0I1KVc9jYTe9tdGGpAMPy32dLBXXo1dS/YwSCTL/2nd9XeHsY616RE3HPXDVk+a+dBuzyz5YdlXwcDTr2A==", |
487 | + "requires": { |
488 | + "@octokit/endpoint": "^6.0.1", |
489 | + "@octokit/request-error": "^2.1.0", |
490 | + "@octokit/types": "^6.16.1", |
491 | + "is-plain-object": "^5.0.0", |
492 | + "node-fetch": "^2.6.7", |
493 | + "universal-user-agent": "^6.0.0" |
494 | + } |
495 | + }, |
496 | + "@octokit/request-error": { |
497 | + "version": "2.1.0", |
498 | + "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-2.1.0.tgz", |
499 | + "integrity": "sha512-1VIvgXxs9WHSjicsRwq8PlR2LR2x6DwsJAaFgzdi0JfJoGSO8mYI/cHJQ+9FbN21aa+DrgNLnwObmyeSC8Rmpg==", |
500 | + "requires": { |
501 | + "@octokit/types": "^6.0.3", |
502 | + "deprecation": "^2.0.0", |
503 | + "once": "^1.4.0" |
504 | + } |
505 | + }, |
506 | + "@octokit/types": { |
507 | + "version": "6.41.0", |
508 | + "resolved": "https://registry.npmjs.org/@octokit/types/-/types-6.41.0.tgz", |
509 | + "integrity": "sha512-eJ2jbzjdijiL3B4PrSQaSjuF2sPEQPVCPzBvTHJD9Nz+9dw2SGH4K4xeQJ77YfTq5bRQ+bD8wT11JbeDPmxmGg==", |
510 | + "requires": { |
511 | + "@octokit/openapi-types": "^12.11.0" |
512 | + } |
513 | + }, |
514 | + "before-after-hook": { |
515 | + "version": "2.2.3", |
516 | + "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz", |
517 | + "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ==" |
518 | + }, |
519 | + "deprecation": { |
520 | + "version": "2.3.1", |
521 | + "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz", |
522 | + "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ==" |
523 | + }, |
524 | + "is-plain-object": { |
525 | + "version": "5.0.0", |
526 | + "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz", |
527 | + "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==" |
528 | + }, |
529 | + "node-fetch": { |
530 | + "version": "2.6.9", |
531 | + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.9.tgz", |
532 | + "integrity": "sha512-DJm/CJkZkRjKKj4Zi4BsKVZh3ValV5IR5s7LVZnW+6YMh0W1BfNA8XSs6DLMGYlId5F3KnA70uu2qepcR08Qqg==", |
533 | + "requires": { |
534 | + "whatwg-url": "^5.0.0" |
535 | + } |
536 | + }, |
537 | + "once": { |
538 | + "version": "1.4.0", |
539 | + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", |
540 | + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", |
541 | + "requires": { |
542 | + "wrappy": "1" |
543 | + } |
544 | + }, |
545 | + "tr46": { |
546 | + "version": "0.0.3", |
547 | + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", |
548 | + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" |
549 | + }, |
550 | + "tunnel": { |
551 | + "version": "0.0.6", |
552 | + "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz", |
553 | + "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==" |
554 | + }, |
555 | + "universal-user-agent": { |
556 | + "version": "6.0.0", |
557 | + "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz", |
558 | + "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w==" |
559 | + }, |
560 | + "uuid": { |
561 | + "version": "8.3.2", |
562 | + "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz", |
563 | + "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==" |
564 | + }, |
565 | + "webidl-conversions": { |
566 | + "version": "3.0.1", |
567 | + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", |
568 | + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" |
569 | + }, |
570 | + "whatwg-url": { |
571 | + "version": "5.0.0", |
572 | + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", |
573 | + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", |
574 | + "requires": { |
575 | + "tr46": "~0.0.3", |
576 | + "webidl-conversions": "^3.0.0" |
577 | + } |
578 | + }, |
579 | + "wrappy": { |
580 | + "version": "1.0.2", |
581 | + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", |
582 | + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==" |
583 | + } |
584 | + } |
585 | +} |
586 | diff --git a/.github/actions/release-changelog-bug-refs/package.json b/.github/actions/release-changelog-bug-refs/package.json |
587 | new file mode 100644 |
588 | index 0000000..62509b1 |
589 | --- /dev/null |
590 | +++ b/.github/actions/release-changelog-bug-refs/package.json |
591 | @@ -0,0 +1,10 @@ |
592 | +{ |
593 | + "name": "release-changelog-bug-refs", |
594 | + "version": "1.0.0", |
595 | + "description": "Block releases if bug references in commits aren't in the proposed changelog entry", |
596 | + "main": "index.js", |
597 | + "dependencies": { |
598 | + "@actions/core": "^1.10.0", |
599 | + "@actions/github": "^5.1.1" |
600 | + } |
601 | +} |
602 | diff --git a/.github/workflows/ci-base.yaml b/.github/workflows/ci-base.yaml |
603 | index dab17d3..59174bf 100644 |
604 | --- a/.github/workflows/ci-base.yaml |
605 | +++ b/.github/workflows/ci-base.yaml |
606 | @@ -29,8 +29,6 @@ jobs: |
607 | run: tox -e mypy |
608 | - name: Version Consistency |
609 | run: python3 ./tools/check-versions-are-consistent.py |
610 | - - name: Docs |
611 | - run: tox -e docs |
612 | unit-tests: |
613 | name: Unit Tests |
614 | runs-on: ubuntu-22.04 |
615 | diff --git a/.github/workflows/ci-integration.yaml b/.github/workflows/ci-integration.yaml |
616 | index 937de39..be05d93 100644 |
617 | --- a/.github/workflows/ci-integration.yaml |
618 | +++ b/.github/workflows/ci-integration.yaml |
619 | @@ -27,7 +27,7 @@ jobs: |
620 | runs-on: ubuntu-22.04 |
621 | strategy: |
622 | matrix: |
623 | - release: ['xenial', 'bionic', 'focal', 'jammy', 'kinetic', 'lunar'] |
624 | + release: ['xenial', 'bionic', 'focal', 'jammy', 'lunar', 'mantic'] |
625 | steps: |
626 | - name: Prepare build tools |
627 | env: |
628 | @@ -65,7 +65,7 @@ jobs: |
629 | # as much information as possible from them. |
630 | fail-fast: false |
631 | matrix: |
632 | - release: ['bionic', 'focal', 'jammy', 'kinetic'] |
633 | + release: ['bionic', 'focal', 'jammy', 'lunar'] |
634 | platform: ['lxd'] |
635 | host_os: ['ubuntu-22.04'] |
636 | include: |
637 | @@ -123,6 +123,9 @@ jobs: |
638 | UACLIENT_BEHAVE_CONTRACT_TOKEN: '${{ secrets.UACLIENT_BEHAVE_CONTRACT_TOKEN }}' |
639 | UACLIENT_BEHAVE_CONTRACT_TOKEN_STAGING: '${{ secrets.UACLIENT_BEHAVE_CONTRACT_TOKEN_STAGING }}' |
640 | UACLIENT_BEHAVE_CONTRACT_TOKEN_STAGING_EXPIRED: '${{ secrets.UACLIENT_BEHAVE_CONTRACT_TOKEN_STAGING_EXPIRED }}' |
641 | + UACLIENT_BEHAVE_LANDSCAPE_REGISTRATION_KEY: '${{ secrets.UACLIENT_BEHAVE_LANDSCAPE_REGISTRATION_KEY }}' |
642 | + UACLIENT_BEHAVE_LANDSCAPE_API_ACCESS_KEY: '${{ secrets.UACLIENT_BEHAVE_LANDSCAPE_API_ACCESS_KEY }}' |
643 | + UACLIENT_BEHAVE_LANDSCAPE_API_SECRET_KEY: '${{ secrets.UACLIENT_BEHAVE_LANDSCAPE_API_SECRET_KEY }}' |
644 | run: | |
645 | PYCLOUDLIB_CONFIG="$(mktemp --tmpdir="${{ runner.temp }}" pycloudlib.toml.XXXXXXXXXX)" |
646 | GCE_CREDENTIALS_PATH="$(mktemp --tmpdir="${{ runner.temp }}" gcloud.json.XXXXXXXXXX)" |
647 | diff --git a/.github/workflows/release-checks.yaml b/.github/workflows/release-checks.yaml |
648 | new file mode 100644 |
649 | index 0000000..a5e0c83 |
650 | --- /dev/null |
651 | +++ b/.github/workflows/release-checks.yaml |
652 | @@ -0,0 +1,22 @@ |
653 | +--- |
654 | + |
655 | +name: Release Checks |
656 | + |
657 | +on: |
658 | + pull_request: |
659 | + branches: |
660 | + - release |
661 | + |
662 | +jobs: |
663 | + release-changelog-bug-refs: |
664 | + runs-on: ubuntu-latest |
665 | + steps: |
666 | + - name: Git checkout |
667 | + uses: actions/checkout@v3 |
668 | + - name: Install dependencies |
669 | + run: cd ./.github/actions/release-changelog-bug-refs && npm install |
670 | + - name: Check for bug references |
671 | + uses: ./.github/actions/release-changelog-bug-refs |
672 | + id: release-changelog-bug-refs |
673 | + with: |
674 | + repo-token: ${{ secrets.GITHUB_TOKEN }} |
675 | diff --git a/.gitignore b/.gitignore |
676 | new file mode 100644 |
677 | index 0000000..def4de5 |
678 | --- /dev/null |
679 | +++ b/.gitignore |
680 | @@ -0,0 +1,51 @@ |
681 | +artifacts/* |
682 | +*debhelper* |
683 | +debian/ubuntu-advantage-tools/ |
684 | +debian/ubuntu-advantage-tools.substvars |
685 | +dev/entitlement-creds.json.* |
686 | +*.pyc |
687 | +*.pyo |
688 | +__pycache__ |
689 | +.tox |
690 | +.pybuild |
691 | +.coverage |
692 | +.cache |
693 | +*.egg-info/ |
694 | +.mypy_cache/ |
695 | +.python-version |
696 | + |
697 | +# Ignore artifacts generated by bddeb |
698 | +*-1~bddeb* |
699 | +ubuntu-advantage-tools_*.orig.tar.gz |
700 | +ubuntu-advantage-tools_all.deb |
701 | +ubuntu_advantage_tools.dsc |
702 | + |
703 | +# test/jenkins artifacts |
704 | +pytest_results.xml |
705 | +reports/ |
706 | + |
707 | +# integration test artifacts |
708 | +azure-priv-*.pem |
709 | +azure-pub-*.txt |
710 | +ec2-*.pem |
711 | +gcp-pub-* |
712 | +gcp-priv-* |
713 | +lxd-*-uaclient-ci-* |
714 | +build-from-source.sh |
715 | +test-results* |
716 | + |
717 | +# credentials - don't commit credentials |
718 | +tools/ua-test-credentials.yaml |
719 | + |
720 | +# apt-hook build artifacts |
721 | +apt-hook/hook |
722 | +apt-hook/ubuntu-advantage.pot |
723 | +apt-hook/json-hook |
724 | +apt-hook/json-hook-test |
725 | + |
726 | +# custom github actions use node |
727 | +node_modules |
728 | + |
729 | +# docs |
730 | +docs/build/ |
731 | +.sphinx |
732 | diff --git a/.readthedocs.yaml b/.readthedocs.yaml |
733 | index 5090ca0..5840eeb 100644 |
734 | --- a/.readthedocs.yaml |
735 | +++ b/.readthedocs.yaml |
736 | @@ -1,14 +1,12 @@ |
737 | version: 2 |
738 | |
739 | -sphinx: |
740 | - configuration: docs/conf.py |
741 | - |
742 | build: |
743 | os: ubuntu-22.04 |
744 | tools: |
745 | python: "3.10" |
746 | + jobs: |
747 | + post_checkout: |
748 | + # Always skip on main branch. |
749 | + # Docs are kept in separate docs and docs-devel branches. |
750 | + - exit 183 |
751 | |
752 | -python: |
753 | - install: |
754 | - - requirements: docs-requirements.txt |
755 | - - requirements: requirements.txt |
756 | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md |
757 | index 03568a6..3529de0 100644 |
758 | --- a/CONTRIBUTING.md |
759 | +++ b/CONTRIBUTING.md |
760 | @@ -7,29 +7,29 @@ from the architecture of the project to how you should test any code changes. |
761 | |
762 | ### How to Guides |
763 | |
764 | -* [How to build](./dev-docs/howtoguides/building.md) |
765 | -* [How to run the code formatting tools](./dev-docs/howtoguides/code_formatting.md) |
766 | -* [How to run the tests](./dev-docs/howtoguides/testing.md) |
767 | -* [How to release a new version](./dev-docs/howtoguides/how_to_release_a_new_version_of_ua.md) |
768 | -* [How to use the contract staging environment](./dev-docs/howtoguides/use_staging_environment.md) |
769 | -* [How to use the magic attach endpoints](./dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md) |
770 | +* [How to build](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/building.md) |
771 | +* [How to run the code formatting tools](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/code_formatting.md) |
772 | +* [How to run the tests](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/testing.md) |
773 | +* [How to release a new version](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/how_to_release_a_new_version_of_ua.md) |
774 | +* [How to use the contract staging environment](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/use_staging_environment.md) |
775 | +* [How to use the magic attach endpoints](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md) |
776 | |
777 | ### Reference |
778 | |
779 | -* [Terminology](./dev-docs/references/terminology.md) |
780 | -* [Architecture](./dev-docs/references/architecture.md) |
781 | -* [Early review sign-off](./dev-docs/references/early_review_signoff.md) |
782 | -* [What happens during attach](./dev-docs/references/what_happens_during_attach.md) |
783 | -* [Enabling a service](./dev-docs/references/enabling_a_service.md) |
784 | -* [Directory layout](./dev-docs/references/directory_layout.md) |
785 | -* [Daily Builds](./dev-docs/references/daily_builds.md) |
786 | -* [Version String Formatting](./dev-docs/references/version_string_formatting.md) |
787 | -* [PR review policy](./dev-docs/references/pr_review_policy.md) |
788 | +* [Terminology](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/terminology.md) |
789 | +* [Architecture](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/architecture.md) |
790 | +* [Early review sign-off](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/early_review_signoff.md) |
791 | +* [What happens during attach](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/what_happens_during_attach.md) |
792 | +* [Enabling a service](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/enabling_a_service.md) |
793 | +* [Directory layout](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/directory_layout.md) |
794 | +* [Daily Builds](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/daily_builds.md) |
795 | +* [Version String Formatting](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/version_string_formatting.md) |
796 | +* [PR review policy](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/references/pr_review_policy.md) |
797 | |
798 | ### Explanation |
799 | |
800 | -* [How auto-attach works](./dev-docs/explanations/how_auto_attach_works.md) |
801 | +* [How auto-attach works](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/explanations/how_auto_attach_works.md) |
802 | |
803 | ### Documentation |
804 | |
805 | -* [Documentation guide](./dev-docs/devdocs_styleguide.md) |
806 | +* [Documentation guide](https://github.com/canonical/ubuntu-pro-client/blob/docs/dev-docs/devdocs_styleguide.md) |
807 | diff --git a/README.md b/README.md |
808 | index 4e7a493..54295c9 100644 |
809 | --- a/README.md |
810 | +++ b/README.md |
811 | @@ -1,22 +1,22 @@ |
812 | <h1> |
813 | <a href="https://ubuntu.com/pro" target="_blank"> |
814 | - <img src="./docs/_static/circle_of_friends.png" width="33"/> |
815 | + <img src="https://raw.githubusercontent.com/canonical/ubuntu-pro-client/docs/docs/_static/circle_of_friends.png" width="33"/> |
816 | </a> |
817 | <br> |
818 | Ubuntu Pro Client |
819 | </h1> |
820 | |
821 | ###### Clean and Consistent CLI for your Ubuntu Pro Systems |
822 | -[![Latest Upstream Version](https://img.shields.io/github/v/tag/canonical/ubuntu-advantage-client.svg?label=Latest%20Upstream%20Version&logo=github&logoColor=white&color=33ce57)](https://github.com/canonical/ubuntu-pro-client/tags) |
823 | -[![CI](https://github.com/canonical/ubuntu-advantage-client/actions/workflows/ci-base.yaml/badge.svg?branch=main)](https://github.com/canonical/ubuntu-pro-client/actions) |
824 | +[![Latest Upstream Version](https://img.shields.io/github/v/tag/canonical/ubuntu-pro-client.svg?label=Latest%20Upstream%20Version&logo=github&logoColor=white&color=33ce57)](https://github.com/canonical/ubuntu-pro-client/tags) |
825 | +[![CI](https://github.com/canonical/ubuntu-pro-client/actions/workflows/ci-base.yaml/badge.svg?branch=main)](https://github.com/canonical/ubuntu-pro-client/actions) |
826 | [![Documentation Status](https://readthedocs.com/projects/canonical-ubuntu-pro-client/badge/?version=latest)](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/?badge=latest) |
827 | <br/> |
828 | [![Released Xenial Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/xenial?label=Xenial&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/xenial/+source/ubuntu-advantage-tools) |
829 | [![Released Bionic Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/bionic?label=Bionic&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/bionic/+source/ubuntu-advantage-tools) |
830 | [![Released Focal Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/focal?label=Focal&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/focal/+source/ubuntu-advantage-tools) |
831 | [![Released Jammy Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/jammy?label=Jammy&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/jammy/+source/ubuntu-advantage-tools) |
832 | -[![Released Kinetic Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/kinetic?label=Kinetic&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/kinetic/+source/ubuntu-advantage-tools) |
833 | [![Released Lunar Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/lunar?label=Lunar&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/lunar/+source/ubuntu-advantage-tools) |
834 | +[![Released Mantic Version](https://img.shields.io/ubuntu/v/ubuntu-advantage-tools/mantic?label=Mantic&logo=ubuntu&logoColor=white)](https://launchpad.net/ubuntu/mantic/+source/ubuntu-advantage-tools) |
835 | |
836 | The Ubuntu Pro Client (`pro`) is the official tool to enable Canonical offerings on your |
837 | system. |
838 | diff --git a/debian/README.source b/debian/README.source |
839 | new file mode 100644 |
840 | index 0000000..44b96b9 |
841 | --- /dev/null |
842 | +++ b/debian/README.source |
843 | @@ -0,0 +1,38 @@ |
844 | +=================================== |
845 | +Packaging of ubuntu-advantage-tools |
846 | +=================================== |
847 | + |
848 | +Development code |
849 | +=================================== |
850 | + |
851 | +The development branches of ubuntu-advantage-tools are hosted in GitHub, at: |
852 | +https://github.com/canonical/ubuntu-pro-client |
853 | + |
854 | +New pull requests with contributions either to the codebase itself or to the |
855 | +documentation branches should always be opened in GitHub. |
856 | + |
857 | +Package source code |
858 | +=================================== |
859 | + |
860 | +The source code used to build the package is hosted in Launchpad, at: |
861 | +https://git.launchpad.net/ubuntu/+source/ubuntu-advantage-tools |
862 | + |
863 | +The development branch in Launchpad is equivalent to the release branch in |
864 | +GitHub. Everytime a new version is released, the content of the GitHub release |
865 | +branch is brought in a Merge Request to the Launchpad development branch. |
866 | + |
867 | +Particularities |
868 | +=================================== |
869 | + |
870 | +- ubuntu-advantage-tools ships the same features and bugfixes to all |
871 | + supported Ubuntu releases. This means the package is practically the |
872 | + same across all LTS releases, including the ones in ESM period, and in |
873 | + the interim releases. (The only differences are the specific dependencies, |
874 | + dealt with in the debian/ files when building the package). |
875 | + |
876 | +- Some test-related files and folders are present in the source package, but |
877 | + are ignored when building the binary packages. debian/rules specifies |
878 | + 'pybuild' as the build system, and unit tests / integration tests are |
879 | + excluded in 'setup.py'. As a consequence, changes to the tests are less |
880 | + relevant in SRU reviews: they stil reflect what is being tested in each |
881 | + release, but they do not cause any impact to the stable releases. |
882 | diff --git a/debian/changelog b/debian/changelog |
883 | index 85d1272..26f78a9 100644 |
884 | --- a/debian/changelog |
885 | +++ b/debian/changelog |
886 | @@ -1,3 +1,38 @@ |
887 | +ubuntu-advantage-tools (29) mantic; urgency=medium |
888 | + |
889 | + * d/control: |
890 | + - update links for the project github page |
891 | + * d/copyright: |
892 | + - bump date to 2023 |
893 | + - update upstream-name and source |
894 | + * d/ubuntu-advantage-tools.{postinst,postrm}: |
895 | + - rename repo GPG keys from -advantage to -pro (GH: #1539) |
896 | + - replace calls to systemctl for deb-systemd-invoke |
897 | + * d/README.source: |
898 | + - add file with basic explanation on the source code (GH: #2463) |
899 | + * New upstream release 29 (LP: #2029144) |
900 | + - anbox-cloud: add support for service |
901 | + - api |
902 | + + new endpoint: u.pro.security.fix.plan.cve.v1 |
903 | + + new endpoint: u.pro.security.fix.plan.usn.v1 |
904 | + + new endpoint: u.apt_news.current_news.v1 |
905 | + + add more data explaining the decision made for |
906 | + u.pro.security.status.reboot_required.v1 endpoint |
907 | + - contract: |
908 | + + send activityInfo after cli attach, enable and disable |
909 | + + start recording when the machine has attached to a Pro subscription |
910 | + + more reliable detection when running on a docker container |
911 | + - esm: create static files to pin packages from esm-infra and esm-apps with |
912 | + higher priority (GH: #2580) |
913 | + - fix: ignore non-USN items on related usns |
914 | + - landscape: add support for the service |
915 | + - logging: update to ubuntupro logging namespace |
916 | + - proxy: add support for TLS-in-TLS proxy (LP: #1999909) |
917 | + - snapd: look for the snapd package instead of the snap command |
918 | + - system: try/except logic to remove files and folders (LP: #2025731) |
919 | + |
920 | + -- Lucas Moura <lucas.moura@canonical.com> Mon, 31 Jul 2023 15:46:23 +0000 |
921 | + |
922 | ubuntu-advantage-tools (28.1) mantic; urgency=medium |
923 | |
924 | * New upstream release 28.1 (LP: #2017949) |
925 | diff --git a/debian/control b/debian/control |
926 | index 1f78a18..51f0549 100644 |
927 | --- a/debian/control |
928 | +++ b/debian/control |
929 | @@ -26,8 +26,8 @@ Build-Depends: bash-completion, |
930 | python3-yaml |
931 | Standards-Version: 4.5.1 |
932 | Homepage: https://ubuntu.com/advantage |
933 | -Vcs-Git: https://github.com/canonical/ubuntu-advantage-client.git |
934 | -Vcs-Browser: https://github.com/canonical/ubuntu-advantage-client |
935 | +Vcs-Git: https://github.com/canonical/ubuntu-pro-client.git |
936 | +Vcs-Browser: https://github.com/canonical/ubuntu-pro-client |
937 | Rules-Requires-Root: no |
938 | |
939 | Package: ubuntu-advantage-tools |
940 | diff --git a/debian/copyright b/debian/copyright |
941 | index 7eb8c9e..e965469 100644 |
942 | --- a/debian/copyright |
943 | +++ b/debian/copyright |
944 | @@ -1,9 +1,9 @@ |
945 | Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ |
946 | -Upstream-Name: ubuntu-advantage-script |
947 | -Source: https://github.com/CanonicalLtd/ubuntu-advantage-script |
948 | +Upstream-Name: ubuntu-pro-client |
949 | +Source: https://github.com/canonical/ubuntu-pro-client |
950 | |
951 | Files: * |
952 | -Copyright: 2017, Canonical Ltd |
953 | +Copyright: 2023, Canonical Ltd |
954 | License: GPL-3.0 |
955 | This program is free software: you can redistribute it and/or modify |
956 | it under the terms of the GNU General Public License as published by |
957 | diff --git a/debian/source/lintian-overrides b/debian/source/lintian-overrides |
958 | index b1ce79a..0697833 100644 |
959 | --- a/debian/source/lintian-overrides |
960 | +++ b/debian/source/lintian-overrides |
961 | @@ -3,6 +3,3 @@ ubuntu-advantage-tools: missing-build-dependency-for-dh_-command dh_systemd_star |
962 | |
963 | # Lintian can't handle the multiline debhelper/dh-systemd dependencies explained in debian/control |
964 | ubuntu-advantage-tools: missing-build-dependency-for-dh-addon *systemd* |
965 | - |
966 | -# Lintian doesn't like mentioning riscv64 for older go package |
967 | -ubuntu-advantage-tools: invalid-arch-string-in-source-relation riscv64 [build-depends: golang-1.10-go [!powerpc !riscv64]] |
968 | diff --git a/debian/ubuntu-advantage-tools.lintian-overrides b/debian/ubuntu-advantage-tools.lintian-overrides |
969 | new file mode 100644 |
970 | index 0000000..0b09bcb |
971 | --- /dev/null |
972 | +++ b/debian/ubuntu-advantage-tools.lintian-overrides |
973 | @@ -0,0 +1,10 @@ |
974 | +# We are silencing this issue because of this LP: #1930121 |
975 | +ubuntu-advantage-tools: command-with-path-in-maintainer-script |
976 | + |
977 | +# Ubuntu doesn't support sysv init.d |
978 | +ubuntu-advantage-tools: package-supports-alternative-init-but-no-init.d-script |
979 | + |
980 | +# We have made the decision of delivering those files |
981 | +ubuntu-advantage-tools: package-installs-apt-preferences |
982 | + |
983 | +ubuntu-advantage-tools: possible-bashism-in-maintainer-script |
984 | diff --git a/debian/ubuntu-advantage-tools.postinst b/debian/ubuntu-advantage-tools.postinst |
985 | index 31d93ae..b332333 100644 |
986 | --- a/debian/ubuntu-advantage-tools.postinst |
987 | +++ b/debian/ubuntu-advantage-tools.postinst |
988 | @@ -16,8 +16,11 @@ fi |
989 | |
990 | APT_TRUSTED_KEY_DIR="/etc/apt/trusted.gpg.d" |
991 | |
992 | -ESM_INFRA_KEY_TRUSTY="ubuntu-advantage-esm-infra-trusty.gpg" |
993 | -ESM_APPS_KEY="ubuntu-advantage-esm-apps.gpg" |
994 | +# ubuntu-advantage-* GPG keys renamed to ubuntu-pro-* in version 29 |
995 | +OLD_ESM_INFRA_KEY_TRUSTY="ubuntu-advantage-esm-infra-trusty.gpg" |
996 | +OLD_ESM_APPS_KEY="ubuntu-advantage-esm-apps.gpg" |
997 | +ESM_INFRA_KEY="ubuntu-pro-esm-infra.gpg" |
998 | +ESM_APPS_KEY="ubuntu-pro-esm-apps.gpg" |
999 | |
1000 | APT_SRC_DIR="/etc/apt/sources.list.d" |
1001 | APT_PREFERENCES_DIR="/etc/apt/preferences.d" |
1002 | @@ -132,7 +135,8 @@ if status: |
1003 | esm_infra_cleanup() { |
1004 | if ! check_service_is_enabled esm-infra; then |
1005 | rm -f "$APT_TRUSTED_KEY_DIR/ubuntu-esm*gpg" # Remove previous esm keys |
1006 | - rm -f "$APT_TRUSTED_KEY_DIR/$ESM_INFRA_KEY_TRUSTY" |
1007 | + rm -f "$APT_TRUSTED_KEY_DIR/$OLD_ESM_INFRA_KEY_TRUSTY" |
1008 | + rm -f "$APT_TRUSTED_KEY_DIR/$ESM_INFRA_KEY" |
1009 | rm -f "$ESM_INFRA_APT_SOURCE_FILE" |
1010 | rm -f "$ESM_INFRA_OLD_APT_SOURCE_FILE_TRUSTY" |
1011 | rm -f "$ESM_APT_PREF_FILE_TRUSTY" "$ESM_INFRA_OLD_APT_PREF_FILE_TRUSTY" |
1012 | @@ -143,6 +147,7 @@ esm_infra_cleanup() { |
1013 | |
1014 | esm_apps_cleanup() { |
1015 | if ! check_service_is_enabled esm-apps; then |
1016 | + rm -f "$APT_TRUSTED_KEY_DIR/$OLD_ESM_APPS_KEY" |
1017 | rm -f "$APT_TRUSTED_KEY_DIR/$ESM_APPS_KEY" |
1018 | rm -f "$ESM_APPS_APT_SOURCE_FILE" |
1019 | rm -f "$ESM_APPS_APT_PREF_FILE" |
1020 | @@ -251,11 +256,11 @@ remove_old_systemd_units() { |
1021 | # The failed state is ephemeral and only needs to be cleared if |
1022 | # it is there so that the system doesn't say it is degraded. |
1023 | # If the old timer was not running, then this is a noop. |
1024 | - systemctl --system daemon-reload > /dev/null || true |
1025 | - systemctl reset-failed ua-license-check.timer > /dev/null 2>&1 || true |
1026 | + deb-systemd-invoke --system daemon-reload > /dev/null || true |
1027 | + deb-systemd-invoke reset-failed ua-license-check.timer > /dev/null 2>&1 || true |
1028 | # In rare race-condition scenarios, the service can also get into |
1029 | # the same failed state. |
1030 | - systemctl reset-failed ua-license-check.service > /dev/null 2>&1 || true |
1031 | + deb-systemd-invoke reset-failed ua-license-check.service > /dev/null 2>&1 || true |
1032 | fi |
1033 | deb-systemd-helper purge ua-license-check.path > /dev/null || true |
1034 | deb-systemd-helper unmask ua-license-check.path > /dev/null || true |
1035 | @@ -359,6 +364,19 @@ migrate_user_config_post() { |
1036 | fi |
1037 | } |
1038 | |
1039 | +rename_gpg_keys() { |
1040 | + # esm-infra doesn't follow the name pattern |
1041 | + if [ -f "$APT_TRUSTED_KEY_DIR/$OLD_ESM_INFRA_KEY_TRUSTY" ]; then |
1042 | + mv "$APT_TRUSTED_KEY_DIR/$OLD_ESM_INFRA_KEY_TRUSTY" "$APT_TRUSTED_KEY_DIR/$ESM_INFRA_KEY" |
1043 | + fi |
1044 | + SERVICES="cc-eal cis esm-apps fips ros realtime-kernel" |
1045 | + for service in $SERVICES; do |
1046 | + if [ -f "$APT_TRUSTED_KEY_DIR/ubuntu-advantage-$service.gpg" ]; then |
1047 | + mv "$APT_TRUSTED_KEY_DIR/ubuntu-advantage-$service.gpg" "$APT_TRUSTED_KEY_DIR/ubuntu-pro-$service.gpg" |
1048 | + fi |
1049 | + done |
1050 | +} |
1051 | + |
1052 | case "$1" in |
1053 | configure) |
1054 | PREVIOUS_PKG_VER=$2 |
1055 | @@ -452,6 +470,11 @@ case "$1" in |
1056 | migrate_user_config_post |
1057 | fi |
1058 | |
1059 | + # Rename the gpg keys to -pro- |
1060 | + if dpkg --compare-versions "$PREVIOUS_PKG_VER" lt "29~"; then |
1061 | + rename_gpg_keys |
1062 | + fi |
1063 | + |
1064 | if grep -q "^ua_config:" /etc/ubuntu-advantage/uaclient.conf; then |
1065 | echo "Warning: uaclient.conf contains old ua_config field." >&2 |
1066 | echo " Please do the following:" >&2 |
1067 | diff --git a/debian/ubuntu-advantage-tools.postrm b/debian/ubuntu-advantage-tools.postrm |
1068 | index c1bcdf5..e0e930d 100644 |
1069 | --- a/debian/ubuntu-advantage-tools.postrm |
1070 | +++ b/debian/ubuntu-advantage-tools.postrm |
1071 | @@ -20,7 +20,7 @@ remove_logs(){ |
1072 | } |
1073 | |
1074 | remove_gpg_files(){ |
1075 | - rm -f /etc/apt/trusted.gpg.d/ubuntu-advantage-*.gpg |
1076 | + rm -f /etc/apt/trusted.gpg.d/ubuntu-pro-*.gpg |
1077 | } |
1078 | |
1079 | case "$1" in |
1080 | diff --git a/dev-docs/devdocs_styleguide.md b/dev-docs/devdocs_styleguide.md |
1081 | deleted file mode 100644 |
1082 | index 818a189..0000000 |
1083 | --- a/dev-docs/devdocs_styleguide.md |
1084 | +++ /dev/null |
1085 | @@ -1,152 +0,0 @@ |
1086 | -# Documentation |
1087 | - |
1088 | -Our docs are hosted on [Read the Docs](https://readthedocs.com/). This page |
1089 | -will explain how to contribute to the docs and build them locally. |
1090 | - |
1091 | -The documentation is *primarily* written in standard Markdown, but pages can |
1092 | -be written in reStructuredText if you prefer. |
1093 | - |
1094 | -We also use the |
1095 | -[MyST-Parser Sphinx extension](https://myst-parser.readthedocs.io/en/latest/intro.html). |
1096 | -This causes all Markdown (.md) files to be parsed as MyST, and |
1097 | -[enables the use of directives](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html), |
1098 | -which can be awkward to achieve in standard Markdown. |
1099 | - |
1100 | -## Building the docs |
1101 | - |
1102 | -To build the docs for Ubuntu Pro Client, you can use a `tox` command. You can |
1103 | -install `tox` on your machine by running the `make test` command. Once tox is |
1104 | -installed, just run the command: |
1105 | - |
1106 | -``` |
1107 | -$ tox -e docs |
1108 | -``` |
1109 | - |
1110 | -The command will generate the HTML pages inside `docs/build`. The makefile |
1111 | -target will build the documentation for you using Sphinx. |
1112 | - |
1113 | -Once built, the HTML files will be viewable in `docs/build/html/`. Use your web |
1114 | -browser to open `index.html` to preview the site. |
1115 | - |
1116 | -## Style guide |
1117 | - |
1118 | -We use the [Canonical style guide](https://docs.ubuntu.com/styleguide/en) in |
1119 | -our documentation, which is summarised below -- with a few additions relevant |
1120 | -to our docs. |
1121 | - |
1122 | -### Language |
1123 | - |
1124 | -Where possible, text should be written in UK English. However, discretion and |
1125 | -common sense can both be applied. For example, where text refers to code |
1126 | -elements that exist in US English, the spelling of these elements should not |
1127 | -be changed to UK English. |
1128 | - |
1129 | -### Voice |
1130 | - |
1131 | -Try to use active voice where possible, rather than the passive voice. The |
1132 | -active voice is generally more concise and easier to read. As an example, you |
1133 | -could say "we recommend" (active) rather than "it is recommended that" |
1134 | -(passive). |
1135 | - |
1136 | -### Headings |
1137 | - |
1138 | -Headings should be written in sentence case. This means that only the first |
1139 | -letter is capitalised (unless the header text refers to e.g., a product name |
1140 | -that would normally be capitalised, such as "Ubuntu Pro Client"). |
1141 | - |
1142 | -Ensure that you do not skip header levels when creating your document |
1143 | -structure, i.e., that a section is followed by a subsection, and not a |
1144 | -sub-subsection. Skipping header levels can lead to de-ranking of pages in |
1145 | -search engines. |
1146 | - |
1147 | -Try to craft your headings to be descriptive, but as short as possible, to help |
1148 | -readers understand what content to expect if they click on it. |
1149 | - |
1150 | -### Line length |
1151 | - |
1152 | -Please keep the line lengths to a maximum of **79** characters. This ensures |
1153 | -that the pages and tables do not get so wide that side scrolling is required. |
1154 | - |
1155 | -### Links |
1156 | - |
1157 | -Where possible, use contextual text in your links to aid users with screen |
1158 | -readers and other accessibility tools. For example, "check out our |
1159 | -[documentation style guide](#links) is preferable to "click |
1160 | -[here](#links) for more". |
1161 | - |
1162 | -### Code blocks |
1163 | - |
1164 | -Our documentation uses the |
1165 | -[Sphinx extension "sphinx-copybutton"](https://sphinx-copybutton.readthedocs.io/en/latest/), |
1166 | -which creates a small button on the right-hand side of code blocks for users to |
1167 | -copy the code snippets we provide. |
1168 | - |
1169 | -The copied code will strip out any prompt symbols so that users can |
1170 | -paste commands directly into their terminal. For user convenience, please |
1171 | -ensure that if you show any code output, it is presented in a separate code |
1172 | -block to the commands. |
1173 | - |
1174 | -Please also specify the language used in your code block, to make sure it |
1175 | -renders with the correct syntax highlighting. |
1176 | - |
1177 | -### Vertical whitespace |
1178 | - |
1179 | -One newline between each section helps ensure readability of the documentation |
1180 | -source code. Keeping paragraphs relatively short (up to ~5-6 sentences) aids in |
1181 | -keeping the text readable when rendered to a web page. Some rST elements also |
1182 | -require an empty newline before and after, so for consistency, ensure that all |
1183 | -elements (tables, images, headers, etc) have a newline before and after. |
1184 | - |
1185 | -### Acronyms and jargon |
1186 | - |
1187 | -Acronyms are always capitalised (e.g., JSON, YAML, QEMU, LXD) in text. |
1188 | - |
1189 | -The first time an acronym is used on a page, it is best practice to introduce |
1190 | -it by showing the expanded name followed by the acronym in parentheses. E.g., |
1191 | -Quick EMUlator (QEMU). If the acronym is *very* common (e.g., URL, HTTP), or |
1192 | -you provide a link to a documentation page with these details, you do not need |
1193 | -to include them. |
1194 | - |
1195 | -Avoid using jargon unless absolutely necessary, to keep our documentation |
1196 | -accessible to as wide a range of users as possible. If jargon is unavoidable, |
1197 | -consider including brief explanations to help the user keep up with the |
1198 | -material. |
1199 | - |
1200 | -### Admonitions and callouts |
1201 | - |
1202 | -Notes, warnings, or other information you wish to draw the reader's attention |
1203 | -to can be called out in an admonition block. If you are writing your code in |
1204 | -Markdown, this is where the MyST extension comes in handy. Here is an example: |
1205 | - |
1206 | -```` |
1207 | - ```{note} |
1208 | - The options are: note, important, hint, seealso, tip, attention, caution, |
1209 | - warning, danger, and error. |
1210 | - ```{warning} |
1211 | - Although it's possible to nest admonitions inside each other, it's better to |
1212 | - avoid doing that unless it's strictly necessary! |
1213 | - ``` |
1214 | -```` |
1215 | - |
1216 | -```{note} |
1217 | -The options are: note, important, hint, seealso, tip, attention, caution, |
1218 | -warning, danger, and error. |
1219 | -```{warning} |
1220 | -Although it's possible to nest admonitions inside each other, it's better to |
1221 | -avoid doing that unless it's strictly necessary! |
1222 | -``` |
1223 | - |
1224 | -## Organisation |
1225 | - |
1226 | -We follow the [principles of Diataxis](https://diataxis.fr/) in our |
1227 | -documentation. When writing new docs, try to consider the purpose of the |
1228 | -document and how the reader will probably use it. This will help you to decide |
1229 | -which section it belongs in. |
1230 | - |
1231 | -### Getting advice |
1232 | - |
1233 | -If you are in any doubt, please contact our team's |
1234 | -[Technical Author (Sally)](https://github.com/s-makin) for guidance. If you |
1235 | -would like her to review any documentation, she would be very happy to help! |
1236 | -Please also tag her as a reviewer on any PR that contains documentation |
1237 | -elements. |
1238 | diff --git a/dev-docs/explanations/how_auto_attach_works.md b/dev-docs/explanations/how_auto_attach_works.md |
1239 | deleted file mode 100644 |
1240 | index c1734f7..0000000 |
1241 | --- a/dev-docs/explanations/how_auto_attach_works.md |
1242 | +++ /dev/null |
1243 | @@ -1,57 +0,0 @@ |
1244 | -# How auto-attach works |
1245 | - |
1246 | -The `pro auto-attach` command follows a specific flow on every **Public Cloud Ubuntu Pro** image: |
1247 | - |
1248 | -1. Identify which cloud the command is running on. This is achieved by running |
1249 | - the `cloud-id` command provided by the [cloud-init](https://cloudinit.readthedocs.io/en/latest/) |
1250 | - package. Currently, we only support the following clouds when |
1251 | - running the command: AWS, Azure and GCP. The command will fail if performed on other |
1252 | - cloud types. |
1253 | - |
1254 | -2. Fetch the cloud metadata. This metadata is a cryptographically signed json blob |
1255 | - that provides the necessary information for the contract server to validate |
1256 | - the machine and return a valid pro token. To fetch that metadata, every cloud |
1257 | - provide a different endpoint to reach it: |
1258 | - |
1259 | - * **AWS**: http://169.254.169.254/latest/dynamic/instance-identity/pkcs7 |
1260 | - * **Azure**: http://169.254.169.254/metadata/attested/document?api-version=2020-09-01 |
1261 | - * **GCP**: http://metadata/computeMetadata/v1/instance/service-accounts/default/identity |
1262 | - |
1263 | -> **Note** |
1264 | -> On AWS, the client will also try the IPv6 address (`[fd00:ec2::254]`) to fetch the metadata if the IPv4 address doesn't work. |
1265 | - |
1266 | -3. Send this metadata json blob to the contract server at: |
1267 | - |
1268 | - * https://contracts.canonical.com/v1/clouds/CLOUD-TYPE/token |
1269 | - |
1270 | - Where CLOUD-TYPE is the cloud name we identified on step 1. |
1271 | - |
1272 | - The contract server will verify if the metadata is signed correctly based on the cloud |
1273 | - it is stored. Additionally, some other checks are performed to see if the metadata is valid. |
1274 | - For example, the contract server checks the product id provided in the metadata is a |
1275 | - valid product. If any problems is found on the metadata, the contract server will produce |
1276 | - an error response. |
1277 | - |
1278 | -4. After the contract server validates the metadata, it returns a token that will be used |
1279 | - to attach the machine to a pro subscription. To attach the machine we will reach the |
1280 | - following contract server endpoint: |
1281 | - |
1282 | - * https://contracts.canonical.com/v1/context/machines/token |
1283 | - |
1284 | - We will pass the token provided on step 3 as header bearer token for this request |
1285 | - |
1286 | -5. The contract returns a json specification based on the provided token. This json |
1287 | - contains all the directives the pro client needs to setup the machine and enable |
1288 | - the necessary services the token is associated with. |
1289 | - |
1290 | -6. Disable the `ubuntu-advantage.service` [daemon](../../docs/explanations/what_is_the_daemon.md), if running. |
1291 | - If the machine is detached, this daemon will be started again. |
1292 | - |
1293 | -Additionally, you can disable the `pro auto-attach` command by adding |
1294 | -the following lines on your `uaclient.conf` configuration file, (by default located at |
1295 | -`/etc/ubuntu-advantage/uaclient.conf`): |
1296 | - |
1297 | -```bash |
1298 | -features: |
1299 | - disable_auto_attach: true |
1300 | -``` |
1301 | diff --git a/dev-docs/explanations/systemd_units.md b/dev-docs/explanations/systemd_units.md |
1302 | deleted file mode 100644 |
1303 | index 577960a..0000000 |
1304 | --- a/dev-docs/explanations/systemd_units.md |
1305 | +++ /dev/null |
1306 | @@ -1,89 +0,0 @@ |
1307 | -# Mechanisms for auto-attaching Ubuntu Pro Cloud instances |
1308 | - |
1309 | -> **Note** |
1310 | -> This document explains the systemd units that attempt to auto-attach in various scenarios. If you're interested in how auto-attach itself works, see [How auto-attach works](./how_auto_attach_works.md). |
1311 | - |
1312 | -There are three methods by which a cloud instance may auto-attach to become Ubuntu Pro. |
1313 | - |
1314 | -1. On boot auto-attach for known Pro cloud instances. |
1315 | -2. Upgrade-in-place for non-Pro instances that get modified via the Cloud platform to entitle them to become Ubuntu Pro (only on Azure and GCP for now). |
1316 | -3. Retry auto-attach in case of failures. |
1317 | - |
1318 | -(1) is handled by a systemd unit (`ua-auto-attach.service`) delivered by a separate package called `ubuntu-advantage-pro`. This package is only installed on Ubuntu Pro Cloud images. In this way, an instance launched from an Ubuntu Pro Cloud image knows that it needs to auto-attach. |
1319 | - |
1320 | -(2) and (3) are both handled in a systemd unit (`ubuntu-advantage.service`) that is present on all Ubuntu machines (including non-Pro). |
1321 | - |
1322 | -Below is a flow chart intended to describe how all of these methods and systemd units interact. |
1323 | - |
1324 | -```mermaid |
1325 | -graph TD; |
1326 | - %% nodes |
1327 | - %%%% decisions |
1328 | - is_pro{Is -pro installed?} |
1329 | - auto_outcome{Success?} |
1330 | - is_attached{Attached?} |
1331 | - should_run_daemon{on Azure? or GCP? or retry flag set?} |
1332 | - is_gcp{Azure or GCP?} |
1333 | - is_retry{retry flag set?} |
1334 | - is_gcp_pro{Pro license detected?} |
1335 | - daemon_attach_outcome{Success?} |
1336 | - daemon_attach_outcome2{Success?} |
1337 | - |
1338 | - %%%% actions |
1339 | - auto_attach[/Try to Attach/] |
1340 | - trigger_retry[/Create Retry Flag File/] |
1341 | - trigger_retry2[/Create Retry Flag File/] |
1342 | - poll_gcp[/Poll for cloud Pro license/] |
1343 | - daemon_attach[/Try to Attach/] |
1344 | - daemon_attach2[/Try to Attach/] |
1345 | - wait[/Wait a while/] |
1346 | - |
1347 | - %%%% systemd units |
1348 | - auto(ua-auto-attach.service) |
1349 | - daemon(ubuntu-advantage.service) |
1350 | - |
1351 | - %%%% states |
1352 | - done([End]) |
1353 | - |
1354 | - |
1355 | - %% arrows |
1356 | - is_pro--Yes-->auto |
1357 | - auto-->auto_attach |
1358 | - subgraph ua-auto-attach.service blocks boot |
1359 | - auto_attach-->auto_outcome |
1360 | - auto_outcome--No-->trigger_retry |
1361 | - end |
1362 | - |
1363 | - is_pro--No-->is_attached |
1364 | - trigger_retry-->is_attached |
1365 | - auto_outcome--Yes-->is_attached |
1366 | - is_attached--No-->should_run_daemon |
1367 | - is_attached--Yes-->done |
1368 | - should_run_daemon--No-->done |
1369 | - should_run_daemon--Yes-->daemon |
1370 | - |
1371 | - daemon-->is_gcp |
1372 | - subgraph ubuntu-advantage.service |
1373 | - is_gcp--Yes-->poll_gcp |
1374 | - subgraph poll for pro license |
1375 | - poll_gcp-->is_gcp_pro |
1376 | - is_gcp_pro--No-->poll_gcp |
1377 | - is_gcp_pro--Yes-->daemon_attach |
1378 | - daemon_attach-->daemon_attach_outcome |
1379 | - daemon_attach_outcome--No-->trigger_retry2 |
1380 | - end |
1381 | - trigger_retry2-->is_retry |
1382 | - is_gcp--No-->is_retry |
1383 | - is_retry--Yes-->daemon_attach2 |
1384 | - subgraph retry auto-attach |
1385 | - daemon_attach2-->daemon_attach_outcome2 |
1386 | - daemon_attach_outcome2--No-->wait |
1387 | - end |
1388 | - wait-->daemon_attach2 |
1389 | - end |
1390 | - |
1391 | - daemon_attach_outcome--Yes-->done |
1392 | - is_retry--No-->done |
1393 | - daemon_attach_outcome2--Yes-->done |
1394 | - daemon_attach_outcome2--Failed for a month-->done |
1395 | -``` |
1396 | diff --git a/dev-docs/howtoguides/build-docs.md b/dev-docs/howtoguides/build-docs.md |
1397 | deleted file mode 100644 |
1398 | index f2a2606..0000000 |
1399 | --- a/dev-docs/howtoguides/build-docs.md |
1400 | +++ /dev/null |
1401 | @@ -1,11 +0,0 @@ |
1402 | -# How to generate Ubuntu Pro Client user documentation |
1403 | - |
1404 | -To build the docs for Ubuntu Pro Client, you can use a dedicated `tox` command for it. |
1405 | -You can install `tox` on your machine by running the `make test` command. Once tox is |
1406 | -installed just run the command: |
1407 | - |
1408 | -```console |
1409 | -$ tox -e docs |
1410 | -``` |
1411 | - |
1412 | -The command will generate the html pages inside `docs/build` |
1413 | diff --git a/dev-docs/howtoguides/building.md b/dev-docs/howtoguides/building.md |
1414 | deleted file mode 100644 |
1415 | index 40b4d70..0000000 |
1416 | --- a/dev-docs/howtoguides/building.md |
1417 | +++ /dev/null |
1418 | @@ -1,43 +0,0 @@ |
1419 | -# Building |
1420 | - |
1421 | -Packages ubuntu-advantage-tools and ubuntu-advantage-pro are created from the |
1422 | -debian/control file in this repository. You can build the |
1423 | -packages the way you would normally build a Debian package: |
1424 | - |
1425 | - |
1426 | -```shell |
1427 | -dpkg-buildpackage -us -uc |
1428 | -``` |
1429 | - |
1430 | -> **Note** |
1431 | -> It will build the packages with dependencies for the Ubuntu release on |
1432 | -> which you are building, so it's best to build in a container or kvm for the |
1433 | -> release you are targeting. |
1434 | - |
1435 | -OR, if you want to build for a target release other than the release |
1436 | -you're on: |
1437 | - |
1438 | -## using sbuild |
1439 | -[configure sbuild](https://wiki.ubuntu.com/SimpleSbuild) and |
1440 | -use that for the build: |
1441 | - |
1442 | -Setup some chroots for sbuild with this script |
1443 | -```shell |
1444 | -bash ./tools/setup_sbuild.sh |
1445 | -``` |
1446 | - |
1447 | -```shell |
1448 | -debuild -S |
1449 | -sbuild --dist=<target> ../ubuntu-advantage-tools_*.dsc |
1450 | -# emulating different architectures in sbuild-launchpad-chroot |
1451 | -sbuild-launchpad-chroot create --architecture="riscv64" "--name=focal-riscv64" "--series=focal" |
1452 | -``` |
1453 | - |
1454 | -> **Note** |
1455 | -> Every so often, it is recommended to update your chroots. |
1456 | -> ```bash |
1457 | -> # to update a single chroot |
1458 | -> sudo sbuild-launchpad-chroot update -n ua-xenial-amd64 |
1459 | -> # this script can be used to update all chroots |
1460 | -> sudo PATTERN=\* sh /usr/share/doc/sbuild/examples/sbuild-debian-developer-setup-update-all |
1461 | -> ``` |
1462 | diff --git a/dev-docs/howtoguides/code_formatting.md b/dev-docs/howtoguides/code_formatting.md |
1463 | deleted file mode 100644 |
1464 | index 153b134..0000000 |
1465 | --- a/dev-docs/howtoguides/code_formatting.md |
1466 | +++ /dev/null |
1467 | @@ -1,25 +0,0 @@ |
1468 | -# Code Formatting |
1469 | - |
1470 | -The `ubuntu-advantage-client` code base is formatted using |
1471 | -[black](https://github.com/psf/black), and imports are sorted with |
1472 | -[isort](https://github.com/PyCQA/isort). When making changes, you |
1473 | -should ensure that your code is blackened and isorted, or it will |
1474 | -be rejected by CI. |
1475 | -Formatting the whole codebase is as simple as running: |
1476 | - |
1477 | -```shell |
1478 | -black uaclient/ |
1479 | -isort uaclient/ |
1480 | -``` |
1481 | - |
1482 | -To make it easier to avoid committing incorrectly formatted code, this |
1483 | -repo includes configuration for [pre-commit](https://pre-commit.com/) |
1484 | -which will stop you from committing any code that isn't blackened. To |
1485 | -install the project's pre-commit hook, install `pre-commit` and run: |
1486 | - |
1487 | -```shell |
1488 | -pre-commit install |
1489 | -``` |
1490 | - |
1491 | -(To install `black` and `pre-commit` at the appropriate versions for |
1492 | -the project, you should install them via `dev-requirements.txt`.) |
1493 | diff --git a/dev-docs/howtoguides/detach_pro_instances.md b/dev-docs/howtoguides/detach_pro_instances.md |
1494 | deleted file mode 100644 |
1495 | index 5bbf541..0000000 |
1496 | --- a/dev-docs/howtoguides/detach_pro_instances.md |
1497 | +++ /dev/null |
1498 | @@ -1,25 +0,0 @@ |
1499 | -# How to permanently detach Pro instances |
1500 | - |
1501 | -## TL;DR |
1502 | - |
1503 | -1. Modify the client configuration file, normally `/etc/ubuntu-advantage/uaclient.conf`, |
1504 | -to contain: |
1505 | - |
1506 | - ```yaml |
1507 | - features: |
1508 | - disable_auto_attach: true |
1509 | - ``` |
1510 | - |
1511 | -2. Perform a `sudo pro detach --assume-yes`. |
1512 | - |
1513 | -## Explanation |
1514 | - |
1515 | -On Pro instances, a `pro detach` won't permanently detach them as, |
1516 | -the instance will be reauto-attached on the next boot (on non GCE instances) |
1517 | -or immediately (on GCE instances due to the daemon). |
1518 | - |
1519 | -The config in step 1 will prevent the [daemon](../../systemd/ubuntu-advantage.service) |
1520 | -and the a [service](../../systemd/ua-auto-attach.service) at next boot to auto-reattach. |
1521 | - |
1522 | -If you want to allow the instance to reauto attach by itself, then remove or set to false |
1523 | -`disable_auto_attach` in the configuration file. |
1524 | diff --git a/dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md b/dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md |
1525 | deleted file mode 100644 |
1526 | index c06c32b..0000000 |
1527 | --- a/dev-docs/howtoguides/how_to_use_magic_attach_endpoints.md |
1528 | +++ /dev/null |
1529 | @@ -1,168 +0,0 @@ |
1530 | -# How to use magic attach API endpoints |
1531 | - |
1532 | -> **Note** |
1533 | -> Minimum version: 27.11 |
1534 | - |
1535 | -Th Ubuntu Pro Client provides three distinct endpoints to make it easier to perform |
1536 | -the magic attach flow. They are: |
1537 | - |
1538 | -* u.pro.attach.magic.initiate.v1 |
1539 | -* u.pro.attach.magic.wait.v1 |
1540 | -* u.pro.attach.magic.revoke.v1 |
1541 | - |
1542 | -We will explain how to use each endpoint and what is the expected output for each of them. |
1543 | - |
1544 | -## Initiate endpoint |
1545 | - |
1546 | -To start the magic attach flow, we need to create a token for it. The initiate endpoint |
1547 | -will perform exactly that. When you run: |
1548 | - |
1549 | -```console |
1550 | -$ pro api u.pro.attach.magic.initiate.v1 |
1551 | -``` |
1552 | - |
1553 | -It is expected for you to see the following json response: |
1554 | - |
1555 | -```json |
1556 | -{ |
1557 | - "_schema_version": "v1", |
1558 | - "data": { |
1559 | - "meta": { |
1560 | - "environment_vars": [] |
1561 | - }, |
1562 | - "attributes": { |
1563 | - "expires": "EXPIRE_DATE", |
1564 | - "expires_in": 10000, |
1565 | - "token": "MAGIC_ATTACH_TOKEN", |
1566 | - "user_code": "USER_CODE" |
1567 | - }, |
1568 | - "type": "MagicAttachInitiate" |
1569 | - }, |
1570 | - "errors": [], |
1571 | - "result": "success", |
1572 | - "version": "UBUNTU PRO CLIENT VERSION", |
1573 | - "warnings": [] |
1574 | -} |
1575 | -``` |
1576 | - |
1577 | -It is noteworthy here that the `attributes` contain both the `user_code` and `token`. The `user_code` |
1578 | -is the information that will be presented to the user, which it will make possible for the user |
1579 | -to validate the magic attach on the Ubuntu Pro portal. Additionally, the `token` information is required |
1580 | -for the other two API endpoints which will be described next. |
1581 | - |
1582 | - |
1583 | -## Wait endpoint |
1584 | - |
1585 | -After we initiate the magic attach procedure, the user must go to the Ubuntu Pro portal and validate |
1586 | -the `user_code` it received. Once that is done, a contract token will be generated for the user, allowing |
1587 | -the attach procedure to begin. The wait endpoint will wait for the user to perform all of those |
1588 | -steps on the Ubuntu Pro portal. To call it, use: |
1589 | - |
1590 | -```console |
1591 | -$ pro api u.pro.attach.magic.wait.v1 --args magic_token=MAGIC_ATTACH_TOKEN |
1592 | -``` |
1593 | - |
1594 | -Note here that the command requires the `token` that was generated in the initiate step. This command |
1595 | -will block and poll the server until there are any updates for that token. If the |
1596 | -user successfully performed the necessary steps on the Ubuntu Pro portal, we should see the following |
1597 | -response: |
1598 | - |
1599 | -```json |
1600 | -{ |
1601 | - "_schema_version": "v1", |
1602 | - "data": { |
1603 | - "attributes": { |
1604 | - "contract_id": "CONTRACT_ID", |
1605 | - "contract_token": "CONTRACT_TOKEN", |
1606 | - "expires": "EXPIRE_DATE", |
1607 | - "expires_in": 10000, |
1608 | - "token": "MAGIC_ATTACH_TOKEN", |
1609 | - "user_code": "USER_CODE" |
1610 | - } |
1611 | - "type": "MagicAttachInitiate" |
1612 | - }, |
1613 | - "errors": [], |
1614 | - "result": "success", |
1615 | - "version": "UBUNTU PRO CLIENT VERSION", |
1616 | - "warnings": [] |
1617 | -} |
1618 | -``` |
1619 | - |
1620 | -The `contract_token` is the token that can be used to perform an attach operation. |
1621 | - |
1622 | -If the provided token is invalid or has expired, we will see the following response: |
1623 | - |
1624 | -```json |
1625 | -{ |
1626 | - "_schema_version": "v1", |
1627 | - "data": { |
1628 | - "meta": { |
1629 | - "environment_vars": [] |
1630 | - } |
1631 | - }, |
1632 | - "errors": [ |
1633 | - { |
1634 | - "code": "magic-attach-token-error", |
1635 | - "meta": {}, |
1636 | - "title": "The magic attach token is invalid, has expired or never existed" |
1637 | - } |
1638 | - ], |
1639 | - "result": "failure", |
1640 | - "version": "UBUNTU PRO CLIENT VERSION", |
1641 | - "warnings": [] |
1642 | -} |
1643 | -``` |
1644 | - |
1645 | -It is expected that the token will be valid for about 10 minutes. Therefore, we expect the wait |
1646 | -command to keep polling for about that amount of time. |
1647 | - |
1648 | - |
1649 | -## Revoke |
1650 | - |
1651 | -If we want to revoke the token created during the initiate call, we can use the revoke command: |
1652 | - |
1653 | -```console |
1654 | -$ pro api u.pro.attach.magic.revoke.v1 --args magic_token=MAGIC_ATTACH_TOKEN |
1655 | -``` |
1656 | - |
1657 | -If the token is valid, we should see the following output: |
1658 | - |
1659 | -```json |
1660 | -{ |
1661 | - "_schema_version": "v1", |
1662 | - "data": { |
1663 | - "attributes": {}, |
1664 | - "meta": { |
1665 | - "environment_vars": [] |
1666 | - }, |
1667 | - "type": "MagicAttachRevoke" |
1668 | - }, |
1669 | - "errors": [], |
1670 | - "result": "success", |
1671 | - "version": "PRO CLIENT VERSION", |
1672 | - "warnings": [] |
1673 | -} |
1674 | -``` |
1675 | - |
1676 | -However, if the token is already expired or even invalid, we will see the following output: |
1677 | - |
1678 | -```json |
1679 | -{ |
1680 | - "_schema_version": "v1", |
1681 | - "data": { |
1682 | - "meta": { |
1683 | - "environment_vars": [] |
1684 | - } |
1685 | - }, |
1686 | - "errors": [ |
1687 | - { |
1688 | - "code": "magic-attach-token-error", |
1689 | - "meta": {}, |
1690 | - "title": "The magic attach token is invalid, has expired or never existed" |
1691 | - } |
1692 | - ], |
1693 | - "result": "failure", |
1694 | - "version": "PRO CLIENT VERSION", |
1695 | - "warnings": [] |
1696 | -} |
1697 | -``` |
1698 | diff --git a/dev-docs/howtoguides/release_a_new_version.md b/dev-docs/howtoguides/release_a_new_version.md |
1699 | deleted file mode 100644 |
1700 | index 44ebd48..0000000 |
1701 | --- a/dev-docs/howtoguides/release_a_new_version.md |
1702 | +++ /dev/null |
1703 | @@ -1,227 +0,0 @@ |
1704 | -# Ubuntu Pro Client releases |
1705 | - |
1706 | -## Background |
1707 | - |
1708 | -The release process for ubuntu-advantage-tools has three overarching steps/goals. |
1709 | - |
1710 | -1. Release to our team infrastructure. This includes GitHub and the `ua-client` PPAs. |
1711 | -2. Release to the latest Ubuntu devel release. |
1712 | -3. Release to the supported Ubuntu past releases via [SRU](https://wiki.ubuntu.com/StableReleaseUpdates) using the [ubuntu-advantage-tools specific SRU process](https://wiki.ubuntu.com/UbuntuAdvantageToolsUpdates). |
1713 | - |
1714 | -Generally speaking, these steps happen in order, but there is some overlap. Also we may backtrack if issues are found part way through the process. |
1715 | - |
1716 | -An average release should take somewhere between 10 and 14 calendar days if things go smoothly, starting at the decision to release and ending at the new version being available in all supported Ubuntu releases. Note that it is not 2 weeks of full time work. Most of the time is spent waiting for review or sitting in proposed. |
1717 | - |
1718 | -> **Warning** |
1719 | -> If the release contains any change listed in the [Early Review Sign-Off list](../references/early_review_signoff.md), make sure it was properly reviewed *before* starting the release process. Ideally they would be reviewed even before implementation, but if some feature is in the list and didn't get a proper review, now is the time to do so. |
1720 | - |
1721 | -## Prerequisites |
1722 | - |
1723 | -If this is your first time releasing ubuntu-advantage-tools, you'll need to do the following before getting started: |
1724 | - |
1725 | -* Add the team helper scripts to your PATH: [uss-tableflip](https://github.com/canonical/uss-tableflip). |
1726 | -* If you don't yet have a gpg key set up, follow the instructions |
1727 | - [here](https://help.launchpad.net/YourAccount/ImportingYourPGPKey) to create a key, |
1728 | - publish it to `hkp://keyserver.ubuntu.com`, and import it into Launchpad. |
1729 | -* Before you run `sbuild-it` for the first time, you'll need to set up a chroot for each Ubuntu release. |
1730 | - Run the following to set up chroots with dependencies pre-installed for each release: |
1731 | - ```bash |
1732 | - apt-get install sbuild-launchpad-chroot |
1733 | - bash ./tools/setup_sbuild.sh # This will give you usage information on how to call it with the correct parameters |
1734 | - ``` |
1735 | -* You must have Launchpad already properly configured in your system in order to upload packages to the PPAs. Follow [this guide](https://help.launchpad.net/Packaging/PPA/Uploading) to get set up. |
1736 | - |
1737 | -* In order to run the `ppa` command, install `ppa-dev-tools` from `bryce`'s PPA: |
1738 | - ```bash |
1739 | - sudo add-apt-repository ppa:bryce/ppa-dev-tools |
1740 | - sudo apt update |
1741 | - sudo apt install ppa-dev-tools |
1742 | - ``` |
1743 | - When running `ppa` for the first time, there will be another round of launchpad authorization to be performed. |
1744 | - |
1745 | -## I. Preliminary/staging release to team infrastructure |
1746 | -1. Create a release PR: |
1747 | - |
1748 | - a. Move the desired commits from our `main` branch onto the desired release branch. |
1749 | - |
1750 | - * This step is currently not well defined. We currently are using `release-27` for all `27.X` releases and have been cherry-picking/rebasing all commits from `main` into this branch for a release. |
1751 | - |
1752 | - b. Create a new entry in the `debian/changelog` file: |
1753 | - |
1754 | - * You can do that by running `dch --newversion <version-name>`. |
1755 | - * Remember to update the release from `UNRELEASED` to the ubuntu/devel release. Edit the version to look like: `27.2`, with the appropriate pro-client version number. |
1756 | - * Populate `debian/changelog` with the commits you have cherry-picked. |
1757 | - * You can do that by running `git log <first-cherry-pick-commit>..<last-cherry-pick-commit> | log2dch` |
1758 | - * This will generate a list of commits that could be included in the changelog. |
1759 | - * You don't need to include all of the commits generated. Remember that the changelog should |
1760 | - be read by the user to understand the new features/modifications in the package. If you |
1761 | - think a commit will not add that much to the user experience, you can drop it from the |
1762 | - changelog. |
1763 | - * To structure the changelog you can use the other entries as example. But we basically try to |
1764 | - keep this order: debian changes, new features/modifications, testing. Within each section, bullet points should be alphabetized. |
1765 | - |
1766 | - c. Create a PR on GitHub into the release branch. Ask in the ~UA channel on Mattermost for review. |
1767 | - |
1768 | - d. When reviewing the release PR, please use the following guidelines when reviewing the new changelog entry: |
1769 | - |
1770 | - * Is the version correctly updated? We must ensure that the new version in the changelog is |
1771 | - correct and it also targets the latest Ubuntu release at the moment. |
1772 | - * Is the entry useful for the user? The changelog entries should be user focused, meaning |
1773 | - that we should only add entries that we think users will care about (i.e. we don't need |
1774 | - entries when fixing a test, as this doesn't provide meaningful information to the user). |
1775 | - * Is this entry redundant? Sometimes we may have changes that affect separate modules of the |
1776 | - code. We should have an entry only for the module that was most affected by it. |
1777 | - * Is the changelog entry unique? We need to verify that the changelog entry is not already |
1778 | - reflected in an earlier version of the changelog. If it is, we need not only to remove but double |
1779 | - check the process we are using to cherry-pick the commits. |
1780 | - * Is this entry actually reflected in the code? Sometimes, we can have changelog entries |
1781 | - that are not reflected in the code anymore. This can happen during development when we are |
1782 | - still unsure about the behaviour of a feature or when we fix a bug that removes the code |
1783 | - that was added. We must verify each changelog entry that is added to be sure of their |
1784 | - presence in the product. |
1785 | - |
1786 | -2. After the release PR is merged, tag the head of the release branch with the version number, e.g., `27.1`. Push this tag to GitHub. |
1787 | - |
1788 | -3. Build the package for all Ubuntu releases and upload to `ppa:ua-client/staging`: |
1789 | - |
1790 | - a. Clone the repository into a clean directory and switch to the release branch. |
1791 | - * *WARNING* Build the package in a clean environment. The reason is that the package |
1792 | - will contain everything that is present in the folder. If you are storing credentials or |
1793 | - other sensible development information in your folder, they will be uploaded too when we send |
1794 | - the package to the ppa. A clean environment is the safest way to perform this. |
1795 | - |
1796 | - b. Edit the changelog |
1797 | - * List yourself as the author of this release. |
1798 | - * Edit the version number to look like: `27.2~rc1` (`<version>~rc<release-candidate-number>`) |
1799 | - * Edit the Ubuntu release name. Start with the ubuntu/devel release. |
1800 | - * `git add debian/changelog && git commit -m "throwaway"` - Do **not** push this commit! |
1801 | - |
1802 | - c. `build-package` |
1803 | - * This script will generate all the package artefacts in the parent directory as `../out`. |
1804 | - |
1805 | - d. `sbuild-it ../out/<package_name>.dsc` |
1806 | - * If this succeeds move on. If this fails, debug and fix before continuing. |
1807 | - |
1808 | - e. Repeat 3.b through 3.d for all supported Ubuntu Releases |
1809 | - * The version for series other than devel should be in the form `<version>~<ubuntu-release-number>~rc<release-candidate-number>` |
1810 | - This means you must add the release number in the changelog. For example, suppose |
1811 | - the devel version is `1.1~rc1`. If you want to build for jammy now, change it to |
1812 | - `1.1~22.04~rc1`. |
1813 | - |
1814 | - f. For each release, dput to the staging PPA: |
1815 | - * `dput ppa:ua-client/staging ../out/<package_name>_source.changes` |
1816 | - * After each `dput` wait for the "Accepted" email from Launchpad before moving on. |
1817 | - |
1818 | -## II. Release to Ubuntu (devel and SRU) |
1819 | - |
1820 | -> **Note** |
1821 | -> `kinetic` is used throughout as a reference to the current devel release. This will change. |
1822 | - |
1823 | -1. Prepare SRU Launchpad bugs. |
1824 | - |
1825 | - a. We do this even before a successful merge into ubuntu/devel because the context added to these bugs is useful for the Server Team reviewer. |
1826 | - |
1827 | - b. Create a new bug on Launchpad for ubuntu-advantage-tools and use the format defined [here](https://wiki.ubuntu.com/UbuntuAdvantageToolsUpdates#SRU_Template) for the description. |
1828 | - * The title should be in the format `[SRU] ubuntu-advantage-tools (27.1 -> 27.2) Xenial, Bionic, Focal, Jammy`, substituting version numbers and release names as necessary. |
1829 | - * If any of the changes for the SRU is in the [Early Review Sign-off list](../references/early_review_signoff.md), include a pointer in the `[Discussion]` section to where the discussion/approval of that feature took place (if possible). |
1830 | - |
1831 | - c. For each Launchpad bug fixed by this release (which should all be referenced in our changelog), add the SRU template to the description and fill out each section. |
1832 | - * Leave the original description in the bug at the bottom under the header `[Original Description]`. |
1833 | - * For the testing steps, include steps to reproduce the bug. Then include instructions for adding `ppa:ua-client/staging`, and steps to verify the bug is no longer present. |
1834 | - |
1835 | -2. Set up the Merge Proposal (MP) for ubuntu/devel: |
1836 | - |
1837 | - a. `git-ubuntu clone ubuntu-advantage-tools; cd ubuntu-advantage-tools` |
1838 | - |
1839 | - b. `git remote add upstream git@github.com:canonical/ubuntu-advantage-client.git` |
1840 | - |
1841 | - c. `git fetch upstream` |
1842 | - |
1843 | - d. `git rebase --onto pkg/ubuntu/devel <last-version-tag> <this-version-tag>` |
1844 | - * e.g. `git rebase --onto pkg/ubuntu/devel 27.0.2 27.1` |
1845 | - * You may need to resolve conflicts, but hopefully these will be minimal. |
1846 | - * You'll end up in a detached state. |
1847 | - |
1848 | - e. `git checkout -B upload-<this-version>-kinetic` |
1849 | - * This creates a new local branch name based on your detached branch. |
1850 | - |
1851 | - f. `git push <your_launchpad_user> upload-<this-version>-kinetic` |
1852 | - |
1853 | - g. On Launchpad, create a merge proposal for this version which targets `ubuntu/devel` |
1854 | - * For an example, see the [27.14.1 merge proposal](https://code.launchpad.net/~renanrodrigo/ubuntu/+source/ubuntu-advantage-tools/+git/ubuntu-advantage-tools/+merge/439507). |
1855 | - * Add 2 review slots for `canonical-server-reporter` and `canonical-server-core-reviewers`. |
1856 | - |
1857 | - h. With the packages published to `ppa:ua-client/staging`, add links to the autopkgtest triggers to the Merge Proposal. The reviewer will have permission to trigger those tests. The links can be obtained by running `ppa tests -r <release> -a <arch1,arch2> ua-client/staging -L` |
1858 | - * Make sure to post links to all the architectures built for a given release. |
1859 | - * The riscv64 autopkgtests are not avaialble and don't need to be included. |
1860 | - * The `ppa test` command will have two variations of tests: the regular one, and one with `all-proposed=1`; only the regular test need to be there. |
1861 | - |
1862 | -3. Server Team Review and Pre-SRU Review |
1863 | - |
1864 | - a. Ask the assigned ubuntu-advantage-tools reviewer/sponsor from Server team for a review of your MPs. If you don't know who that is, ask in ~Server. Include a link to the ubuntu/devel MP and to the SRU bug. |
1865 | - |
1866 | - b. If they request changes, create a PR into the release branch on GitHub and ask Pro Client team for review. After that is merged, cherry-pick the commit into your `upload-<this-version>-<devel-release>` branch and push to launchpad. Then notify the Server Team member that you have addressed their requests. |
1867 | - * Some issues may just be filed for addressing in the future if they are not urgent or pertinent to this release. |
1868 | - * Unless the changes are very minor, or only testing related, you should upload a new release candidate version to `ppa:ua-client/staging` as described in I.3. |
1869 | - * After the release is finished, any commits that were merged directly into the release branch in this way should be brought back into `main` via a single PR. |
1870 | - |
1871 | - c. Once review is complete and approved, the Server Team member should **not** upload the version to the devel release. |
1872 | - * If they do, then any changes to the code after this point will require a bump in the patch version of the release. |
1873 | - |
1874 | - d. Now ask the SRU team for a pre-SRU review of the same MP. Mention that the exact same code will be released to all stable Ubuntu releases. |
1875 | - * Follow instructions in `II.4.b` if they request any changes. |
1876 | - |
1877 | - e. Once the SRU team member gives a pre-SRU approval, create the branches for each stable release. They should be named `upload-<this-version>-<codename>`. |
1878 | - * The versions for the stable releases must include `~<release-number>` |
1879 | - * If you've followed the instructions precisely so far, you can just run `bash tools/create-lp-release-branches.sh`. |
1880 | - - When using the `create-lp-release-branches.sh` script, an important parameter is `SRU_BUG`: |
1881 | - - In the vast majority of cases, this should be set to the overall SRU bug written in step II.1.b. |
1882 | - - In the case where an existing SRU never got released, and a new patch version was uploaded on top of it to fix a new bug discovered during review, then the bug should still be the overall SRU bug. |
1883 | - - If the release is exclusively a bugfix release and the previous version has already been successfully released all the way through the SRU process, then the bug should instead be the specific bugfix number. |
1884 | - |
1885 | - f. Ask Server team member sponsor to upload to devel, and then the SRU proposed queue using the stable release branches you just created. |
1886 | - * Ask them to tag the PR with the appropriate `upload/<version>` tag so git-ubuntu will import rich commit history. |
1887 | - * If they do not have upload rights to the proposed queue, ask in ~Server channel for a Ubuntu Server team member with upload rights for an upload review of the MP for the proposed queue. |
1888 | - |
1889 | - g. Check the [-proposed release queue](https://launchpad.net/ubuntu/xenial/+queue?queue_state=1&queue_text=ubuntu-advantage-tools) for presence of ubuntu-advantage-tools in unapproved state for each supported release. Note: libera chat #ubuntu-release IRC channel has a bot that reports queued uploads of any package in a message like "Unapproved: ubuntu-advantage-tools .. version". |
1890 | - |
1891 | - h. Tell the SRU team member who performed the pre-SRU review that the packages are in the -proposed release queue. They will need to actually approve the package to move into -proposed. |
1892 | - |
1893 | -4. -proposed verification and release to -updates |
1894 | - |
1895 | - a. As soon as the SRU vanguard approves the packages, a bot in #ubuntu-release will announce that ubuntu-advantage-tools is accepted into the applicable -proposed pockets, or the [Xenial -proposed release rejection queue](https://launchpad.net/ubuntu/xenial/+queue?queue_state=4&queue_text=ubuntu-advantage-tools) will contain a reason for rejections. Double check the SRU process bug for any actionable review feedback. |
1896 | - * Once accepted into `-proposed` by an SRU vanguard [ubuntu-advantage-tools shows up in the pending_sru page](https://people.canonical.com/~ubuntu-archive/pending-sru.html), check `rmadison ubuntu-advantage-tools | grep -proposed` to see if the upload exists in -proposed yet. |
1897 | - * Also actually check that the packages are accessible in a container by [enabling proposed](https://wiki.ubuntu.com/Testing/EnableProposed) and updating the package. |
1898 | - |
1899 | - b. With the package in proposed, perform the steps from `I.3` above but use a `~stableppaX` suffix instead of `~rcX` in the version name, and upload to `ppa:ua-client/stable` instead of staging. |
1900 | - |
1901 | - c. Perform the [Ubuntu-advantage-client SRU verification steps](https://wiki.ubuntu.com/UbuntuAdvantageToolsUpdates). This typically involves running all behave targets with `UACLIENT_BEHAVE_ENABLE_PROPOSED=1 UACLIENT_BEHAVE_CHECK_VERSION=<this-version>` and saving the output. |
1902 | - * There may also be one-time test scripts added in the `sru/` directory for this release. |
1903 | - |
1904 | - d. After all tests have passed, tarball all of the output files and upload them to the SRU bug with a message that looks like this: |
1905 | - |
1906 | - ``` |
1907 | - We have run the full ubuntu-advantage-tools integration test suite against the version in -proposed. The results are attached. All tests passed. |
1908 | - |
1909 | - You can verify the correct version was used by checking the output of the first test in each file, which prints the version number. |
1910 | - |
1911 | - I am marking the verification done for this SRU. |
1912 | - ``` |
1913 | - |
1914 | - Change the tags on the bug from `verification-needed` to `verification-done` (including the verification tags for each Ubuntu release). |
1915 | - |
1916 | - e. For any other related Launchpad bugs that are fixed in this release, perform the verification steps necessary for those bugs and mark them `verification-done` as needed. This will likely involve following the test steps, but instead of adding the staging PPA, enabling -proposed. |
1917 | - |
1918 | - f. Once all SRU bugs are tagged as `verification*-done`, all SRU-bugs should be listed as green in [the pending_sru page](https://people.canonical.com/~ubuntu-archive/pending-sru.html). |
1919 | - |
1920 | - g. After the pending SRU page says that ubuntu-advantage-tools has been in proposed for 7 days, it is now time to ping the [current SRU vanguard](https://wiki.ubuntu.com/StableReleaseUpdates#Publishing) for acceptance of ubuntu-advantage-tools into -updates. |
1921 | - |
1922 | - h. Check `rmadison ubuntu-advantage-tools` for updated version in -updates. |
1923 | - * Also actually check that the packages are accessible in a container and updating the package. |
1924 | - |
1925 | -## III. Post-release updates |
1926 | - |
1927 | -1. Ensure the version tag is correct on GitHub. The `version` git tag should point to the commit that was released as that version to ubuntu -updates. If changes were made in response to feedback during the release process, the tag may have to be moved. |
1928 | -2. Bring in any changes that were made to the release branch into `main` via PR (e.g., changelog edits). |
1929 | -3. Move any scripts added in `sru/` to a new folder in `sru/_archive` for the release. |
1930 | -4. Tell CPC that there is a new version of `ubuntu-advantage-tools` in -updates for all series. |
1931 | diff --git a/dev-docs/howtoguides/testing.md b/dev-docs/howtoguides/testing.md |
1932 | deleted file mode 100644 |
1933 | index 24706d4..0000000 |
1934 | --- a/dev-docs/howtoguides/testing.md |
1935 | +++ /dev/null |
1936 | @@ -1,247 +0,0 @@ |
1937 | -# Testing |
1938 | -All unit and lint tests are run using `tox`, with different versions of Python with specific constraints. We also use `tox-setuptools-version` to specify the correct setuptools version based on what is present in each release, and `tox-pyenv` to recognize the different local [pyenv interpreters](https://github.com/pyenv/pyenv). |
1939 | - |
1940 | -First, run the script to install and configure `pyenv`, and the `tox` dependencies: |
1941 | - |
1942 | -```shell |
1943 | -./tools/setup_pyenv.sh |
1944 | -``` |
1945 | - |
1946 | -After that you need to [set up your shell environment](https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv), according to the pyenv documentation. |
1947 | -The guide has quick snippets to configure `bash`, `zsh` and `fish` shells. |
1948 | - |
1949 | -Refresh your terminal to make sure pyenv is working. Then you can run the unit and lint tests: |
1950 | - |
1951 | -```shell |
1952 | -tox |
1953 | -``` |
1954 | - |
1955 | -> **Note** |
1956 | -> There are a number of `autouse` mocks in our unit tests. These are intended to prevent accidental side effects on the host system from running the unit tests, as well as prevent leaks of the system environment into the unit tests. |
1957 | -> One such `autouse` mock tells the unit tests that they are run as root (unless the mock is overriden for a particular test). |
1958 | -> These `autouse` mocks have helped, but may not be preventing all side effects or environment leakage. |
1959 | - |
1960 | -The client also includes built-in dep8 tests. These are run as follows: |
1961 | - |
1962 | -```shell |
1963 | -autopkgtest -U --shell-fail . -- lxd ubuntu:xenial |
1964 | -``` |
1965 | - |
1966 | -## Integration Tests |
1967 | - |
1968 | -Ubuntu Pro Client uses [behave](https://behave.readthedocs.io) |
1969 | -for its integration testing. |
1970 | - |
1971 | -The integration test definitions are stored in the `features/` |
1972 | -directory and consist of two parts: `.feature` files that define the |
1973 | -tests we want to run, and `.py` files which implement the underlying |
1974 | -logic for those tests. |
1975 | - |
1976 | -By default, integration tests will do the following on a given cloud platform: |
1977 | - * Launch an instance running latest daily image of the target Ubuntu release |
1978 | - * Add the Ubuntu Pro client daily build PPA: [ppa:ua-client/daily](https://code.launchpad.net/~ua-client/+archive/ubuntu/daily) |
1979 | - * Install the appropriate ubuntu-advantage-tools and ubuntu-advantage-pro deb |
1980 | - * Run the integration tests on that instance. |
1981 | - |
1982 | -The testing can be overridden to install ubuntu-advantage-tools from other sources instead of the daily PPA by providing `UACLIENT_BEHAVE_INSTALL_FROM` to the behave test runner. The default is `UACLIENT_BEHAVE_INSTALL_FROM=daily`, and the other available options are: |
1983 | - |
1984 | -- `staging`: install from the [staging PPA](https://code.launchpad.net/~ua-client/+archive/ubuntu/staging) |
1985 | -- `stable`: install from the [stable PPA](https://code.launchpad.net/~ua-client/+archive/ubuntu/stable) |
1986 | -- `archive`: install the latest version available in the archive, not adding any PPA |
1987 | -- `proposed`: install the package from the -proposed pocket - specially useful for SRU testing (see [the release guide](how_to_release_a_new_version_of_ua.md)) |
1988 | -- `custom`: install from a custom provided PPA. If set, then two other variables need to be set: `UACLIENT_BEHAVE_CUSTOM_PPA=<PPA URL>` and `UACLIENT_BEHAVE_CUSTOM_PPA_KEYID=<signing key for the PPA>`. |
1989 | -- `local`: install from a local copy of the ubuntu-advantage-client source code |
1990 | - |
1991 | -`local` is particularly useful, as it runs the suite against the local code, thus including and validating the latest changes made. It is advised to run any related integration tests against local code changes before pushing them to be reviewed. |
1992 | - |
1993 | -> **Note** |
1994 | -> Note that we cache the source when running with `UACLIENT_BEHAVE_INSTALL_FROM=local` based on a hash, calculated from the repository state. If you change the python code locally and run the behave tests against your new version, there will be new debs in the cache source with the new repo state hash. |
1995 | - |
1996 | -To run the tests, you can use `tox`: |
1997 | - |
1998 | -```shell |
1999 | -tox -e behave-lxd-20.04 |
2000 | -``` |
2001 | - |
2002 | -or, if you just want to run a specific file, or a test within a file: |
2003 | - |
2004 | -```shell |
2005 | -tox -e behave-lxd-20.04 features/unattached_commands.feature |
2006 | -tox -e behave-lxd-20.04 features/unattached_commands.feature:28 |
2007 | -``` |
2008 | - |
2009 | -As can be seen, this will run behave tests only for release 20.04 (Focal Fossa). We are currently |
2010 | -supporting 5 distinct releases: |
2011 | - |
2012 | -* 21.10 (Kinetic Kudu) |
2013 | -* 22.04 (Jammy Jellyfish) |
2014 | -* 20.04 (Focal Fossa) |
2015 | -* 18.04 (Bionic Beaver) |
2016 | -* 16.04 (Xenial Xerus) |
2017 | - |
2018 | -Therefore, to change which release to run the behave tests against, just change the release version |
2019 | -on the behave command. |
2020 | - |
2021 | -Furthermore, when developing/debugging a new scenario: |
2022 | - |
2023 | - 1. Add a `@wip` tag decorator on the scenario |
2024 | - 2. To only run @wip scenarios run: `tox -e behave-lxd-20.04 -- -w` |
2025 | - 3. If you want to use a debugger: |
2026 | - 1. Add ipdb to integration-requirements.txt |
2027 | - 2. Add ipdb.set_trace() in the code block you wish to debug |
2028 | - |
2029 | -(If you're getting started with behave, we recommend at least reading |
2030 | -through [the behave |
2031 | -tutorial](https://behave.readthedocs.io/en/latest/tutorial.html) to get |
2032 | -an idea of how it works, and how tests are written.) |
2033 | - |
2034 | -## Iterating Locally |
2035 | - |
2036 | -To make running the tests repeatedly less time-intensive, our behave |
2037 | -testing setup has support for reusing images between runs via two |
2038 | -configuration options (provided in environment variables), |
2039 | -`UACLIENT_BEHAVE_IMAGE_CLEAN` and `UACLIENT_BEHAVE_REUSE_IMAGE`. |
2040 | - |
2041 | -To avoid the test framework cleaning up the image it creates, you can |
2042 | -run it like this: |
2043 | - |
2044 | -```sh |
2045 | -UACLIENT_BEHAVE_IMAGE_CLEAN=0 tox -e behave |
2046 | -``` |
2047 | - |
2048 | -which will emit a line like this above the test summary: |
2049 | - |
2050 | -``` |
2051 | -Image cleanup disabled, not deleting: behave-image-1572443113978755 |
2052 | -``` |
2053 | - |
2054 | -You can then reuse that image by plugging its name into your next test |
2055 | -run, like so: |
2056 | - |
2057 | -```sh |
2058 | -UACLIENT_BEHAVE_REUSE_IMAGE=behave-image-1572443113978755 tox -e behave |
2059 | -``` |
2060 | - |
2061 | -If you've done this correctly, you should see something like |
2062 | -`reuse_image = behave-image-1572443113978755` in the "Config options" |
2063 | -output, and test execution should start immediately (without the usual |
2064 | -image build step). |
2065 | - |
2066 | -(Note that this handling is specific to our behave tests as it's |
2067 | -performed in `features/environment.py`, so don't expect to find |
2068 | -documentation about it outside of this codebase.) |
2069 | - |
2070 | -## Optimizing total run time of integration tests with snapshots |
2071 | -When `UACLIENT_BEHAVE_SNAPSHOT_STRATEGY=1` we create a snapshot of an instance |
2072 | -with ubuntu-advantage-tools installed and restore from that snapshot for all tests. |
2073 | -This adds an upfront cost that is amortized across several test scenarios. |
2074 | - |
2075 | -Based on some rough testing in July 2021, these are the situations |
2076 | -when you should set UACLIENT_BEHAVE_SNAPSHOT_STRATEGY=1 |
2077 | - |
2078 | -> At time of writing, starting a lxd-vm instance from a local snapshot takes |
2079 | -> longer than starting a fresh lxd-vm instance and installing ua. |
2080 | - |
2081 | -| machine_type | condition | |
2082 | -| ------------- | ------------------ | |
2083 | -| lxd-container | num_scenarios > 7 | |
2084 | -| lxd-vm | never | |
2085 | -| gcp | num_scenarios > 5 | |
2086 | -| azure | num_scenarios > 14 | |
2087 | -| aws | num_scenarios > 11 | |
2088 | - |
2089 | -## Integration testing on EC2 |
2090 | -The following tox environments allow for testing focal on EC2: |
2091 | - |
2092 | -``` |
2093 | - # To test ubuntu-pro-images |
2094 | - tox -e behave-awspro-20.04 |
2095 | - # To test Canonical cloud images (non-ubuntu-pro) |
2096 | - tox -e behave-awsgeneric-20.04 |
2097 | -``` |
2098 | - |
2099 | -To run the test for a different release, just update the release version string. For example, |
2100 | -to run AWS pro xenial tests, you can run: |
2101 | - |
2102 | -``` |
2103 | -tox -e behave-awspro-16.04 |
2104 | -``` |
2105 | - |
2106 | -In order to run EC2 tests, please set up the [pycloudlib toml |
2107 | -file](https://github.com/canonical/pycloudlib/blob/main/pycloudlib.toml.template) with |
2108 | -the required EC2 credentials. |
2109 | - |
2110 | -To specifically run non-ubuntu pro tests using canonical cloud-images an |
2111 | -additional token obtained from https://ubuntu.com/pro needs to be set: |
2112 | - - UACLIENT_BEHAVE_CONTRACT_TOKEN=<your_token> |
2113 | - |
2114 | -* To manually run EC2 integration tests with a specific AMI Id provide the |
2115 | -following environment variable to launch your specific AMI instead of building |
2116 | -a daily ubuntu-advantage-tools image. |
2117 | -```sh |
2118 | -UACLIENT_BEHAVE_REUSE_IMAGE=your-custom-ami tox -e behave-awspro-20.04 |
2119 | -``` |
2120 | - |
2121 | -## Integration testing on Azure |
2122 | -The following tox environments allow for testing focal on Azure: |
2123 | - |
2124 | -``` |
2125 | - # To test ubuntu-pro-images |
2126 | - tox -e behave-azurepro-20.04 |
2127 | - # To test Canonical cloud images (non-ubuntu-pro) |
2128 | - tox -e behave-azuregeneric-20.04 |
2129 | -``` |
2130 | - |
2131 | -To run the test for a different release, just update the release version string. For example, |
2132 | -to run Azure pro xenial tests, you can run: |
2133 | - |
2134 | -``` |
2135 | -tox -e behave-azurepro-16.04 |
2136 | -``` |
2137 | - |
2138 | -In order to run Azure tests, please set up the [pycloudlib toml |
2139 | -file](https://github.com/canonical/pycloudlib/blob/main/pycloudlib.toml.template) with |
2140 | -the required Azure credentials. |
2141 | - |
2142 | -To specifically run non-ubuntu pro tests using canonical cloud-images an |
2143 | -additional token obtained from https://ubuntu.com/pro needs to be set: |
2144 | - - UACLIENT_BEHAVE_CONTRACT_TOKEN=<your_token> |
2145 | - |
2146 | -* To manually run Azure integration tests with a specific Image Id provide the |
2147 | -following environment variable to launch your specific Image Id instead of building |
2148 | -a daily ubuntu-advantage-tools image. |
2149 | -```sh |
2150 | -UACLIENT_BEHAVE_REUSE_IMAGE=your-custom-image-id tox -e behave-azurepro-20.04 |
2151 | -``` |
2152 | - |
2153 | -## Integration testing on GCP |
2154 | -The following tox environments allow for testing focal on GCP: |
2155 | - |
2156 | -``` |
2157 | - # To test ubuntu-pro-images |
2158 | - tox -e behave-gcppro-20.04 |
2159 | - # To test Canonical cloud images (non-ubuntu-pro) |
2160 | - tox -e behave-gcpgeneric-20.04 |
2161 | -``` |
2162 | - |
2163 | -To run the test for a different release, just update the release version string. For example, |
2164 | -to run GCP pro xenial tests, you can run: |
2165 | - |
2166 | -``` |
2167 | -tox -e behave-gcppro-16.04 |
2168 | -``` |
2169 | - |
2170 | -In order to run GCP tests, please set up the [pycloudlib toml |
2171 | -file](https://github.com/canonical/pycloudlib/blob/main/pycloudlib.toml.template) with |
2172 | -the required GCP credentials. |
2173 | - |
2174 | -To specifically run non-ubuntu pro tests using canonical cloud-images an |
2175 | -additional token obtained from https://ubuntu.com/pro needs to be set: |
2176 | - - UACLIENT_BEHAVE_CONTRACT_TOKEN=<your_token> |
2177 | - |
2178 | -* To manually run GCP integration tests with a specific Image Id provide the |
2179 | -following environment variable to launch your specific Image Id instead of building |
2180 | -a daily ubuntu-advantage-tools image. |
2181 | -```sh |
2182 | -UACLIENT_BEHAVE_REUSE_IMAGE=your-custom-image-id tox -e behave-gcppro-20.04 |
2183 | -``` |
2184 | diff --git a/dev-docs/howtoguides/use_staging_environment.md b/dev-docs/howtoguides/use_staging_environment.md |
2185 | deleted file mode 100644 |
2186 | index b616fce..0000000 |
2187 | --- a/dev-docs/howtoguides/use_staging_environment.md |
2188 | +++ /dev/null |
2189 | @@ -1,13 +0,0 @@ |
2190 | -# Use the contracts staging environment |
2191 | - |
2192 | -You can change the contract server that the Pro Client will use by setting the |
2193 | -following option in your `uaclient.conf` configuration file, (by default located at |
2194 | -`/etc/ubuntu-advantage/uaclient.conf`). |
2195 | - |
2196 | -```yaml |
2197 | -contract_url: https://contracts.staging.canonical.com |
2198 | -``` |
2199 | - |
2200 | -> **Note** |
2201 | -> You might be using a local `uaclient.conf` file when running the pro client. |
2202 | -> If that is the case, remember to change that file instead. |
2203 | diff --git a/dev-docs/references/architecture.md b/dev-docs/references/architecture.md |
2204 | deleted file mode 100644 |
2205 | index a4efbdd..0000000 |
2206 | --- a/dev-docs/references/architecture.md |
2207 | +++ /dev/null |
2208 | @@ -1,18 +0,0 @@ |
2209 | -# Architecture |
2210 | - |
2211 | -Ubuntu Pro Client is a python3-based command line |
2212 | -utility. It provides a CLI to attach, detach, enable, |
2213 | -disable and check status of support related services. |
2214 | - |
2215 | -The package `ubuntu-advantage-tools` also provides a C++ APT hook which helps |
2216 | -advertise ESM service and available packages in MOTD and during various apt |
2217 | -commands. |
2218 | - |
2219 | -The `ubuntu-advantage-pro` package delivers auto-attach functionality via a |
2220 | -systemd service for various cloud platforms. |
2221 | - |
2222 | -By default, Ubuntu machines are deployed in an unattached state. A machine can |
2223 | -get manually or automatically attached to a specific contract by interacting |
2224 | -with the Contract Server REST API. Any change in state of services or machine |
2225 | -attach results in additional interactions with the Contract Server API to |
2226 | -validate such operations. |
2227 | diff --git a/dev-docs/references/daily_builds.md b/dev-docs/references/daily_builds.md |
2228 | deleted file mode 100644 |
2229 | index ea52c39..0000000 |
2230 | --- a/dev-docs/references/daily_builds.md |
2231 | +++ /dev/null |
2232 | @@ -1,4 +0,0 @@ |
2233 | -# Daily Builds |
2234 | - |
2235 | -On Launchpad, there is a [daily build recipe](https://code.launchpad.net/~canonical-server/+recipe/ua-client-daily), |
2236 | -which will build the client and place it in the [ua-client-daily PPA](https://code.launchpad.net/~ua-client/+archive/ubuntu/daily). |
2237 | diff --git a/dev-docs/references/directory_layout.md b/dev-docs/references/directory_layout.md |
2238 | deleted file mode 100644 |
2239 | index 1fc1f77..0000000 |
2240 | --- a/dev-docs/references/directory_layout.md |
2241 | +++ /dev/null |
2242 | @@ -1,31 +0,0 @@ |
2243 | -# Directory layout |
2244 | - |
2245 | -The following describes the intent of Ubuntu Pro Client related directories: |
2246 | - |
2247 | -| File/Directory | Intent | |
2248 | -| -------- | -------- | |
2249 | -| ./tools | Helpful scripts used to publish, release or test various aspects of Ubuntu Pro Client | |
2250 | -| ./features/ | Behave BDD integration tests for Ubuntu Pro Client |
2251 | -| ./uaclient/ | collection of python modules which will be packaged into ubuntu-advantage-tools package to deliver the Ubuntu Pro Client CLI | |
2252 | -| uaclient.entitlements | Service-specific \*Entitlement class definitions which perform enable, disable, status, and entitlement operations etc. All classes derive from base.py:UAEntitlement and many derive from repo.py:RepoEntitlement | |
2253 | -| ./uaclient/cli.py | The entry-point for the command-line client |
2254 | -| ./uaclient/clouds/ | Cloud-platform detection logic used in Ubuntu Pro to determine if a given instance should be auto-attached to a contract | |
2255 | -| uaclient.contract | Module for interacting with the Contract Server API | |
2256 | -| uaclient.messages | Module that contains the messages delivered by `pro` to the user | |
2257 | -| uaclient.security | Module that hold the logic used to run `pro fix` commands | |
2258 | -| ./apt-hook/ | the C++ apt-hook delivering MOTD and apt command notifications about Ubuntu Pro support services | |
2259 | -| /etc/ubuntu-advantage/uaclient.conf | Configuration file for the Ubuntu Pro Client.| |
2260 | -| /var/lib/ubuntu-advantage/private | `root` read-only directory containing Contract API responses, machine-tokens and service credentials | |
2261 | -| /var/lib/ubuntu-advantage/machine-token.json | `world` readable file containing redacted Contract API responses, machine-tokens and service credentials | |
2262 | -| /var/log/ubuntu-advantage.log | `root` read-only log of ubuntu-advantage operations | |
2263 | - |
2264 | -## Note |
2265 | - |
2266 | -We have two `machine-token.json` files, located at: |
2267 | - |
2268 | -- /var/lib/ubuntu-advantage/private/machine-token.json |
2269 | -- /var/lib/ubuntu-advantage/machine-token.json |
2270 | - |
2271 | -The first file, located in the `private` directory, is root read-only. We have another world readable file in the `/var/lib/ubuntu-advantage` directory. |
2272 | - |
2273 | -The latter is currently being used when calling the `pro status` command as a non-root user. This file is redacted to remove any sensitive user data. |
2274 | diff --git a/dev-docs/references/early_review_signoff.md b/dev-docs/references/early_review_signoff.md |
2275 | deleted file mode 100644 |
2276 | index f5d99d8..0000000 |
2277 | --- a/dev-docs/references/early_review_signoff.md |
2278 | +++ /dev/null |
2279 | @@ -1,36 +0,0 @@ |
2280 | -# Early review sign-off |
2281 | -As the Client has a very broad exception for SRUs, there are some features which |
2282 | -need pre-evaluation from people outside the team. |
2283 | - |
2284 | -This pre-evaluation should be performed at specification time, even before any |
2285 | -implementation, to prevent frustration from any side when trying to SRU and to |
2286 | -avoid possible blockers for the process. |
2287 | - |
2288 | -The review for such special features must be performed by: |
2289 | -1. A SRU team member, and |
2290 | -2. Someone from the Ubuntu Core Development team with appropriate expertise on |
2291 | - the topic being changed. |
2292 | - |
2293 | -There may be the case where a single person matches both of the descriptions |
2294 | -above - that is acceptable from the review perspective. |
2295 | - |
2296 | -## Features which need special attention |
2297 | - |
2298 | -The team should request the aforementioned pre-evaluation of any feature which |
2299 | -involves: |
2300 | - |
2301 | -- How the Client interacts with APT |
2302 | -- How the Client interacts with systemd |
2303 | -- Anything that changes network traffic patterns, including anything |
2304 | -that might "phone home" |
2305 | -- Anything that changes the use of persistent processes or scheduled |
2306 | -jobs |
2307 | -- Changes that affect what part of the namespace in PATH we consume |
2308 | -- Actions that take place without an explicit user opt-in* |
2309 | - |
2310 | -New items may be eventually added to this list |
2311 | -(preferrably before any problem happens!). |
2312 | - |
2313 | - |
2314 | -\* executing a CLI command to perform a specific task counts a |
2315 | - opt-in for that task. |
2316 | diff --git a/dev-docs/references/enabling_a_service.md b/dev-docs/references/enabling_a_service.md |
2317 | deleted file mode 100644 |
2318 | index d799972..0000000 |
2319 | --- a/dev-docs/references/enabling_a_service.md |
2320 | +++ /dev/null |
2321 | @@ -1,21 +0,0 @@ |
2322 | -# Enabling a service |
2323 | - |
2324 | -Each service controlled by Ubuntu Pro Client will have a python module in |
2325 | -uaclient/entitlements/\*.py which handles setup and teardown of services when |
2326 | -enabled or disabled. |
2327 | - |
2328 | -If a contract entitles a machine to a service, `root` user can enable the |
2329 | -service with `pro enable <service>`. If a service can be disabled |
2330 | -`pro disable <service>` will be permitted. |
2331 | - |
2332 | -The goal of the Ubuntu Pro Client is to remain simple and flexible and let the |
2333 | -contracts backend drive dynamic changes in contract offerings and constraints. |
2334 | -In pursuit of that goal, the Ubuntu Pro Client obtains most of it's service constraints |
2335 | -from a machine token that it obtains from the Contract Server API. |
2336 | - |
2337 | -The Ubuntu Pro Client is simple in that it relies on the machine token on the attached |
2338 | -machine to describe whether a service is applicable for an environment and what |
2339 | -configuration is required to properly enable that service. |
2340 | - |
2341 | -Any interactions with the Contract Server API are defined as UAContractClient |
2342 | -class methods in [uaclient/contract.py](../../uaclient/contract.py). |
2343 | diff --git a/dev-docs/references/pr_review_policy.md b/dev-docs/references/pr_review_policy.md |
2344 | deleted file mode 100644 |
2345 | index ce9a35e..0000000 |
2346 | --- a/dev-docs/references/pr_review_policy.md |
2347 | +++ /dev/null |
2348 | @@ -1,19 +0,0 @@ |
2349 | -# PR review policy |
2350 | - |
2351 | -The team follows this policy for PR reviews: |
2352 | - |
2353 | -* Simple PRs: PRs that fix typos or perform one line changes require **one** approval from a team |
2354 | - member and can be merged immediately by the reviewer. |
2355 | -* Low complexity PRs: For short PRs we require **one** approval to merge. However, after approving the |
2356 | - PR we will wait for **one** day before merging it. This will allow other team members to review |
2357 | - the PR if they want. When one day has passed after the approval and there are no new requested |
2358 | - changes, any team member can merge. |
2359 | -* Complex PRs: Minimum of **two** approvals from team members. After there are two team-member approvals |
2360 | - and there are no remaining requested changes, any team member can merge. |
2361 | -* SRU blocker PRs: Some PRs may also require review from members that are not on the team, like SRU |
2362 | - reviewers. This is the case, for example, when adding/creating new systemd units. For those PRs, we |
2363 | - will directly ask for feedback from members outside the team that have a more suitable background to review |
2364 | - the change we are proposing. Therefore, we not only require at least **two** approvals from team members, |
2365 | - but also approvals from every external reviewer we assigned. After the required approvals have been given, |
2366 | - the additional review feedback has been taken into account, and there are no requested changes remaining, |
2367 | - any team member can merge. |
2368 | diff --git a/dev-docs/references/terminology.md b/dev-docs/references/terminology.md |
2369 | deleted file mode 100644 |
2370 | index 0459eb7..0000000 |
2371 | --- a/dev-docs/references/terminology.md |
2372 | +++ /dev/null |
2373 | @@ -1,13 +0,0 @@ |
2374 | -# Terminology |
2375 | - |
2376 | -The following vocabulary is used to describe different aspects of the work |
2377 | -Ubuntu Pro Client performs: |
2378 | - |
2379 | -| Term | Meaning | |
2380 | -| -------- | -------- | |
2381 | -| Ubuntu Pro Client | The python command line client represented in this ubuntu-pro-client repository. It is installed on each Ubuntu machine and is the entry-point to enable any Ubuntu Pro commercial service on an Ubuntu machine | |
2382 | -| Contract Server | The backend service exposing a REST API to which Ubuntu Pro Client authenticates in order to obtain contract and commercial service information and manage which support services are active on a machine | |
2383 | -| Entitlement/Service | An Ubuntu Pro commercial support service such as FIPS, ESM, Livepatch, CIS-Audit to which a contract may be entitled | |
2384 | -| Affordance | Service-specific list of applicable architectures and Ubuntu series on which a service can run | |
2385 | -| Directives | Service-specific configuration values which are applied to a service when enabling that service | |
2386 | -| Obligations | Service-specific policies that must be instrumented for support of a service. Example: `enableByDefault: true` means that any attached machine **MUST** enable a service on attach | |
2387 | diff --git a/dev-docs/references/version_string_formatting.md b/dev-docs/references/version_string_formatting.md |
2388 | deleted file mode 100644 |
2389 | index 59f163c..0000000 |
2390 | --- a/dev-docs/references/version_string_formatting.md |
2391 | +++ /dev/null |
2392 | @@ -1,27 +0,0 @@ |
2393 | -# Version string formatting |
2394 | - |
2395 | -Below are the versioning schemes used for publishing debs: |
2396 | - |
2397 | -| Build target | Version Format | |
2398 | -| --------------------------------------------------------------------------------- | ------------------------------------------ | |
2399 | -| [Daily PPA](https://code.launchpad.net/~canonical-server/+recipe/ua-client-daily) | `XX.YY-<revno>~g<commitish>~ubuntu22.04.1` | |
2400 | -| Staging PPA | `XX.YY~22.04~rc1` | |
2401 | -| Stable PPA | `XX.YY~22.04~stableppa1` | |
2402 | -| Archive release | `XX.YY~22.04` | |
2403 | -| Archive bugfix release | `XX.YY.Z~22.04` | |
2404 | - |
2405 | -## Supported upgrade paths on same upstream version |
2406 | - |
2407 | -Regardless of source, the latest available "upstream version" (e.g. 27.4) will always be installed, because the upstream version comes first followed by a tilde in all version formats. |
2408 | - |
2409 | -This table demonstrates upgrade paths between sources for one particular upstream version. |
2410 | - |
2411 | -| Upgrade path | Version diff example | |
2412 | -| ------------------------------- | ----------------------------------------------------------------------- | |
2413 | -| Staging to Next Staging rev | `31.4~22.04~rc1` ➜ `31.4~22.04~rc2` | |
2414 | -| Staging to Stable | `31.4~22.04~rc2` ➜ `31.4~22.04~stableppa1` | |
2415 | -| Stable to Next Stable rev | `31.4~22.04~stableppa1` ➜ `31.4~22.04~stableppa2` | |
2416 | -| Stable to Archive | `31.4~22.04~stableppa2` ➜ `31.4~22.04` | |
2417 | -| LTS Archive to Next LTS Archive | `31.4~22.04` ➜ `31.4~24.04` | |
2418 | -| Archive to Daily | `31.4~24.04` ➜ `31.4-1500~g75fa134~ubuntu24.04.1` | |
2419 | -| Daily to Next Daily | `31.4-1500~g75fa134~ubuntu24.04.1` ➜ `31.4-1501~g3836375~ubuntu24.04.1` | |
2420 | diff --git a/dev-docs/references/what_happens_during_attach.md b/dev-docs/references/what_happens_during_attach.md |
2421 | deleted file mode 100644 |
2422 | index 05854e1..0000000 |
2423 | --- a/dev-docs/references/what_happens_during_attach.md |
2424 | +++ /dev/null |
2425 | @@ -1,15 +0,0 @@ |
2426 | -### What happens during attach |
2427 | -After running the command `pro attach TOKEN`, Ubuntu Pro Client will perform the following steps: |
2428 | - |
2429 | -* Read the config from /etc/ubuntu-advantage/uaclient.conf to obtain |
2430 | - the contract\_url (default: https://contracts.canonical.com) |
2431 | -* POSTs to the Contract Server API @ |
2432 | - <contract_url>/api/v1/context/machines/token providing the \<contractToken\> |
2433 | -* The Contract Server responds with a JSON blob containing an unique machine |
2434 | - token, service credentials, affordances, directives and obligations to allow |
2435 | - enabling and disabling Ubuntu Pro services |
2436 | -* Ubuntu Pro Client writes the machine token API response to the root-readonly |
2437 | - /var/lib/ubuntu-advantage/private/machine-token.json and a version with secrets redacted to the world-readable |
2438 | - file /var/lib/ubuntu-advantage/machine-token.json. |
2439 | -* Ubuntu Pro Client auto-enables any services defined with |
2440 | - `obligations:{enableByDefault: true}` |
2441 | diff --git a/docs-requirements.txt b/docs-requirements.txt |
2442 | deleted file mode 100644 |
2443 | index a2de834..0000000 |
2444 | --- a/docs-requirements.txt |
2445 | +++ /dev/null |
2446 | @@ -1,7 +0,0 @@ |
2447 | -furo |
2448 | -m2r2 |
2449 | -myst-parser |
2450 | -sphinx==5.1.1 |
2451 | -sphinx_autobuild |
2452 | -sphinx_copybutton |
2453 | -sphinx_design |
2454 | diff --git a/docs/_static/circle_of_friends.png b/docs/_static/circle_of_friends.png |
2455 | deleted file mode 100644 |
2456 | index 4178914..0000000 |
2457 | Binary files a/docs/_static/circle_of_friends.png and /dev/null differ |
2458 | diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css |
2459 | deleted file mode 100644 |
2460 | index 49efd28..0000000 |
2461 | --- a/docs/_static/css/custom.css |
2462 | +++ /dev/null |
2463 | @@ -1,240 +0,0 @@ |
2464 | -/** Fix the font weight (300 for normal, 400 for slightly bold) **/ |
2465 | -/** Should be 100 for all headers, 400 for normal text **/ |
2466 | - |
2467 | -h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head { |
2468 | - font-weight: 200; |
2469 | -} |
2470 | - |
2471 | -.toc-title { |
2472 | - font-weight: 400; |
2473 | -} |
2474 | - |
2475 | -div.page, li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt { |
2476 | - font-weight: 300; |
2477 | - line-height: 1.5; |
2478 | - font-size: var(--font-size--normal); |
2479 | -} |
2480 | - |
2481 | - |
2482 | -/** Side bars (side-bar tree = left, toc-tree = right) **/ |
2483 | -div.sidebar-tree { |
2484 | - font-weight: 200; |
2485 | - line-height: 1.5; |
2486 | - font-size: var(--font-size--normal); |
2487 | -} |
2488 | - |
2489 | -div.toc-tree { |
2490 | - font-weight: 200; |
2491 | - font-size: var(--font-size--medium); |
2492 | - line-height: 1.5; |
2493 | -} |
2494 | - |
2495 | -.sidebar-tree .toctree-l1>.reference, .toc-tree li.scroll-current>.reference { |
2496 | - font-weight: 400; |
2497 | -} |
2498 | - |
2499 | -/** List styling **/ |
2500 | -ol, ul { |
2501 | - margin-bottom: 1.5rem; |
2502 | - margin-left: 1rem; |
2503 | - margin-top: 0; |
2504 | - padding-left: 1rem; |
2505 | -} |
2506 | - |
2507 | -/** Table styling **/ |
2508 | - |
2509 | -th.head { |
2510 | - text-transform: uppercase; |
2511 | - font-size: var(--font-size--small); |
2512 | -} |
2513 | - |
2514 | -table.docutils { |
2515 | - border: 0; |
2516 | - box-shadow: none; |
2517 | - width:100%; |
2518 | -} |
2519 | - |
2520 | -table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child { |
2521 | - border-right: none; |
2522 | - border-left: none; |
2523 | -} |
2524 | - |
2525 | -/* center align table cells with ":-:" */ |
2526 | -td.text-center { |
2527 | - text-align: center; |
2528 | -} |
2529 | - |
2530 | -/** No rounded corners **/ |
2531 | - |
2532 | -.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight { |
2533 | - border-radius: 0; |
2534 | -} |
2535 | - |
2536 | -/** code blocks and literals **/ |
2537 | -code.docutils.literal.notranslate, .highlight pre, pre.literal-block { |
2538 | - font-size: var(--font-size--medium); |
2539 | -} |
2540 | - |
2541 | - |
2542 | -/** Admonition styling **/ |
2543 | - |
2544 | -.admonition { |
2545 | - font-size: var(--font-size--medium); |
2546 | - box-shadow: none; |
2547 | -} |
2548 | - |
2549 | -/** Styling for links **/ |
2550 | -/* unvisited link */ |
2551 | -a:link { |
2552 | - color: #06c; |
2553 | - text-decoration: none; |
2554 | -} |
2555 | - |
2556 | -/* visited link */ |
2557 | -a:visited { |
2558 | - color: #7d42b8; |
2559 | - text-decoration: none; |
2560 | -} |
2561 | - |
2562 | -/* mouse over link */ |
2563 | -a:hover { |
2564 | - text-decoration: underline; |
2565 | -} |
2566 | - |
2567 | -/* selected link */ |
2568 | -a:active { |
2569 | - text-decoration: underline; |
2570 | -} |
2571 | - |
2572 | -a.sidebar-brand.centered { |
2573 | - text-decoration: none; |
2574 | -} |
2575 | - |
2576 | -/** Color for the "copy link" symbol next to headings **/ |
2577 | - |
2578 | -a.headerlink { |
2579 | - color: var(--color-brand-primary); |
2580 | -} |
2581 | - |
2582 | -/** Line to the left of the current navigation entry **/ |
2583 | - |
2584 | -.sidebar-tree li.current-page { |
2585 | - border-left: 2px solid var(--color-brand-primary); |
2586 | -} |
2587 | - |
2588 | -/** Some tweaks for issue #16 **/ |
2589 | - |
2590 | -[role="tablist"] { |
2591 | - border-bottom: 1px solid var(--color-sidebar-item-background--hover); |
2592 | -} |
2593 | - |
2594 | -.sphinx-tabs-tab[aria-selected="true"] { |
2595 | - border: 0; |
2596 | - border-bottom: 2px solid var(--color-brand-primary); |
2597 | - background-color: var(--color-sidebar-item-background--current); |
2598 | - font-weight:300; |
2599 | -} |
2600 | - |
2601 | -.sphinx-tabs-tab{ |
2602 | - color: var(--color-brand-primary); |
2603 | - font-weight:300; |
2604 | -} |
2605 | - |
2606 | -.sphinx-tabs-panel { |
2607 | - border: 0; |
2608 | - border-bottom: 1px solid var(--color-sidebar-item-background--hover); |
2609 | - background: var(--color-background-primary); |
2610 | -} |
2611 | - |
2612 | -button.sphinx-tabs-tab:hover { |
2613 | - background-color: var(--color-sidebar-item-background--hover); |
2614 | -} |
2615 | - |
2616 | -/** Custom classes to fix scrolling in tables by decreasing the |
2617 | - font size or breaking certain columns. |
2618 | - Specify the classes in the Markdown file with, for example: |
2619 | - ```{rst-class} break-col-4 min-width-4-8 |
2620 | - ``` |
2621 | -**/ |
2622 | - |
2623 | -table.dec-font-size { |
2624 | - font-size: smaller; |
2625 | -} |
2626 | -table.break-col-1 td.text-left:first-child { |
2627 | - word-break: break-word; |
2628 | -} |
2629 | -table.break-col-4 td.text-left:nth-child(4) { |
2630 | - word-break: break-word; |
2631 | -} |
2632 | -table.min-width-1-15 td.text-left:first-child { |
2633 | - min-width: 15em; |
2634 | -} |
2635 | -table.min-width-4-8 td.text-left:nth-child(4) { |
2636 | - min-width: 8em; |
2637 | -} |
2638 | - |
2639 | -/** Underline for abbreviations **/ |
2640 | - |
2641 | -abbr[title] { |
2642 | - text-decoration: underline solid #cdcdcd; |
2643 | -} |
2644 | - |
2645 | -/** Use the same style for right-details as for left-details **/ |
2646 | -.bottom-of-page .right-details { |
2647 | - font-size: var(--font-size--small); |
2648 | - display: block; |
2649 | -} |
2650 | - |
2651 | -/** Version switcher */ |
2652 | -button.version_select { |
2653 | - color: var(--color-foreground-primary); |
2654 | - background-color: var(--color-toc-background); |
2655 | - padding: 5px 10px; |
2656 | - border: none; |
2657 | -} |
2658 | - |
2659 | -.version_select:hover, .version_select:focus { |
2660 | - background-color: var(--color-sidebar-item-background--hover); |
2661 | -} |
2662 | - |
2663 | -.version_dropdown { |
2664 | - position: relative; |
2665 | - display: inline-block; |
2666 | - text-align: right; |
2667 | - font-size: var(--sidebar-item-font-size); |
2668 | -} |
2669 | - |
2670 | -.available_versions { |
2671 | - display: none; |
2672 | - position: absolute; |
2673 | - right: 0px; |
2674 | - background-color: var(--color-toc-background); |
2675 | - box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2); |
2676 | - z-index: 11; |
2677 | -} |
2678 | - |
2679 | -.available_versions a { |
2680 | - color: var(--color-foreground-primary); |
2681 | - padding: 12px 16px; |
2682 | - text-decoration: none; |
2683 | - display: block; |
2684 | -} |
2685 | - |
2686 | -.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)} |
2687 | - |
2688 | -.show {display:block;} |
2689 | - |
2690 | -/** Fix for nested numbered list - the nested list is lettered **/ |
2691 | -ol.arabic ol.arabic { |
2692 | - list-style: lower-alpha; |
2693 | -} |
2694 | - |
2695 | -/** Make expandable sections look like links **/ |
2696 | -details summary { |
2697 | - color: var(--color-link); |
2698 | -} |
2699 | - |
2700 | -/** Context links at the bottom of the page **/ |
2701 | -footer { |
2702 | - font-size: var(--font-size--medium); |
2703 | -} |
2704 | diff --git a/docs/_static/css/github_issue_links.css b/docs/_static/css/github_issue_links.css |
2705 | deleted file mode 100644 |
2706 | index af4be86..0000000 |
2707 | --- a/docs/_static/css/github_issue_links.css |
2708 | +++ /dev/null |
2709 | @@ -1,24 +0,0 @@ |
2710 | -.github-issue-link-container { |
2711 | - padding-right: 0.5rem; |
2712 | -} |
2713 | -.github-issue-link { |
2714 | - font-size: var(--font-size--small); |
2715 | - font-weight: bold; |
2716 | - background-color: #DD4814; |
2717 | - padding: 13px 23px; |
2718 | - text-decoration: none; |
2719 | -} |
2720 | -.github-issue-link:link { |
2721 | - color: #FFFFFF; |
2722 | -} |
2723 | -.github-issue-link:visited { |
2724 | - color: #FFFFFF |
2725 | -} |
2726 | -.muted-link.github-issue-link:hover { |
2727 | - color: #FFFFFF; |
2728 | - text-decoration: underline; |
2729 | -} |
2730 | -.github-issue-link:active { |
2731 | - color: #FFFFFF; |
2732 | - text-decoration: underline; |
2733 | -} |
2734 | diff --git a/docs/_static/css/logo.css b/docs/_static/css/logo.css |
2735 | deleted file mode 100644 |
2736 | index 98d7cef..0000000 |
2737 | --- a/docs/_static/css/logo.css |
2738 | +++ /dev/null |
2739 | @@ -1,7 +0,0 @@ |
2740 | -.sidebar-brand.centered { |
2741 | - text-align: start; |
2742 | -} |
2743 | -.sidebar-logo { |
2744 | - max-width: 44px; |
2745 | - margin: initial; |
2746 | -} |
2747 | diff --git a/docs/_static/js/github_issue_links.js b/docs/_static/js/github_issue_links.js |
2748 | deleted file mode 100644 |
2749 | index d339060..0000000 |
2750 | --- a/docs/_static/js/github_issue_links.js |
2751 | +++ /dev/null |
2752 | @@ -1,25 +0,0 @@ |
2753 | -window.onload = function() { |
2754 | - const link = document.createElement("a"); |
2755 | - link.classList.add("muted-link"); |
2756 | - link.classList.add("github-issue-link"); |
2757 | - link.text = "Give feedback"; |
2758 | - link.href = ( |
2759 | - "https://github.com/canonical/ubuntu-pro-client/issues/new?" |
2760 | - + "title=docs%3A+TYPE+YOUR+QUESTION+HERE" |
2761 | - + "&body=*Please describe the question or issue you're facing with " |
2762 | - + `"${document.title}"` |
2763 | - + ".*" |
2764 | - + "%0A%0A%0A%0A%0A" |
2765 | - + "---" |
2766 | - + "%0A" |
2767 | - + `*Reported+from%3A+${location.href}*` |
2768 | - ); |
2769 | - link.target = "_blank"; |
2770 | - |
2771 | - const div = document.createElement("div"); |
2772 | - div.classList.add("github-issue-link-container"); |
2773 | - div.append(link) |
2774 | - |
2775 | - const container = document.querySelector(".article-container > .content-icon-container"); |
2776 | - container.prepend(div); |
2777 | -}; |
2778 | diff --git a/docs/conf.py b/docs/conf.py |
2779 | deleted file mode 100644 |
2780 | index 33da04c..0000000 |
2781 | --- a/docs/conf.py |
2782 | +++ /dev/null |
2783 | @@ -1,109 +0,0 @@ |
2784 | -# Configuration file for the Sphinx documentation builder. |
2785 | -# |
2786 | -# This file only contains a selection of the most common options. For a full |
2787 | -# list see the documentation: |
2788 | -# https://www.sphinx-doc.org/en/master/usage/configuration.html |
2789 | - |
2790 | -# -- Path setup -------------------------------------------------------------- |
2791 | - |
2792 | -# If extensions (or modules to document with autodoc) are in another directory, |
2793 | -# add these directories to sys.path here. If the directory is relative to the |
2794 | -# documentation root, use os.path.abspath to make it absolute, like shown here. |
2795 | -# |
2796 | -# import os |
2797 | -# import sys |
2798 | -# sys.path.insert(0, os.path.abspath('.')) |
2799 | - |
2800 | -import datetime |
2801 | - |
2802 | -# -- Project information ----------------------------------------------------- |
2803 | - |
2804 | -project = "Ubuntu Pro Client" |
2805 | -author = "Canonical Group Ltd" |
2806 | -copyright = "%s, %s" % (datetime.date.today().year, author) |
2807 | - |
2808 | -# -- General configuration --------------------------------------------------- |
2809 | - |
2810 | -# Add any Sphinx extension module names here, as strings. They can be |
2811 | -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom |
2812 | -# ones. |
2813 | - |
2814 | -extensions = [ |
2815 | - "myst_parser", |
2816 | - "sphinx_copybutton", |
2817 | - "sphinx_design", |
2818 | -] |
2819 | - |
2820 | -# Add any paths that contain templates here, relative to this directory. |
2821 | - |
2822 | -templates_path = ["_templates"] |
2823 | - |
2824 | -html_extra_path = ["googleaf254801a5285c31.html", "sitemap-index.xml"] |
2825 | - |
2826 | -# List of patterns, relative to source directory, that match files and |
2827 | -# directories to ignore when looking for source files. |
2828 | -# This pattern also affects html_static_path and html_extra_path. |
2829 | - |
2830 | -exclude_patterns = [] |
2831 | - |
2832 | -# It seems we need to request creation of automatic anchors for our headings. |
2833 | -# Setting to 2 because that's what we need now. |
2834 | -# If referencing any heading of lesser importance, adjust here. |
2835 | - |
2836 | -myst_heading_anchors = 3 |
2837 | - |
2838 | - |
2839 | -# -- Options for HTML output ------------------------------------------------- |
2840 | - |
2841 | -# The theme to use for HTML and HTML Help pages. See the documentation for |
2842 | -# a list of builtin themes: |
2843 | -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output |
2844 | - |
2845 | -html_theme = "furo" |
2846 | -html_logo = "_static/circle_of_friends.png" |
2847 | -html_theme_options = { |
2848 | - "light_css_variables": { |
2849 | - "color-sidebar-background-border": "none", |
2850 | - "font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif", |
2851 | - "font-stack--monospace": "Ubuntu Mono variable, Ubuntu Mono, Consolas, Monaco, Courier, monospace", |
2852 | - "color-foreground-primary": "#111", |
2853 | - "color-foreground-secondary": "var(--color-foreground-primary)", |
2854 | - "color-foreground-muted": "#333", |
2855 | - "color-background-secondary": "#FFF", |
2856 | - "color-background-hover": "#f2f2f2", |
2857 | - "color-brand-primary": "#111", |
2858 | - "color-brand-content": "#06C", |
2859 | - "color-inline-code-background": "rgba(0,0,0,.03)", |
2860 | - "color-sidebar-link-text": "#111", |
2861 | - "color-sidebar-item-background--current": "#ebebeb", |
2862 | - "color-sidebar-item-background--hover": "#f2f2f2", |
2863 | - "sidebar-item-line-height": "1.3rem", |
2864 | - "color-link-underline": "var(--color-background-primary)", |
2865 | - "color-link-underline--hover": "var(--color-background-primary)", |
2866 | - }, |
2867 | - "dark_css_variables": { |
2868 | - "color-foreground-secondary": "var(--color-foreground-primary)", |
2869 | - "color-foreground-muted": "#CDCDCD", |
2870 | - "color-background-secondary": "var(--color-background-primary)", |
2871 | - "color-background-hover": "#666", |
2872 | - "color-brand-primary": "#fff", |
2873 | - "color-brand-content": "#06C", |
2874 | - "color-sidebar-link-text": "#f7f7f7", |
2875 | - "color-sidebar-item-background--current": "#666", |
2876 | - "color-sidebar-item-background--hover": "#333", |
2877 | - }, |
2878 | -} |
2879 | - |
2880 | -# Add any paths that contain custom static files (such as style sheets) here, |
2881 | -# relative to this directory. They are copied after the builtin static files, |
2882 | -# so a file named "default.css" will overwrite the builtin "default.css". |
2883 | -html_static_path = ["_static"] |
2884 | - |
2885 | -html_css_files = [ |
2886 | - "css/logo.css", |
2887 | - "css/github_issue_links.css", |
2888 | - "css/custom.css", |
2889 | -] |
2890 | -html_js_files = [ |
2891 | - "js/github_issue_links.js", |
2892 | -] |
2893 | diff --git a/docs/explanations.rst b/docs/explanations.rst |
2894 | deleted file mode 100644 |
2895 | index 78adb85..0000000 |
2896 | --- a/docs/explanations.rst |
2897 | +++ /dev/null |
2898 | @@ -1,56 +0,0 @@ |
2899 | -Ubuntu Pro Client explanation |
2900 | -***************************** |
2901 | - |
2902 | -Our explanatory and conceptual guides are written to provide a better |
2903 | -understanding of how the Ubuntu Pro Client (``pro``) works. They enable you |
2904 | -to expand your knowledge and become better at using and configuring ``pro``. |
2905 | - |
2906 | -Messaging |
2907 | -========= |
2908 | - |
2909 | -Here you'll find details about Ubuntu Pro Client-related APT and MOTD messages |
2910 | --- what they are, when they are used and how they work. |
2911 | - |
2912 | -.. toctree:: |
2913 | - :maxdepth: 1 |
2914 | - |
2915 | - Pro-related APT messages <explanations/apt_messages.md> |
2916 | - Pro-related MOTD messages <explanations/motd_messages.md> |
2917 | - |
2918 | -Commands |
2919 | -======== |
2920 | - |
2921 | -Some of the commands in ``pro`` do more than you think. Here we'll show you a |
2922 | -selection of some of the commands -- what they do, and how they work. |
2923 | - |
2924 | -.. toctree:: |
2925 | - :maxdepth: 1 |
2926 | - |
2927 | - explanations/how_to_interpret_the_security_status_command.md |
2928 | - explanations/how_to_interpret_output_of_unattended_upgrades.md |
2929 | - explanations/status_columns.md |
2930 | - explanations/what_refresh_does.md |
2931 | - |
2932 | -Public Cloud Ubuntu Pro |
2933 | -======================= |
2934 | - |
2935 | -Here we talk about Ubuntu Pro images for AWS, Azure and GCP, and the related |
2936 | -tooling: the ``ubuntu-advantage-pro`` package. |
2937 | - |
2938 | -.. toctree:: |
2939 | - :maxdepth: 1 |
2940 | - |
2941 | - explanations/what_are_ubuntu_pro_cloud_instances.md |
2942 | - explanations/what_is_the_ubuntu_advantage_pro_package.md |
2943 | - |
2944 | -Other Pro features explained |
2945 | -============================ |
2946 | - |
2947 | -.. toctree:: |
2948 | - :maxdepth: 1 |
2949 | - |
2950 | - explanations/cves_and_usns_explained.md |
2951 | - explanations/what_are_the_timer_jobs.md |
2952 | - explanations/what_is_the_daemon.md |
2953 | - explanations/why_trusty_is_no_longer_supported.md |
2954 | - explanations/errors_explained.md |
2955 | diff --git a/docs/explanations/apt_messages.md b/docs/explanations/apt_messages.md |
2956 | deleted file mode 100644 |
2957 | index edd50d2..0000000 |
2958 | --- a/docs/explanations/apt_messages.md |
2959 | +++ /dev/null |
2960 | @@ -1,156 +0,0 @@ |
2961 | -# Ubuntu Pro-related APT messages |
2962 | - |
2963 | -When running some APT commands, you might see Ubuntu Pro-related messages in |
2964 | -the output of those commands. Currently, we deliver those messages when |
2965 | -running either `apt upgrade` or `apt dist-upgrade`. The scenarios |
2966 | -where we deliver those messages are: |
2967 | - |
2968 | -## ESM series with esm-infra service disabled |
2969 | - |
2970 | -When you run `apt upgrade` on an ESM release, like Xenial, we advertise |
2971 | -the `esm-infra` service if packages could be upgraded by enabling the service: |
2972 | - |
2973 | -``` |
2974 | -Reading package lists... Done |
2975 | -Building dependency tree |
2976 | -Reading state information... Done |
2977 | -Calculating upgrade... Done |
2978 | -The following package was automatically installed and is no longer required: |
2979 | - libfreetype6 |
2980 | - Use 'apt autoremove' to remove it. |
2981 | -The following security updates require Ubuntu Pro with 'esm-infra' enabled: |
2982 | - libpam0g libpam-modules openssl ntfs-3g git-man libsystemd0 squashfs-tools git openssh-sftp-server udev libpam-runtime isc-dhcp-common libx11-6 libudev1 apport python3-apport systemd-sysv liblz4-1 libpam-systemd systemd libpam-modules-bin openssh-server libx11-data openssh-client libxml2 curl isc-dhcp-client python3-problem-report libcurl3-gnutls libssl1.0.0 |
2983 | -Learn more about Ubuntu Pro for 16.04 at https://ubuntu.com/16-04 |
2984 | -``` |
2985 | - |
2986 | -## LTS series with esm-apps service disabled |
2987 | - |
2988 | -When you are running `apt upgrade` on a LTS release, like Focal, we advertise |
2989 | -the `esm-apps` service if packages could be upgraded by enabling the service: |
2990 | - |
2991 | -``` |
2992 | -Reading package lists... Done |
2993 | -Building dependency tree |
2994 | -Reading state information... Done |
2995 | -Calculating upgrade... Done |
2996 | -The following package was automatically installed and is no longer required: |
2997 | - libfreetype6 |
2998 | -Use 'apt autoremove' to remove it. |
2999 | -Get more security updates through Ubuntu Pro with 'esm-apps' enabled: |
3000 | - adminer editorconfig ansible |
3001 | -Learn more about Ubuntu Pro at https://ubuntu.com/pro |
3002 | -0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded. |
3003 | -``` |
3004 | - |
3005 | -## ESM package count |
3006 | - |
3007 | -If both ESM services are enabled on the system, we deliver a package count |
3008 | -related to each service near the end of the `apt` command: |
3009 | - |
3010 | -``` |
3011 | -1 standard LTS security update, 29 esm-infra security updates and 8 esm-apps security updates |
3012 | -``` |
3013 | - |
3014 | -We only deliver this message if the service is enabled *and* we upgraded |
3015 | -packages related to it. For example, if we had no `esm-infra` package upgrades, |
3016 | -the message would be: |
3017 | - |
3018 | -``` |
3019 | -1 standard LTS security update and 8 esm-apps security updates |
3020 | -``` |
3021 | - |
3022 | -## Expired contract |
3023 | - |
3024 | -If we detect that your contract is expired, we will deliver the following |
3025 | -message advertising `esm-infra` in the middle of the `apt upgrade` command: |
3026 | - |
3027 | -``` |
3028 | -# |
3029 | -# *Your Ubuntu Pro subscription has EXPIRED* |
3030 | -# 10 additional security update(s) require Ubuntu Pro with '{service}' enabled. |
3031 | -# Renew your service at https://ubuntu.com/pro |
3032 | -# |
3033 | -``` |
3034 | - |
3035 | -If we don't have any `esm-infra`-related packages to upgrade, we would show the |
3036 | -following message instead: |
3037 | - |
3038 | -``` |
3039 | -# |
3040 | -# *Your Ubuntu Pro subscription has EXPIRED* |
3041 | -# Renew your service at https://ubuntu.com/pro |
3042 | -# |
3043 | -``` |
3044 | - |
3045 | -## Contract is about to expire |
3046 | - |
3047 | -Similarly, if we detect that your contract is about to expire, we deliver the |
3048 | -following message in the middle of the `apt` command: |
3049 | - |
3050 | -``` |
3051 | -# |
3052 | -# CAUTION: Your Ubuntu Pro subscription will expire in 2 days. |
3053 | -# Renew your subscription at https://ubuntu.com/pro to ensure continued |
3054 | -# security coverage for your applications. |
3055 | -# |
3056 | -``` |
3057 | - |
3058 | -## Contract has expired, but still in grace period |
3059 | - |
3060 | -Additionally, if we detect that the contract has expired, but is still in the |
3061 | -grace period, the following message will be seen in the middle of the `apt` |
3062 | -command output: |
3063 | - |
3064 | -``` |
3065 | -# |
3066 | -# CAUTION: Your Ubuntu Pro subscription expired on 10 Sep 2021. |
3067 | -# Renew your subscription at https://ubuntu.com/pro to ensure continued |
3068 | -# security coverage for your applications. |
3069 | -# Your grace period will expire in 11 days. |
3070 | -# |
3071 | -``` |
3072 | - |
3073 | -## How are the APT messages generated? |
3074 | - |
3075 | -We have two distinct `apt` hooks that allow us to deliver these messages when |
3076 | -you run `apt upgrade` or `apt dist-upgrade`. They are: |
3077 | - |
3078 | -### `apt-esm-hook` |
3079 | - |
3080 | -Responsible for populating templates with accurate package counts (i.e. the package |
3081 | -count we see on the Expired contract messages). |
3082 | -However, the messaging here is created by two distinct steps: |
3083 | - |
3084 | -1. Our [update_messages](what_are_the_timer_jobs.md) timer job creates |
3085 | - templates for the APT messages this hook will deliver. We cannot create the |
3086 | - full message on the timer job, because we need the accurate package names |
3087 | - and count. This information can only be obtained when running the `apt` |
3088 | - command. |
3089 | - |
3090 | - ```{note} |
3091 | - These templates will only be produced if certain conditions are met. For |
3092 | - example, we only produce "expired contract" templates if the contracts are |
3093 | - indeed expired. |
3094 | - ``` |
3095 | - |
3096 | -2. When you run either `apt upgrade` or `apt dist-upgrade`, the hook |
3097 | - searches for these templates and if they exist, they are populated with the |
3098 | - correct `apt` content and delivered to the user. |
3099 | - |
3100 | -### `apt-esm-json-hook` |
3101 | - |
3102 | -The JSON hook is responsible for delivering the rest of the message we have presented here. |
3103 | -This hook is used to inject the message in the exact place we want, so we need to use a specific `apt` |
3104 | -[JSON hook](https://salsa.debian.org/apt-team/apt/-/blob/main/doc/json-hooks-protocol.md) |
3105 | -to communicate with it. |
3106 | - |
3107 | -```{note} |
3108 | -Those hooks are only delivered on LTS releases. This is because the hooks will |
3109 | -not deliver useful messages on non-LTS due to lack of support for ESM services. |
3110 | -``` |
3111 | - |
3112 | -## How are APT configured to deliver those messages? |
3113 | - |
3114 | -We currently ship the package the `20apt-esm-hook.conf` configuration that |
3115 | -configures both the basic apt hooks to call our `apt-esm-hook` binary, and also |
3116 | -the `json` API of `apt` to call our `apt-esm-json-hook` binary. |
3117 | diff --git a/docs/explanations/cves_and_usns_explained.md b/docs/explanations/cves_and_usns_explained.md |
3118 | deleted file mode 100644 |
3119 | index 272c1d8..0000000 |
3120 | --- a/docs/explanations/cves_and_usns_explained.md |
3121 | +++ /dev/null |
3122 | @@ -1,44 +0,0 @@ |
3123 | -# CVEs and USNs explained |
3124 | - |
3125 | -## What is a CVE |
3126 | - |
3127 | -Common Vulnerabilities and Exposures (CVEs) are a way to catalogue and track public security |
3128 | -vulnerabilities for a given software. Every CVE is identified through a unique identifier, |
3129 | -for example [CVE-2023-0465](https://www.cve.org/CVERecord?id=CVE-2023-0465). |
3130 | - |
3131 | -CVEs are maintained by the [MITRE Corporation](https://cve.mitre.org/) and the goal of the project |
3132 | -is to provide naming conventions for the public known security issues while also maintaining a |
3133 | -centralised repository for all of the security issues. This makes it easier for an organization to |
3134 | -submit a new security flaw though the CVE convention while also analysing any other existing CVEs |
3135 | -in the database. |
3136 | - |
3137 | -You can search for any existing CVE related to Ubuntu using |
3138 | -[the Ubuntu CVE page](https://ubuntu.com/security/cves). |
3139 | - |
3140 | -## What is a USN? |
3141 | - |
3142 | -An Ubuntu Security Notice (USN) is the way that Canonical publicly catalogues and displays security |
3143 | -vulneratibilities for Ubuntu packages. Usually, a USN is composed of one or more |
3144 | -[CVEs](#what-is-a-cve) and it also contains update instructions to fix the issue, if a fix is |
3145 | -already available. |
3146 | - |
3147 | -USNs follow a naming convention of the format: [USN-5963-1](https://ubuntu.com/security/notices/USN-5963-1) |
3148 | - |
3149 | -You can search for any existing USN using |
3150 | -[the Ubuntu Security Notices page](https://ubuntu.com/security/notices). |
3151 | - |
3152 | -## What are related USNs? |
3153 | - |
3154 | -A USN is composed of different CVEs. If the same CVE appears on multiple USNs, we say that those USNs are related. |
3155 | -In the following image, we can see a visual representation of that concept, where USN-789 and USN-321 |
3156 | -are related USNs because both are affected by CVE-2: |
3157 | - |
3158 | -![Related USN example](../images/usn-related.png) |
3159 | - |
3160 | - |
3161 | -A real example can be seen in [USN-5573-1](https://ubuntu.com/security/notices/USN-5573-1). |
3162 | -In the section **Related notices**, it shows that both **USN-5570-1** |
3163 | -and **USN-5570-2** are related to **USN-5573-1**. |
3164 | - |
3165 | -This information is useful for users that want to tackle |
3166 | -all related USNs at once, making sure that a CVE is fully fixed on their Ubuntu machine. |
3167 | diff --git a/docs/explanations/errors_explained.md b/docs/explanations/errors_explained.md |
3168 | deleted file mode 100644 |
3169 | index 6739e8b..0000000 |
3170 | --- a/docs/explanations/errors_explained.md |
3171 | +++ /dev/null |
3172 | @@ -1,101 +0,0 @@ |
3173 | -# Errors you may encounter and their meaning |
3174 | - |
3175 | -If you encounter an error or warning message from Pro Client that you don't understand and cannot find it in this document, please click "Have a question?" at the top of the page and let us know so that we can add it. |
3176 | - |
3177 | -## User Configuration Migration in version 27.14 |
3178 | - |
3179 | -Version 27.14 of Ubuntu Pro Client changed how some user configuration settings are stored on disk. It moved several settings out of `/etc/ubuntu-advantage/uaclient.conf` and into a file managed solely by the `pro config {set,unset,show}` subcommands. |
3180 | - |
3181 | -Most settings should've gotten automatically migrated to the new file when Pro Client upgraded. If something failed you may see one of the following messages: |
3182 | - |
3183 | -### Migration error 1 |
3184 | -**Error message:** |
3185 | -``` |
3186 | -Warning: Failed to load /etc/ubuntu-advantage/uaclient.conf |
3187 | - No automatic migration will occur. |
3188 | - You may need to use "pro config set" to re-set your settings. |
3189 | -``` |
3190 | - |
3191 | -**Where you'll see it:** |
3192 | - |
3193 | -During an `apt upgrade` or `apt install ubuntu-advantage-tools` |
3194 | - |
3195 | -**What does it mean:** |
3196 | - |
3197 | -This means that `/etc/ubuntu-advantage/uaclient.conf` was unable to be read or unable to be parsed as yaml during the migration. |
3198 | - |
3199 | -**What you can do about it:** |
3200 | - |
3201 | -Check the contents of `/etc/ubuntu-advantage/uaclient.conf`. |
3202 | -1. Ensure it is valid yaml |
3203 | -2. For any setting that is nested under `ua_config`: |
3204 | - - If you modified the value in the past: run `pro config set field_name=your_custom_value` |
3205 | - - delete the setting from `/etc/ubuntu-advantage/uaclient.conf` |
3206 | - - delete the `ua_config:` line from `/etc/ubuntu-advantage/uaclient.conf` |
3207 | - |
3208 | -### Migration error 2 |
3209 | -**Error message:** |
3210 | -``` |
3211 | -Warning: Failed to migrate user_config from /etc/ubuntu-advantage/uaclient.conf |
3212 | - Please run the following to keep your custom settings: |
3213 | - pro config set example=example |
3214 | -``` |
3215 | - |
3216 | -**Where you'll see it:** |
3217 | - |
3218 | -During an `apt upgrade` or `apt install ubuntu-advantage-tools` |
3219 | - |
3220 | -**What does it mean:** |
3221 | - |
3222 | -This means that `/var/lib/ubuntu-advantage/user-config.json` was unable to be written or a json serialization error occurred. |
3223 | - |
3224 | -**What you can do about it:** |
3225 | - |
3226 | -Run each of the `pro config set` commands recommended in the warning message. |
3227 | - |
3228 | -### Migration error 3 |
3229 | -**Error message:** |
3230 | -``` |
3231 | -Warning: Failed to migrate /etc/ubuntu-advantage/uaclient.conf |
3232 | - Please add following to uaclient.conf to keep your config: |
3233 | - example: example |
3234 | -``` |
3235 | - |
3236 | -**Where you'll see it:** |
3237 | - |
3238 | -During an `apt upgrade` or `apt install ubuntu-advantage-tools` |
3239 | - |
3240 | -**What does it mean:** |
3241 | - |
3242 | -This means that `/etc/ubuntu-advantage/uaclient.conf` was unable to be written or a yaml serialization error occurred. |
3243 | - |
3244 | -**What you can do about it:** |
3245 | - |
3246 | -Ensure that the settings listed in the warning output make it into your new uaclient.conf. |
3247 | - |
3248 | -### Warnings in versions >=27.14~ |
3249 | - |
3250 | -**Error message:** |
3251 | -``` |
3252 | -legacy "ua_config" found in uaclient.conf |
3253 | -``` |
3254 | -or |
3255 | -``` |
3256 | -Warning: uaclient.conf contains old ua_config field. |
3257 | -``` |
3258 | - |
3259 | -**Where you'll see it:** |
3260 | - |
3261 | -In `/var/log/ubuntu-advantage.log` after using the `pro` cli or during an `apt upgrade` to a newer version of ubuntu-advantage-tools. |
3262 | - |
3263 | -**What does it mean:** |
3264 | - |
3265 | -This means that there are still settings nested under `ua_config` in `/etc/ubuntu-advantage/uaclient.conf`. These will still be honored, but support may be removed in the future. |
3266 | - |
3267 | -**What you can do about it:** |
3268 | - |
3269 | -Check the contents of `/etc/ubuntu-advantage/uaclient.conf`. |
3270 | -For any setting that is nested under `ua_config`: |
3271 | -- If you modified the value in the past: run `pro config set field_name=your_custom_value` |
3272 | -- delete the setting from `/etc/ubuntu-advantage/uaclient.conf` |
3273 | -- delete the `ua_config:` line from `/etc/ubuntu-advantage/uaclient.conf` |
3274 | diff --git a/docs/explanations/how_to_interpret_output_of_unattended_upgrades.md b/docs/explanations/how_to_interpret_output_of_unattended_upgrades.md |
3275 | deleted file mode 100644 |
3276 | index 714c14a..0000000 |
3277 | --- a/docs/explanations/how_to_interpret_output_of_unattended_upgrades.md |
3278 | +++ /dev/null |
3279 | @@ -1,82 +0,0 @@ |
3280 | -# How to interpret the output of unattended-upgrades |
3281 | - |
3282 | -On Pro Client version 27.14~, we introduced the `u.pro.unattended_upgrades.status.v1` endpoint. |
3283 | -This endpoint is designed to provide users with an overview of the configuration and setup for |
3284 | -unattended-upgrades on the machine. The expected output follows this JSON example: |
3285 | - |
3286 | -```json |
3287 | -{ |
3288 | - "_schema_version": "v1", |
3289 | - "data": { |
3290 | - "attributes": { |
3291 | - "apt_periodic_job_enabled": true, |
3292 | - "package_lists_refresh_frequency_days": 1, |
3293 | - "systemd_apt_timer_enabled": true, |
3294 | - "unattended_upgrades_allowed_origins": [ |
3295 | - "${distro_id}:${distro_codename}", |
3296 | - "${distro_id}:${distro_codename}-security", |
3297 | - "${distro_id}ESMApps:${distro_codename}-apps-security", |
3298 | - "${distro_id}ESM:${distro_codename}-infra-security" |
3299 | - ], |
3300 | - "unattended_upgrades_disabled_reason": null, |
3301 | - "unattended_upgrades_frequency_days": 1, |
3302 | - "unattended_upgrades_last_run": null, |
3303 | - "unattended_upgrades_running": true |
3304 | - }, |
3305 | - "meta": { |
3306 | - "environment_vars": [], |
3307 | - "raw_config": { |
3308 | - "APT::Periodic::Enable": "1", |
3309 | - "APT::Periodic::Unattended-Upgrade": "1", |
3310 | - "APT::Periodic::Update-Package-Lists": "1", |
3311 | - "Unattended-Upgrade::Allowed-Origins": [ |
3312 | - "${distro_id}:${distro_codename}", |
3313 | - "${distro_id}:${distro_codename}-security", |
3314 | - "${distro_id}ESMApps:${distro_codename}-apps-security", |
3315 | - "${distro_id}ESM:${distro_codename}-infra-security" |
3316 | - ] |
3317 | - } |
3318 | - }, |
3319 | - "type": "UnattendedUpgradesStatus" |
3320 | - }, |
3321 | - "errors": [], |
3322 | - "result": "success", |
3323 | - "version": "27.14~16.04.1", |
3324 | - "warnings": [] |
3325 | -} |
3326 | -``` |
3327 | - |
3328 | -As we can see from this output, we have a variable named `unattended_upgrades_running`. That variable |
3329 | -indicates if unattended-upgrades is properly configured and running on the machine. |
3330 | -The value of this field will only be `true` if *ALL* of the following prerequisites are also true: |
3331 | - |
3332 | -* *`apt_periodic_job_enable` is true*: That variable indicates if the APT::Periodic::Enable configuration variable |
3333 | - is turned on. If it is turned off, unattended-upgrades will not automatically run on the machine. |
3334 | -* *`package_lists_refresh_frequency_days` is non-zero*: That variable shows the value of APT::Periodic::Package-List-Frequency. |
3335 | - This configuration defines the daily frequency for updating package sources in the background. If it has a zero value, this step will never |
3336 | - happen and unattended-upgrades might not be able to install new versions of the packages. |
3337 | -* *`systemd_apt_timer_enabled` is true*: This variable is true if both `apt-daily.timer` and `apt-daily-upgrade.timer` are running |
3338 | - on the machine. These timers are the ones that control when unattended-upgrades run. The first job, `apt-daily.timer` is responsible |
3339 | - for triggering the code that downloads the lastest package information on the system. The second job, `apt-daily-upgrade.timer` is |
3340 | - responsible for running unattended-upgrades to download the latest version of the packages. If one of these jobs is disabled, |
3341 | - unattended-upgrades might not work as expected. |
3342 | -* *`unattended_upgrades_allowed_origins` is not empty*: This variable defines the origins that |
3343 | - unattended-upgrades can use to install a package. If that list is empty, no packages can be |
3344 | - installed and unattended-upgrades will not work as expected. |
3345 | -* *`unattended_upgrades_frequency_days` is non-zero*: That variable shows the value of |
3346 | - APT::Periodic::Unattended-Upgrade. This configuration defines the daily frequency for running |
3347 | - unattended-upgrades in the background. Therefore, if it has a zero value, the command will never |
3348 | - run. |
3349 | - |
3350 | - |
3351 | -If any of those conditions are not met, the variable |
3352 | -*unattended_upgrades_disabled_reason* will contain an object explaining why unattended-upgrades is |
3353 | -not running. For example, if `package_lists_refresh_frequency_days` has a zero value, we will see |
3354 | -the following value for *unattended_upgrades_disabled_reason*: |
3355 | - |
3356 | -```json |
3357 | -{ |
3358 | - "msg": "APT::Periodic::Update-Package-Lists is turned off", |
3359 | - "code": "unattended-upgrades-cfg-value-turned-off" |
3360 | -} |
3361 | -``` |
3362 | diff --git a/docs/explanations/how_to_interpret_the_security_status_command.md b/docs/explanations/how_to_interpret_the_security_status_command.md |
3363 | deleted file mode 100644 |
3364 | index b0a56e9..0000000 |
3365 | --- a/docs/explanations/how_to_interpret_the_security_status_command.md |
3366 | +++ /dev/null |
3367 | @@ -1,323 +0,0 @@ |
3368 | -# What does `security-status` do? |
3369 | - |
3370 | -The `security-status` command provides an overview of all the packages |
3371 | -installed on your machine, and the security coverage that applies to those |
3372 | -packages. |
3373 | - |
3374 | -The output of the `security-status` command varies, depending on the configuration of the machine you run it on. In this article, we'll take a look at the different outputs of `security-status` and the situations in which you might see them. |
3375 | - |
3376 | -## Command output |
3377 | - |
3378 | -If you run the `pro security-status` command, the first blocks of information |
3379 | -you see look like: |
3380 | - |
3381 | -``` |
3382 | -2871 packages installed: |
3383 | - 2337 packages from Ubuntu Main/Restricted repository |
3384 | - 504 packages from Ubuntu Universe/Multiverse repository |
3385 | - 8 packages from third parties |
3386 | - 22 packages no longer available for download |
3387 | - |
3388 | -To get more information about the packages, run |
3389 | - pro security-status --help |
3390 | -for a list of available options. |
3391 | -``` |
3392 | - |
3393 | -Those are counts for the `apt` packages installed in the system, sorted |
3394 | -between the packages in main, universe, third party packages, and packages |
3395 | -that are no longer available. You will also see a hint to run |
3396 | -`pro security-status --help` to get more information. |
3397 | - |
3398 | -### `apt update` hint |
3399 | - |
3400 | -To get accurate package information, the `apt` caches must be up to date. If |
3401 | -your cache was not updated recently, you may see a message in the output with |
3402 | -a hint to update. |
3403 | - |
3404 | -``` |
3405 | -The system apt cache may be outdated. Make sure to run |
3406 | - sudo apt-get update |
3407 | -to get the latest package information from apt. |
3408 | -``` |
3409 | - |
3410 | -### LTS coverage |
3411 | - |
3412 | -If `esm-infra` is disabled in your system, main/restricted packages will be |
3413 | -covered during the LTS period - this information is presented right after the |
3414 | -hints. A covered system will present this message: |
3415 | - |
3416 | -``` |
3417 | -This machine is receiving security patching for Ubuntu Main/Restricted |
3418 | -repository until <year>. |
3419 | -``` |
3420 | - |
3421 | -On a system where the LTS period ended, you'll see: |
3422 | - |
3423 | -``` |
3424 | -This machine is NOT receiving security patches because the LTS period has ended |
3425 | -and esm-infra is not enabled. |
3426 | -``` |
3427 | - |
3428 | -### Ubuntu Pro coverage |
3429 | - |
3430 | -An Ubuntu Pro subscription provides more security coverage than a standard LTS. |
3431 | -The next blocks of information are related to Ubuntu Pro itself: |
3432 | - |
3433 | -``` |
3434 | -This machine is attached to an Ubuntu Pro subscription. |
3435 | - |
3436 | -Main/Restricted packages are receiving security updates from |
3437 | -Ubuntu Pro with 'esm-infra' enabled until 2032. |
3438 | - |
3439 | -Universe/Multiverse packages are receiving security updates from |
3440 | -Ubuntu Pro with 'esm-apps' enabled until 2032. You have received 21 security |
3441 | -updates. |
3442 | -``` |
3443 | - |
3444 | -This system is already attached to Pro! It is a Jammy machine, which has |
3445 | -installed some updates from `esm-apps`. Running the same command on a Xenial |
3446 | -system without Pro enabled, the output looks like: |
3447 | - |
3448 | -``` |
3449 | -This machine is NOT attached to an Ubuntu Pro subscription. |
3450 | - |
3451 | -Ubuntu Pro with 'esm-infra' enabled provides security updates for |
3452 | -Main/Restricted packages until 2026. There are 170 pending security updates. |
3453 | - |
3454 | -Ubuntu Pro with 'esm-apps' enabled provides security updates for |
3455 | -Universe/Multiverse packages until 2026. There is 1 pending security update. |
3456 | - |
3457 | -Try Ubuntu Pro with a free personal subscription on up to 5 machines. |
3458 | -Learn more at https://ubuntu.com/pro |
3459 | -``` |
3460 | - |
3461 | -There are lots of `esm-infra` updates for this machine, and even an `esm-apps` |
3462 | -update. The hint in the end of the output has a link to the main Pro website, |
3463 | -so the user can learn more about Pro and get their subscription. |
3464 | - |
3465 | -### Interim releases |
3466 | - |
3467 | -If you are running an interim release, the output is slightly different because |
3468 | -there are no Ubuntu Pro services available. You will still see the package |
3469 | -counts and support period though - your main/restricted packages are supported |
3470 | -for 9 months from the release date. |
3471 | - |
3472 | -``` |
3473 | -613 packages installed: |
3474 | - 601 packages from Ubuntu Main/Restricted repository |
3475 | - 12 packages from Ubuntu Universe/Multiverse repository |
3476 | - |
3477 | -To get more information about the packages, run |
3478 | - pro security-status --help |
3479 | -for a list of available options. |
3480 | - |
3481 | -Main/Restricted packages receive updates until 1/2024. |
3482 | - |
3483 | -Ubuntu Pro is not available for non-LTS releases. |
3484 | -``` |
3485 | - |
3486 | -### Optional flags for specific package sets |
3487 | - |
3488 | -Some flags can be passed to `security-status` to get information about coverage |
3489 | -of specific package sets. As an example, let's look at the output of |
3490 | -`pro security-status --esm-infra`: |
3491 | - |
3492 | -``` |
3493 | -442 packages installed: |
3494 | - 441 packages from Ubuntu Main/Restricted repository |
3495 | - |
3496 | -Main/Restricted packages are receiving security updates from |
3497 | -Ubuntu Pro with 'esm-infra' enabled until 2026. You have received 3 security |
3498 | -updates. There are 160 pending security updates. |
3499 | - |
3500 | -Run 'pro help esm-infra' to learn more |
3501 | - |
3502 | -Installed packages with an available esm-infra update: |
3503 | -( ... list of packages ... ) |
3504 | - |
3505 | -Installed packages with an esm-infra update applied: |
3506 | -( ... list of packages ... ) |
3507 | - |
3508 | -Further installed packages covered by esm-infra: |
3509 | -( ... list of packages ... ) |
3510 | - |
3511 | -For example, run: |
3512 | - apt-cache show tcpdump |
3513 | -to learn more about that package. |
3514 | -``` |
3515 | - |
3516 | -Besides the support information of main/restricted (which Ubuntu Pro with |
3517 | -`esm-infra` extends) there are lists of: |
3518 | -- packages which have some updated version available in esm-infra repositories |
3519 | -- packages which have an installed version from the esm-infra repositories |
3520 | -- packages which are covered by esm-infra |
3521 | - |
3522 | -You will see a similar output when running `pro security-status --esm-apps`, |
3523 | -but with information regarding universe/multiverse packages. |
3524 | - |
3525 | -You can also get a list of the third-party packages installed in the system: |
3526 | - |
3527 | -``` |
3528 | -$ pro security-status --thirdparty |
3529 | -2871 packages installed: |
3530 | - 8 packages from third parties |
3531 | - |
3532 | -Packages from third parties are not provided by the official Ubuntu |
3533 | -archive, for example packages from Personal Package Archives in Launchpad. |
3534 | - |
3535 | -Packages: |
3536 | -( ... list of packages ... ) |
3537 | - |
3538 | -For example, run: |
3539 | - apt-cache show <package_name> |
3540 | -to learn more about that package. |
3541 | -``` |
3542 | - |
3543 | -And also a list of unavailable packages (which no longer have any installation |
3544 | -source): |
3545 | - |
3546 | -``` |
3547 | -$ pro security-status --unavailable |
3548 | -2871 packages installed: |
3549 | - 22 packages no longer available for download |
3550 | - |
3551 | -Packages that are not available for download may be left over from a |
3552 | -previous release of Ubuntu, may have been installed directly from a |
3553 | -.deb file, or are from a source which has been disabled. |
3554 | - |
3555 | -Packages: |
3556 | -( ... list of packages ... ) |
3557 | - |
3558 | - |
3559 | -For example, run: |
3560 | - apt-cache show <package_name> |
3561 | -to learn more about that package. |
3562 | -``` |
3563 | - |
3564 | -## Machine-readable output |
3565 | - |
3566 | -If you run the `pro security-status --format yaml` command on your machine, you |
3567 | -should expect to see an output that follows this structure: |
3568 | - |
3569 | -``` |
3570 | -_schema_version: '0.1' |
3571 | -summary: |
3572 | - num_esm_apps_packages: 0 |
3573 | - num_esm_apps_updates: 0 |
3574 | - num_esm_infra_packages: 1 |
3575 | - num_esm_infra_updates: 1 |
3576 | - num_main_packages: 70 |
3577 | - num_multiverse_packages: 10 |
3578 | - num_restricted_packages: 10 |
3579 | - num_third_party_packages: 0 |
3580 | - num_universe_packages: 9 |
3581 | - num_installed_packages: 100 |
3582 | - num_standard_security_updates: 0 |
3583 | - ua: |
3584 | - attached: true |
3585 | - enabled_services: |
3586 | - - esm-apps |
3587 | - - esm-infra |
3588 | - entitled_services: |
3589 | - - esm-apps |
3590 | - - esm-infra |
3591 | -packages: |
3592 | -- origin: esm.ubuntu.com |
3593 | - package: zlib1g |
3594 | - service_name: esm-infra |
3595 | - status: upgrade_available |
3596 | - version: 1:1.2.8.dfsg-2ubuntu4.3+esm1 |
3597 | - download_size: 123456 |
3598 | -livepatch: |
3599 | - fixed_cves: |
3600 | - - Name: cve-2013-1798 |
3601 | - Patched: true |
3602 | -``` |
3603 | - |
3604 | -Let's understand what each key means in the output of the |
3605 | -`pro security-status --format yaml` command: |
3606 | - |
3607 | -### `summary` |
3608 | - |
3609 | -This provides a summary of the system related to Ubuntu Pro and the different |
3610 | -package sources in the system: |
3611 | - |
3612 | -* **`num_installed_packages`**: The total number of installed packages on the |
3613 | - system. |
3614 | -* **`num_esm_apps_packages`**: The number of packages installed from `esm-apps`. |
3615 | -* **`num_esm_apps_updates`**: The number of `esm-apps` package updates available |
3616 | - to the system. |
3617 | -* **`num_esm_infra_packages`**: The number of packages installed from |
3618 | - `esm-infra`. |
3619 | -* **`num_esm_infra_updates`**: The number of `esm-infra` package updates |
3620 | - available to the system. |
3621 | -* **`num_main_packages`**: The number of packages installed from the `main` |
3622 | - archive component. |
3623 | -* **`num_multiverse_packages`**: The number of packages installed from the |
3624 | - `multiverse` archive component. |
3625 | -* **`num_restricted_packages`**: The number of packages installed from the |
3626 | - `restricted` archive component. |
3627 | -* **`num_third_party_packages`** : The number of packages installed from |
3628 | - `third party` sources. |
3629 | -* **`num_universe_packages`**: The number of packages installed from the |
3630 | - `universe` archive component. |
3631 | -* **`num_unknown_packages`**: The number of packages installed from sources not |
3632 | - known to `apt` (e.g., those installed locally through `dpkg` or packages |
3633 | - without a remote reference). |
3634 | -* **`num_standard_security_updates`**: The number of standard security updates |
3635 | - available to the system. |
3636 | - |
3637 | -```{note} |
3638 | - It is worth mentioning here that the `_updates` fields are presenting the |
3639 | - number of **security** updates for **installed** packages. For example, let's |
3640 | - assume your machine has a universe package that has a security update from |
3641 | - `esm-infra`. The count will be displayed as: |
3642 | - |
3643 | - ``` |
3644 | - num_esm_infra_packages: 0 |
3645 | - num_esm_infra_updates: 1 |
3646 | - num_universe_packages: 1 |
3647 | - ``` |
3648 | - |
3649 | - After upgrading the system, the count will turn to: |
3650 | - |
3651 | - ``` |
3652 | - num_esm_infra_packages: 1 |
3653 | - num_esm_infra_updates: 0 |
3654 | - num_universe_packages: 0 |
3655 | - ``` |
3656 | -``` |
3657 | - |
3658 | -* **`ua`**: An object representing the state of Ubuntu Pro on the system: |
3659 | - * **`attached`**: If the system is attached to an Ubuntu Pro subscription. |
3660 | - * **`enabled_services`**: A list of services that are enabled on the system. |
3661 | - If unattached, this will always be an empty list. |
3662 | - * **`entitled_services`**: A list of services that are entitled on your |
3663 | - Ubuntu Pro subscription. If unattached, this will always be an empty list. |
3664 | - |
3665 | -### `packages` |
3666 | - |
3667 | -This provides a list of security updates for packages installed on the system. |
3668 | -Every entry on the list will follow this structure: |
3669 | - |
3670 | -* **`origin`**: The host where the update comes from. |
3671 | -* **`package`**: The name of the package. |
3672 | -* **`service_name`**: The service that provides the package update. It can be |
3673 | - one of: `esm-infra`, `esm-apps` or `standard-security`. |
3674 | -* **`status`**: The status for this update. It will be one of: |
3675 | - * **"upgrade_available"**: The package can be upgraded right now. |
3676 | - * **"pending_attach"**: The package needs an Ubuntu Pro subscription attached |
3677 | - to be upgraded. |
3678 | - * **"pending_enable"**: The machine is attached to an Ubuntu Pro subscription, |
3679 | - but the service required to provide the upgrade is not enabled. |
3680 | - * **"upgrade_unavailable"**: The machine is attached, but the contract is not |
3681 | - entitled to the service which provides the upgrade. |
3682 | -* **`version`**: The update version. |
3683 | -* **`download_size`**: The number of bytes that would be downloaded in order to |
3684 | - install the update. |
3685 | - |
3686 | -### `livepatch` |
3687 | - |
3688 | -This displays Livepatch-related information. Currently, the only information |
3689 | -presented is **`fixed_cves`**. This represents a list of CVEs that were fixed |
3690 | -by Livepatches applied to the kernel. |
3691 | diff --git a/docs/explanations/motd_messages.md b/docs/explanations/motd_messages.md |
3692 | deleted file mode 100644 |
3693 | index 6a8f22b..0000000 |
3694 | --- a/docs/explanations/motd_messages.md |
3695 | +++ /dev/null |
3696 | @@ -1,212 +0,0 @@ |
3697 | -# Ubuntu Pro-related MOTD messages |
3698 | - |
3699 | -When the Ubuntu Pro Client (`pro`) is installed on the system, it delivers |
3700 | -custom messages on ["Message of the Day" (MOTD)](https://wiki.debian.org/motd). |
3701 | -Those messages are generated directly by three different sources. |
3702 | - |
3703 | -* MOTD about available updates |
3704 | -* MOTD about important subscription conditions |
3705 | -* MOTD about ESM being available |
3706 | - |
3707 | -## MOTD about available updates |
3708 | - |
3709 | -The [update-notifier](https://wiki.ubuntu.com/UpdateNotifier) delivers a script |
3710 | -via the `update-notifier-common` package called |
3711 | -`/usr/lib/update-notifier/apt_check.py. |
3712 | -With regards to Ubuntu Pro, this script is responsible for: |
3713 | - |
3714 | -* Informing the user about the status of one of the ESM services; `esm-apps` if |
3715 | - the machine is an LTS series, or `esm-infra` if the series is in ESM mode. |
3716 | -* Showing the number of `esm-infra` or `esm-apps` packages that can be upgraded |
3717 | - on the machine. |
3718 | - |
3719 | -`update-notifier` has always added information about potential updates to |
3720 | -MOTD to raise user awareness. With the advent of Ubuntu Pro they are |
3721 | -just more differentiated. |
3722 | - |
3723 | -Note that if you run `apt_check.py` directly it might give you rather |
3724 | -unreadable output as it is meant for program use. You can add `--human-readable` |
3725 | -to see the information as it would be presented in MOTD. |
3726 | - |
3727 | -### Machine is unattached |
3728 | - |
3729 | -On a machine that runs an Ubuntu release for which the `esm-apps` service |
3730 | -is available, but not yet attached to an Ubuntu Pro subscription, there will |
3731 | -be a message notifying the user that there may be more security updates |
3732 | -available through ESM Apps. |
3733 | - |
3734 | -``` |
3735 | -Expanded Security Maintenance for Applications is not enabled. |
3736 | - |
3737 | -0 updates can be applied immediately. |
3738 | - |
3739 | -Enable ESM Apps to receive additional future security updates. |
3740 | -See https://ubuntu.com/esm or run: sudo pro status |
3741 | -``` |
3742 | - |
3743 | -### Machine is fully attached |
3744 | - |
3745 | -In the opposite situation, if an LTS machine has the `esm-infra` and `esm-apps` services enabled then users will see the following output in MOTD: |
3746 | - |
3747 | -``` |
3748 | -Expanded Security Maintenance for Applications is enabled. |
3749 | - |
3750 | -11 updates can be applied immediately. |
3751 | -5 of these updates are ESM Apps security updates. |
3752 | -1 of these updates is a ESM Infra security update. |
3753 | -5 of these updates are standard security updates. |
3754 | -To see these additional updates run: apt list --upgradable |
3755 | -``` |
3756 | - |
3757 | -### Machine is fully attached, on an older release |
3758 | - |
3759 | -Above you have seen examples of recent (as in "still in their first 5 |
3760 | -years of support") Ubuntu releases, where the hint is about ESM Apps |
3761 | -extending the coverage to the universe repositories. |
3762 | - |
3763 | -However, if running on an Ubuntu release that has is already past the initial |
3764 | -5 years of support and has thereby entered Expanded Security Maintenance |
3765 | -(["ESM"](https://ubuntu.com/security/esm)), we would instead see |
3766 | -`esm-infra` (which provides coverage for another 5 years) being shown: |
3767 | - |
3768 | -``` |
3769 | -Expanded Security Maintenance Infrastructure is enabled. |
3770 | - |
3771 | -11 updates can be applied immediately. |
3772 | -5 of these updates are ESM Apps security updates. |
3773 | -1 of these updates is a ESM Infra security update. |
3774 | -5 of these updates are standard security updates. |
3775 | -To see these additional updates run: apt list --upgradable |
3776 | -``` |
3777 | - |
3778 | -### Partial service enablement |
3779 | - |
3780 | -Now let's consider a scenario where one of these services is not enabled. For |
3781 | -example, if `esm-apps` was disabled, the output will be: |
3782 | - |
3783 | -``` |
3784 | -Expanded Security Maintenance for Applications is not enabled. |
3785 | - |
3786 | -6 updates can be applied immediately. |
3787 | -1 of these updates is a ESM Infra security update. |
3788 | -5 of these updates are standard security updates. |
3789 | -To see these additional updates run: apt list --upgradable |
3790 | - |
3791 | -5 additional security updates can be applied with ESM Apps |
3792 | -Learn more about enabling ESM Apps for Ubuntu 16.04 at |
3793 | -https://ubuntu.com/16-04 |
3794 | -``` |
3795 | - |
3796 | -At the end of the output we can see the number of packages that *could* be |
3797 | -upgraded if that service was enabled. Note that we would deliver the same |
3798 | -information for `esm-infra` if the service was disabled and the series running |
3799 | -on the machine is in ESM state. |
3800 | - |
3801 | -## MOTD about important subscription conditions |
3802 | - |
3803 | -One of the [timer jobs](https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/what_are_the_timer_jobs.html) |
3804 | -Ubuntu Pro uses can insert additional messages into MOTD. |
3805 | -These messages will be always delivered next to the content created by |
3806 | -`update-notifier`. These additional messages are generated when `pro` |
3807 | -detects that certain conditions on the machine have been met. They are: |
3808 | - |
3809 | -### Subscription expired |
3810 | - |
3811 | -When the Ubuntu Pro subscription is expired, `pro` will deliver the following |
3812 | -message after the `update-notifier` message: |
3813 | - |
3814 | -``` |
3815 | -*Your Ubuntu Pro subscription has EXPIRED* |
3816 | -2 additional security update(s) require Ubuntu Pro with 'esm-infra' enabled. |
3817 | -Renew your service at https://ubuntu.com/pro |
3818 | -``` |
3819 | - |
3820 | -### Subscription about to expire |
3821 | - |
3822 | -When the Ubuntu Pro subscription is about to expire, we deliver the following |
3823 | -message after the `update-notifier` message: |
3824 | - |
3825 | -``` |
3826 | -CAUTION: Your Ubuntu Pro subscription will expire in 2 days. |
3827 | -Renew your subscription at https://ubuntu.com/pro to ensure continued security |
3828 | -coverage for your applications. |
3829 | -``` |
3830 | - |
3831 | -### Subscription expired but within grace period |
3832 | - |
3833 | -When the Ubuntu Pro subscription has expired, but is still within the grace |
3834 | -period, we deliver the following message after the `update-notifier` script: |
3835 | - |
3836 | -``` |
3837 | -CAUTION: Your Ubuntu Pro subscription expired on 10 Sep 2021. |
3838 | -Renew your subscription at https://ubuntu.com/pro to ensure continued security |
3839 | -coverage for your applications. |
3840 | -Your grace period will expire in 9 days. |
3841 | -``` |
3842 | - |
3843 | -## MOTD about ESM being available |
3844 | - |
3845 | -When Ubuntu Pro became generally available, a temporary announcement was made |
3846 | -through MOTD. This was intended to raise awareness of Pro now being available |
3847 | -and free for personal use, and was shown on systems that could be covered |
3848 | -by `esm-apps`. |
3849 | -It looked like: |
3850 | - |
3851 | -``` |
3852 | - * Introducing Expanded Security Maintenance for Applications. |
3853 | - Receive updates to over 25,000 software packages with your |
3854 | - Ubuntu Pro subscription. Free for personal use. |
3855 | - |
3856 | - https://ubuntu.com/pro |
3857 | -``` |
3858 | - |
3859 | -Since this message was intended as a limited-time announcement to coincide |
3860 | -with the release of Ubuntu Pro into general availability, it was removed in |
3861 | -27.14. |
3862 | - |
3863 | -## How are these messages inserted into MOTD and how can I disable them? |
3864 | - |
3865 | -Just as there are different purposes to the messages outlined above, |
3866 | -there are different sources producing these MOTD elements that one |
3867 | -sees at login. |
3868 | - |
3869 | -Those messages are considered important to ensure user awareness about |
3870 | -the free additional security coverage provided by Ubuntu Pro and about |
3871 | -not-yet-applied potential updates in general. Therefore it is generally not |
3872 | -recommended to disable them. But still, you can selectively disable them |
3873 | -by removing the config files that add them, as outlined below. |
3874 | - |
3875 | -Removing those files is considered a conffile change to customize a program |
3876 | -and they will stay removed even on future upgrades or re-installations of the |
3877 | -related packages. |
3878 | - |
3879 | -If you realize that you actually need them back you need |
3880 | -to reinstall the related packages and tell apt/dpkg to offer you to restore |
3881 | -those files via: |
3882 | - |
3883 | -``` |
3884 | -sudo apt install --reinstall -o Dpkg::Options::="--force-confask" ubuntu-advantage-tools update-notifier-common |
3885 | -``` |
3886 | - |
3887 | -## Source: MOTD about available updates |
3888 | - |
3889 | -1. `update-notifier-common` has a hook `/etc/apt/apt.conf.d/99update-notifier` that runs after `apt update`. |
3890 | -2. That hook will update the information in `/var/lib/update-notifier/updates-available` matching the new package information that was just fetched by using `/usr/lib/update-notifier/apt-check --human-readable`. |
3891 | -3. At MOTD generation time, the script located at `/etc/update-motd.d/90-updates-available` checks if `/var/lib/update-notifier/updates-available` exists and if it does, inserts the message into the full MOTD. |
3892 | - |
3893 | -If you want to disable any message of update-notifier (not just related to Ubuntu Pro and ESM) about potentially available updates remove `/etc/update-motd.d/90-updates-available`. |
3894 | - |
3895 | -## Source: MOTD about important subscription conditions |
3896 | - |
3897 | -1. The subscription status is checked periodically in the background when the machine is attached to an Ubuntu Pro subscription. |
3898 | -2. If one of the above conditions applies to the subscription that the machine is attached to (there are no messages generated by this for unattached machines), then the message is stored in `/var/lib/ubuntu-advantage/messages/motd-contract-status`. |
3899 | -3. At MOTD generation time, the script located at `/etc/update-motd.d/91-contract-ua-esm-status` checks if `/var/lib/ubuntu-advantage/messages/motd-contract-status` exists and if it does, inserts the message into the full MOTD. |
3900 | - |
3901 | -If you want to disable any message about important conditions of your attached subscription remove `/etc/update-motd.d/91-contract-ua-esm-status`. |
3902 | - |
3903 | -## Source: MOTD about ESM being available |
3904 | - |
3905 | -1. `pro` checks regularly if a system would have `esm-apps` available to it and if so places a message in `/var/lib/ubuntu-advantage/messages/motd-esm-announce`. |
3906 | -2. At MOTD generation time, the script located at `/etc/update-motd.d/88-esm-announce` checks if `/var/lib/ubuntu-advantage/messages/motd-esm-announce` exists and if it does, inserts the message into the full MOTD. |
3907 | - |
3908 | -If you want to disable the ESM announcement remove `/etc/update-motd.d/88-esm-announce` (or upgrade to 27.14 or later which will remove it for you). |
3909 | diff --git a/docs/explanations/status_columns.md b/docs/explanations/status_columns.md |
3910 | deleted file mode 100644 |
3911 | index 6e79449..0000000 |
3912 | --- a/docs/explanations/status_columns.md |
3913 | +++ /dev/null |
3914 | @@ -1,205 +0,0 @@ |
3915 | -# The `pro status` output explained |
3916 | - |
3917 | -When running `pro status` we can observe two different types of outputs, which |
3918 | -depend on whether the Ubuntu Pro subscription is attached or unattached. |
3919 | - |
3920 | -## Pro subscription unattached |
3921 | -When unattached, users will see the following status table containing only |
3922 | -three columns: |
3923 | - |
3924 | -``` |
3925 | -SERVICE AVAILABLE DESCRIPTION |
3926 | -cc-eal no Common Criteria EAL2 Provisioning Packages |
3927 | -cis no Security compliance and audit tools |
3928 | -esm-infra yes Expanded Security Maintenance for Infrastructure |
3929 | -fips no NIST-certified core packages |
3930 | -fips-updates no NIST-certified core packages with priority security updates |
3931 | -livepatch yes Canonical Livepatch service |
3932 | -``` |
3933 | - |
3934 | -Where: |
3935 | - |
3936 | -* **SERVICE**: Is the name of service being offered |
3937 | -* **AVAILABLE**: Shows if that service is available on that machine. To verify |
3938 | - if a service is available, we check the machine kernel version, architecture, |
3939 | - Ubuntu release being used and the machine type (i.e lxd for LXD containers) |
3940 | -* **DESCRIPTION**: A short description of the service. |
3941 | - |
3942 | -## With Pro subscription attached |
3943 | - |
3944 | -However, if we run the same command when attached, we have an output with 4 |
3945 | -columns: |
3946 | - |
3947 | -``` |
3948 | -SERVICE ENTITLED STATUS DESCRIPTION |
3949 | -cis yes disabled Center for Internet Security Audit Tools |
3950 | -esm-infra yes enabled Expanded Security Maintenance for Infrastructure |
3951 | -fips yes n/a NIST-certified core packages |
3952 | -fips-updates yes n/a NIST-certified core packages with priority security updates |
3953 | -livepatch yes n/a Canonical Livepatch service |
3954 | -``` |
3955 | - |
3956 | -You may notice that the column **AVAILABLE** is no longer shown, and instead we |
3957 | -see the following new columns: |
3958 | - |
3959 | -* **ENTITLED**: Shows if the user subscription allows that service to be |
3960 | - enabled. |
3961 | -* **STATUS**: Reports the state of that service on the machine. |
3962 | - |
3963 | -It is possible that a service could appear as "available" when the Pro status is |
3964 | -unattached, but then shows as "not entitled" if the subscription is later |
3965 | -attached. This happens because even if the service is available, if your Ubuntu |
3966 | -Pro subscription doesn't allow you access to a service, `pro` cannot enable it. |
3967 | - |
3968 | -The **STATUS** column allows for three possible states: |
3969 | - |
3970 | -* **enabled**: The service is enabled on the machine. |
3971 | -* **disabled**: The service is not currently running. |
3972 | -* **n/a**: This means "not applicable". This will show if the service cannot be |
3973 | - enabled on the machine due to a non-contract restriction. For example, we |
3974 | - cannot enable `livepatch` on a container. |
3975 | - |
3976 | -## Notices |
3977 | - |
3978 | -"Notices" are information regarding the Ubuntu Pro status which either require |
3979 | -some kind of action from the user, or may impact the experience with Ubuntu Pro. |
3980 | - |
3981 | -For example, let's say FIPS was just enabled, but the system wasn't rebooted |
3982 | -yet (which is required for booting into the FIPS Kernel). The output of |
3983 | -`pro status` in this case will contain: |
3984 | - |
3985 | -``` |
3986 | -NOTICES |
3987 | -FIPS support requires system reboot to complete configuration. |
3988 | -``` |
3989 | - |
3990 | -After the system is rebooted, the notice will go away. |
3991 | - |
3992 | -Notices can always be resolved, and the instructions on how to resolve it will |
3993 | -be explicitly stated in the notice itself. |
3994 | - |
3995 | -## Features |
3996 | - |
3997 | -"Features" are extra configuration values that can be set and unset in |
3998 | -`uaclient.conf`. Most of these are meant for development/testing purposes, but |
3999 | -some can be used in application flows. For example, to always have beta services |
4000 | -with the same flow as the non-beta (for `enable`, `status`, etc.), |
4001 | -`uaclient.conf` may have: |
4002 | - |
4003 | -``` |
4004 | -features: |
4005 | - allow_beta: true |
4006 | -``` |
4007 | - |
4008 | -In this case, the output of `pro status` will contain: |
4009 | - |
4010 | -``` |
4011 | -FEATURES |
4012 | -allow_beta: True |
4013 | -``` |
4014 | - |
4015 | -It's important to keep in mind that any feature defined like this will be |
4016 | -listed, even if it is invalid or typed the wrong way. Those appear in `status` |
4017 | -output for informational and debugging purposes. |
4018 | - |
4019 | -## Machine-readable output |
4020 | - |
4021 | -The `pro status` command supports a `--format` flag with options including `json` and `yaml`. These result in a machine-readable form of the information presented by the `pro status` command. |
4022 | - |
4023 | -```{note} |
4024 | -`pro status` should return the same results whether using `sudo` or not, but earlier versions did not always do this. We recommend using `sudo` whenever possible. |
4025 | -``` |
4026 | - |
4027 | -For example, running `sudo pro status --format=json` on an attached machine may give you something like this: |
4028 | -```javascript |
4029 | -{ |
4030 | - "_doc": "Content provided in json response is currently considered Experimental and may change", |
4031 | - "_schema_version": "0.1", |
4032 | - "account": { |
4033 | - "created_at": "2000-01-02T03:04:05+06:00", |
4034 | - "id": "account_id", |
4035 | - "name": "Test" |
4036 | - }, |
4037 | - "attached": true, |
4038 | - "config": { ...effectiveConfiguration }, |
4039 | - "config_path": "/etc/ubuntu-advantage/uaclient.conf", |
4040 | - "contract": { |
4041 | - "created_at": "2000-01-02T03:04:05+06:00", |
4042 | - "id": "contract_id", |
4043 | - "name": "contract_name", |
4044 | - "products": [ "uaa-essential" ], |
4045 | - "tech_support_level": "essential" |
4046 | - }, |
4047 | - "effective": null, |
4048 | - "environment_vars": [...proClientEnvironmentVariables], |
4049 | - "errors": [], |
4050 | - "execution_details": "No Ubuntu Pro operations are running", |
4051 | - "execution_status": "inactive", |
4052 | - "expires": "9999-12-31T00:00:00+00:00", |
4053 | - "features": {}, |
4054 | - "machine_id": "machine_id", |
4055 | - "notices": [], |
4056 | - "result": "success", |
4057 | - "services": [ |
4058 | - { |
4059 | - "available": "yes", |
4060 | - "blocked_by": [], |
4061 | - "description": "Expanded Security Maintenance for Applications", |
4062 | - "description_override": null, |
4063 | - "entitled": "yes", |
4064 | - "name": "esm-apps", |
4065 | - "status": "enabled", |
4066 | - "status_details": "Ubuntu Pro: ESM Apps is active", |
4067 | - "warning": null |
4068 | - }, |
4069 | - { |
4070 | - "available": "yes", |
4071 | - "blocked_by": [], |
4072 | - "description": "Expanded Security Maintenance for Infrastructure", |
4073 | - "description_override": null, |
4074 | - "entitled": "yes", |
4075 | - "name": "esm-infra", |
4076 | - "status": "enabled", |
4077 | - "status_details": "Ubuntu Pro: ESM Infra is active", |
4078 | - "warning": null |
4079 | - }, |
4080 | - { |
4081 | - "available": "yes", |
4082 | - "blocked_by": [], |
4083 | - "description": "Canonical Livepatch service", |
4084 | - "description_override": null, |
4085 | - "entitled": "yes", |
4086 | - "name": "livepatch", |
4087 | - "status": "enabled", |
4088 | - "status_details": "", |
4089 | - "warning": null |
4090 | - }, |
4091 | - ...otherServiceStatusObjects |
4092 | - ], |
4093 | - "simulated": false, |
4094 | - "version": "27.13.6~18.04.1", |
4095 | - "warnings": [] |
4096 | -} |
4097 | -``` |
4098 | - |
4099 | -Some particularly important attributes in the output include: |
4100 | -* `attached`: This boolean value indicates whether this machine is attached to an Ubuntu Pro account. This does not tell you if any particular service (e.g. `esm-infra`) is enabled. You must check the individual service item in the `services` list for that status (described below). |
4101 | -* `expires`: This is the date that the Ubuntu Pro subscription is valid until (in RFC3339 format). After this date has passed the machine should be treated as if not attached and no services are enabled. `attached` may still say `true` and services may still say they are `entitled` and `enabled`, but if the `expires` date has passed, you should assume the services are not functioning. |
4102 | -* `services`: This is a list of Ubuntu Pro services. Each item has its own attributes. Widely applicable services include those with `name` equal to `esm-infra`, `esm-apps`, and `livepatch`. Some important fields in each service object are: |
4103 | - * `name`: The name of the service. |
4104 | - * `entitled`: A boolean indicating whether the attached Ubuntu Pro account is allowed to enable this service. |
4105 | - * `status`: A string indicating the service's current status on the machine. Any value other than `enabled` should be treated as if the service is not enabled and not working properly on the machine. Possible values are: |
4106 | - * `enabled`: The service is enabled and working. |
4107 | - * `disabled`: The service can be enabled but is not currently. |
4108 | - * `n/a`: The service cannot be enabled on this machine. |
4109 | - * `warning`: The service is supposed to be enabled but something is wrong. Check the `warning` field in the service item for additional information. |
4110 | - |
4111 | -For example, if you want to programatically find the status of esm-infra on a particular machine, you can use the following command: |
4112 | -```shell |
4113 | -sudo pro status --format=json | jq '.services[] | select(.name == "esm-infra").status' |
4114 | -``` |
4115 | -That command will print one of the `status` values defined above. |
4116 | - |
4117 | -```{attention} |
4118 | -In an future version of Ubuntu Pro Client, there will be an [API](../references/api.md) function to access this information. For now, though, `pro status --format=json` is the recommended machine-readable interface to this data. |
4119 | -``` |
4120 | diff --git a/docs/explanations/what_are_the_timer_jobs.md b/docs/explanations/what_are_the_timer_jobs.md |
4121 | deleted file mode 100644 |
4122 | index fa84b36..0000000 |
4123 | --- a/docs/explanations/what_are_the_timer_jobs.md |
4124 | +++ /dev/null |
4125 | @@ -1,26 +0,0 @@ |
4126 | -# Timer jobs explained |
4127 | - |
4128 | -Ubuntu Pro Client (`pro`) sets up a `systemd` timer to run jobs that need to be |
4129 | -carried out periodically. Every time the timer runs, it decides which jobs need |
4130 | -to be performed based on their intervals. When a job runs successfully, its next |
4131 | -run is determined by the interval defined for that job. |
4132 | - |
4133 | -## Current jobs |
4134 | - |
4135 | -The jobs that `pro` runs periodically are `metering` and `update_messaging`. |
4136 | - |
4137 | -### The `update_messaging` job |
4138 | - |
4139 | -`update_messaging` updates the MOTD and APT messages every 6 hours. It ensures |
4140 | -that the MOTD and APT messages displayed on the system match those that are |
4141 | -available/enabled. It finds updated information about available packages or |
4142 | -security updates and shows these to the user. |
4143 | - |
4144 | -### The `metering` job |
4145 | - |
4146 | -`metering` pings the Canonical servers for contract metering every 4 hours. It |
4147 | -informs Canonical which services are enabled on the machine. |
4148 | - |
4149 | -```{note} |
4150 | -The `metering` job only runs when attached to an Ubuntu Pro subscription. |
4151 | -``` |
4152 | diff --git a/docs/explanations/what_are_ubuntu_pro_cloud_instances.md b/docs/explanations/what_are_ubuntu_pro_cloud_instances.md |
4153 | deleted file mode 100644 |
4154 | index 4e84d7e..0000000 |
4155 | --- a/docs/explanations/what_are_ubuntu_pro_cloud_instances.md |
4156 | +++ /dev/null |
4157 | @@ -1,28 +0,0 @@ |
4158 | -# About Public Cloud Ubuntu Pro images |
4159 | - |
4160 | -Ubuntu Pro images are published to [AWS](https://ubuntu.com/aws/pro), |
4161 | -[Azure](https://ubuntu.com/azure/pro) and [GCP](https://ubuntu.com/gcp/pro). |
4162 | -All of these come with Ubuntu Pro support and services built in. |
4163 | - |
4164 | -On first boot, Ubuntu Pro images will automatically attach to an Ubuntu Pro |
4165 | -support contract and enable all necessary Ubuntu Pro services so that no extra |
4166 | -setup is required to ensure a secure and supported Ubuntu machine. |
4167 | - |
4168 | -There are two primary flavors of Ubuntu Pro images in clouds: *Ubuntu Pro*, and |
4169 | -*Ubuntu Pro FIPS*. |
4170 | - |
4171 | -## Ubuntu Pro |
4172 | - |
4173 | -These Ubuntu LTS images are provided already attached to Ubuntu Pro support, |
4174 | -with kernel Livepatch and ESM security access enabled. Ubuntu Pro images are |
4175 | -entitled to enable any additional Ubuntu Pro services (like |
4176 | -[`fips`](../howtoguides/enable_fips.md) or |
4177 | -[`usg`](../howtoguides/enable_cis.md)). |
4178 | - |
4179 | -## Ubuntu Pro FIPS |
4180 | - |
4181 | -These specialized Ubuntu Pro images for 16.04, 18.04 and 20.04 come pre-enabled |
4182 | -with the cloud-optimized FIPS-certified kernel, as well as all additional SSL |
4183 | -and security hardening enabled. These images are available as |
4184 | -[AWS Ubuntu Pro FIPS](https://ubuntu.com/aws/fips), |
4185 | -[Azure Ubuntu Pro FIPS](https://ubuntu.com/azure/fips) and GCP Ubuntu Pro FIPS. |
4186 | diff --git a/docs/explanations/what_is_the_daemon.md b/docs/explanations/what_is_the_daemon.md |
4187 | deleted file mode 100644 |
4188 | index 0ad510f..0000000 |
4189 | --- a/docs/explanations/what_is_the_daemon.md |
4190 | +++ /dev/null |
4191 | @@ -1,14 +0,0 @@ |
4192 | -# What is the Pro upgrade daemon? |
4193 | - |
4194 | -Ubuntu Pro Client sets up a daemon on supported platforms (currently GCP |
4195 | -only) to detect if an Ubuntu Pro license has been purchased for the machine. |
4196 | -If a Pro license is detected, then the machine is automatically attached. |
4197 | - |
4198 | -If you are not interested in Ubuntu Pro services and don't want your machine to |
4199 | -be automatically attached to your subscription, you can safely stop and disable |
4200 | -the daemon using `systemctl`: |
4201 | - |
4202 | -``` |
4203 | -sudo systemctl stop ubuntu-advantage.service |
4204 | -sudo systemctl disable ubuntu-advantage.service |
4205 | -``` |
4206 | diff --git a/docs/explanations/what_is_the_ubuntu_advantage_pro_package.md b/docs/explanations/what_is_the_ubuntu_advantage_pro_package.md |
4207 | deleted file mode 100644 |
4208 | index 337e97c..0000000 |
4209 | --- a/docs/explanations/what_is_the_ubuntu_advantage_pro_package.md |
4210 | +++ /dev/null |
4211 | @@ -1,8 +0,0 @@ |
4212 | -# What is the `ubuntu-advantage-pro` package? |
4213 | - |
4214 | -The `ubuntu-advantage-pro` package is used by |
4215 | -[Public Cloud Ubuntu Pro](what_are_ubuntu_pro_cloud_instances.md) machines to |
4216 | -automate the process of attaching a machine on boot. |
4217 | - |
4218 | -Therefore, the only thing that `ubuntu-advantage-pro` does is ship a `systemd` |
4219 | -unit that runs an auto-attach command on first boot. |
4220 | diff --git a/docs/explanations/what_refresh_does.md b/docs/explanations/what_refresh_does.md |
4221 | deleted file mode 100644 |
4222 | index 5312962..0000000 |
4223 | --- a/docs/explanations/what_refresh_does.md |
4224 | +++ /dev/null |
4225 | @@ -1,25 +0,0 @@ |
4226 | -# What `pro refresh` does |
4227 | - |
4228 | -When you run the `pro refresh` command on your machine, three distinct stages |
4229 | -are performed. |
4230 | - |
4231 | -## Contract |
4232 | - |
4233 | -The contract information on the machine is refreshed. If we find any deltas |
4234 | -between the old contract and the new one, we process that delta and apply the |
4235 | -changes to the machine. |
4236 | - |
4237 | -If you need *only* this stage during refresh, run `pro refresh contract`. |
4238 | - |
4239 | -## Configuration |
4240 | - |
4241 | -If there is any config change made to `/etc/ubuntu-advantage/uaclient.conf`, |
4242 | -those changes will now be applied to the machine. |
4243 | - |
4244 | -If you need *only* this stage during refresh, run `pro refresh config`. |
4245 | - |
4246 | -## MOTD and APT messages |
4247 | - |
4248 | -Processes new MOTD and APT messages, and refreshes the machine to use them. |
4249 | - |
4250 | -If you need *only* this stage during refresh, run `pro refresh messages`. |
4251 | diff --git a/docs/explanations/why_trusty_is_no_longer_supported.md b/docs/explanations/why_trusty_is_no_longer_supported.md |
4252 | deleted file mode 100644 |
4253 | index 3d37ee6..0000000 |
4254 | --- a/docs/explanations/why_trusty_is_no_longer_supported.md |
4255 | +++ /dev/null |
4256 | @@ -1,10 +0,0 @@ |
4257 | -# Why is 14.04 (Trusty) no longer supported? |
4258 | - |
4259 | -On 14.04 (Trusty), the Ubuntu Pro Client package is not receiving upstream |
4260 | -updates beyond version 19.6, plus any critical CVE maintenance related to this |
4261 | -version. |
4262 | - |
4263 | -Version 19.6 already has full-featured support of the applicable Ubuntu Pro |
4264 | -service offerings `esm-infra` and `livepatch`. In the event that a CVE is |
4265 | -discovered that affects the Ubuntu Pro Client version on Trusty, a fix and |
4266 | -backport will be provided for those specific issues. |
4267 | diff --git a/docs/googleaf254801a5285c31.html b/docs/googleaf254801a5285c31.html |
4268 | deleted file mode 100644 |
4269 | index b603071..0000000 |
4270 | --- a/docs/googleaf254801a5285c31.html |
4271 | +++ /dev/null |
4272 | @@ -1 +0,0 @@ |
4273 | -google-site-verification: googleaf254801a5285c31.html |
4274 | \ No newline at end of file |
4275 | diff --git a/docs/howtoguides.rst b/docs/howtoguides.rst |
4276 | deleted file mode 100644 |
4277 | index 5b93de6..0000000 |
4278 | --- a/docs/howtoguides.rst |
4279 | +++ /dev/null |
4280 | @@ -1,102 +0,0 @@ |
4281 | -Ubuntu Pro Client how-to guides |
4282 | -******************************* |
4283 | - |
4284 | -If you have a specific goal and are already familiar with the Ubuntu Pro Client |
4285 | -(``pro``), our how-to guides have more in-depth detail than our tutorials and |
4286 | -can be applied to a wider range of situations. |
4287 | - |
4288 | -They will help you to achieve a particular end result, but may require you to |
4289 | -understand and adapt the steps to fit your specific requirements. |
4290 | - |
4291 | -How to use ``pro`` commands |
4292 | -=========================== |
4293 | - |
4294 | -``attach`` |
4295 | ----------- |
4296 | - |
4297 | -.. toctree:: |
4298 | - :maxdepth: 1 |
4299 | - |
4300 | - Get an Ubuntu Pro token and attach to a subscription <howtoguides/get_token_and_attach.md> |
4301 | - Attach with a configuration file <howtoguides/how_to_attach_with_config_file.md> |
4302 | - |
4303 | -``collect-logs`` |
4304 | ----------------- |
4305 | - |
4306 | -.. toctree:: |
4307 | - :maxdepth: 1 |
4308 | - |
4309 | - Collect data logs for bug reporting <howtoguides/how_to_collect_logs.md> |
4310 | - |
4311 | -``config`` |
4312 | ----------- |
4313 | - |
4314 | -.. toctree:: |
4315 | - :maxdepth: 1 |
4316 | - |
4317 | - Disable or re-enable APT News <howtoguides/disable_enable_apt_news.md> |
4318 | - Configure a proxy <howtoguides/configure_proxies.md> |
4319 | - Configure a timer job <howtoguides/configuring_timer_jobs.md> |
4320 | - |
4321 | -``enable`` |
4322 | ----------- |
4323 | - |
4324 | -.. toctree:: |
4325 | - :maxdepth: 1 |
4326 | - |
4327 | - Enable Pro Services in a Dockerfile <howtoguides/enable_in_dockerfile.md> |
4328 | - Enable CC EAL <howtoguides/enable_cc.md> |
4329 | - Enable CIS <howtoguides/enable_cis.md> |
4330 | - Enable Expanded Security Maintenance for Infrastructure <howtoguides/enable_esm_infra.md> |
4331 | - Enable FIPS <howtoguides/enable_fips.md> |
4332 | - Enable Livepatch <howtoguides/enable_livepatch.md> |
4333 | - Enable Real-Time Kernel <howtoguides/enable_realtime_kernel.md> |
4334 | - |
4335 | -``fix`` |
4336 | -------- |
4337 | - |
4338 | -.. toctree:: |
4339 | - :maxdepth: 1 |
4340 | - |
4341 | - Run `fix` in "dry run" mode <howtoguides/how_to_run_fix_in_dry_run_mode.md> |
4342 | - Skip fixing related USNs <howtoguides/how_to_not_fix_related_usns.md> |
4343 | - |
4344 | -``refresh`` |
4345 | ------------ |
4346 | - |
4347 | -.. toctree:: |
4348 | - :maxdepth: 1 |
4349 | - |
4350 | - Update MOTD and APT messages <howtoguides/update_motd_messages.md> |
4351 | - |
4352 | -``status`` |
4353 | ----------- |
4354 | - |
4355 | -.. toctree:: |
4356 | - :maxdepth: 1 |
4357 | - |
4358 | - Simulate the `attach` operation <howtoguides/how_to_simulate_attach.md> |
4359 | - |
4360 | -``version`` |
4361 | ------------ |
4362 | - |
4363 | -.. toctree:: |
4364 | - :maxdepth: 1 |
4365 | - |
4366 | - Check Ubuntu Pro Client version <howtoguides/check_pro_version> |
4367 | - |
4368 | -``lock`` |
4369 | ------------ |
4370 | - |
4371 | -.. toctree:: |
4372 | - :maxdepth: 1 |
4373 | - |
4374 | - Get rid of corrupted locks <howtoguides/get_rid_of_corrupt_lock.md> |
4375 | - |
4376 | -Create a ``pro`` Golden Image |
4377 | -============================= |
4378 | - |
4379 | -.. toctree:: |
4380 | - :maxdepth: 1 |
4381 | - |
4382 | - Create a customised Cloud Ubuntu Pro image <howtoguides/create_pro_golden_image.md> |
4383 | diff --git a/docs/howtoguides/check_pro_version.md b/docs/howtoguides/check_pro_version.md |
4384 | deleted file mode 100644 |
4385 | index faeaf6b..0000000 |
4386 | --- a/docs/howtoguides/check_pro_version.md |
4387 | +++ /dev/null |
4388 | @@ -1,14 +0,0 @@ |
4389 | -# How to check your Ubuntu Pro Client version |
4390 | - |
4391 | -There are two ways to check the current version of the Ubuntu Pro Client you |
4392 | -are running. You can use the command: |
4393 | - |
4394 | -```bash |
4395 | -pro version |
4396 | -``` |
4397 | - |
4398 | -Or the alternative: |
4399 | - |
4400 | -```bash |
4401 | -pro --version |
4402 | -``` |
4403 | diff --git a/docs/howtoguides/configure_proxies.md b/docs/howtoguides/configure_proxies.md |
4404 | deleted file mode 100644 |
4405 | index 4fa5081..0000000 |
4406 | --- a/docs/howtoguides/configure_proxies.md |
4407 | +++ /dev/null |
4408 | @@ -1,120 +0,0 @@ |
4409 | -# How to configure a proxy |
4410 | - |
4411 | -The Ubuntu Pro Client can be configured to use an HTTP/HTTPS proxy as needed |
4412 | -for network requests. It will also honor the `no_proxy` environment variable |
4413 | -(if set) to avoid using local proxies for certain outbound traffic. In |
4414 | -addition, the Ubuntu Pro Client will automatically set up proxies for all |
4415 | -programs required for enabling Ubuntu Pro services. This includes APT, Snaps, |
4416 | -and Livepatch. |
4417 | - |
4418 | -## HTTP/HTTPS proxies |
4419 | - |
4420 | -To configure standard HTTP and/or HTTPS proxies, run the following commands: |
4421 | - |
4422 | -```console |
4423 | -$ sudo pro config set http_proxy=http://host:port |
4424 | -$ sudo pro config set https_proxy=https://host:port |
4425 | -``` |
4426 | - |
4427 | -After running the above commands, Ubuntu Pro Client will: |
4428 | - |
4429 | -1. Verify that the proxy is working by using it to reach `api.snapcraft.io` |
4430 | -2. Configure itself to use the given proxy for all future network requests |
4431 | -3. Configure `snapd` (if `snapd` is installed) to use the given proxy |
4432 | -4. Configure Livepatch (if Livepatch has already been enabled) to use the given |
4433 | - proxy |
4434 | - 1. If Livepatch is enabled after the `config` command, Ubuntu Pro Client |
4435 | - will configure Livepatch to use the given proxy at that time. |
4436 | - |
4437 | -To remove HTTP/HTTPS proxy configuration, run the following: |
4438 | - |
4439 | -```console |
4440 | -$ sudo pro config unset http_proxy |
4441 | -$ sudo pro config unset https_proxy |
4442 | -``` |
4443 | - |
4444 | -After running the above commands, Ubuntu Pro Client will also remove proxy |
4445 | -configuration from `snapd` (if installed) and Livepatch (if enabled). |
4446 | - |
4447 | -## APT proxies |
4448 | - |
4449 | -APT proxy settings are configured separately. To have Ubuntu Pro Client manage |
4450 | -your global APT proxy configuration, run the following commands: |
4451 | - |
4452 | -```console |
4453 | -$ sudo pro config set global_apt_http_proxy=http://host:port |
4454 | -$ sudo pro config set global_apt_https_proxy=https://host:port |
4455 | -``` |
4456 | - |
4457 | -After running the above commands, Ubuntu Pro Client will: |
4458 | - |
4459 | -1. Verify that the proxy works by using it to reach `archive.ubuntu.com` or |
4460 | - `esm.ubuntu.com`. |
4461 | -2. Configure APT to use the given proxy by writing an apt configuration file to |
4462 | - `/etc/apt/apt.conf.d/90ubuntu-advantage-aptproxy`. |
4463 | - |
4464 | -```{caution} |
4465 | -Any configuration file that comes later in the `apt.conf.d` |
4466 | -directory could override the proxy configured by the Ubuntu Pro Client. |
4467 | -``` |
4468 | - |
4469 | -To remove the APT proxy configuration, run the following: |
4470 | - |
4471 | -``` |
4472 | -$ sudo pro config unset global_apt_http_proxy |
4473 | -$ sudo pro config unset global_apt_https_proxy |
4474 | -``` |
4475 | - |
4476 | -```{attention} |
4477 | -Starting in version 27.9, APT proxy config options changed. |
4478 | -The old settings: `apt_http_proxy` and `apt_https_proxy` will still work and |
4479 | -will be treated the same as `global_apt_http_proxy` and |
4480 | -`global_apt_https_proxy`, respectively. |
4481 | -``` |
4482 | - |
4483 | -### Pro-service-only APT proxies |
4484 | - |
4485 | -To set an APT proxy that will only be used for Ubuntu Pro services, use the |
4486 | -following commands instead: |
4487 | - |
4488 | -```console |
4489 | -$ sudo pro config set ua_apt_http_proxy=http://host:port |
4490 | -$ sudo pro config set ua_apt_https_proxy=https://host:port |
4491 | -``` |
4492 | - |
4493 | -## Authenticate your proxy server |
4494 | - |
4495 | -If your proxy server requires authentication, you can pass the credentials |
4496 | -directly in the URL when setting the configuration, as in: |
4497 | - |
4498 | -``` |
4499 | -$ sudo pro config set https_proxy=https://username:password@host:port |
4500 | -``` |
4501 | - |
4502 | -## Check the configuration |
4503 | - |
4504 | -To see which proxies Ubuntu Pro Client is currently configured to use, you can |
4505 | -use the `show` command. |
4506 | - |
4507 | -```console |
4508 | -$ sudo pro config show |
4509 | -``` |
4510 | - |
4511 | -The above will output something that looks like the following if there are |
4512 | -proxies set: |
4513 | - |
4514 | -``` |
4515 | -http_proxy http://proxy |
4516 | -https_proxy https://proxy |
4517 | -global_apt_http_proxy http://aptproxy |
4518 | -global_apt_https_proxy https://aptproxy |
4519 | -``` |
4520 | - |
4521 | -Or it may look like this if there aren’t any proxies set: |
4522 | - |
4523 | -``` |
4524 | -http_proxy None |
4525 | -https_proxy None |
4526 | -global_apt_http_proxy None |
4527 | -global_apt_https_proxy None |
4528 | -``` |
4529 | diff --git a/docs/howtoguides/configuring_timer_jobs.md b/docs/howtoguides/configuring_timer_jobs.md |
4530 | deleted file mode 100644 |
4531 | index 05059df..0000000 |
4532 | --- a/docs/howtoguides/configuring_timer_jobs.md |
4533 | +++ /dev/null |
4534 | @@ -1,39 +0,0 @@ |
4535 | -# How to configure a timer job |
4536 | - |
4537 | -All timer jobs can be configured through the `pro config set` command. |
4538 | -We will show how you can properly use this command to interact with timer jobs. |
4539 | - |
4540 | -## Check a timer job's configuration |
4541 | - |
4542 | -To see each job’s running interval, use the `show` command: |
4543 | - |
4544 | -```console |
4545 | -$ sudo pro config show |
4546 | -``` |
4547 | - |
4548 | -You should see output which includes the timer jobs: |
4549 | - |
4550 | -``` |
4551 | -update_messaging_timer 21600 |
4552 | -metering_timer 14400 |
4553 | -``` |
4554 | - |
4555 | -## Change a timer job interval |
4556 | - |
4557 | -Each job has a configuration option of the form `<job_name>_timer`, |
4558 | -which can be set with `pro config`. The expected value is a positive |
4559 | -integer for the number of seconds in the interval. For example, to |
4560 | -change the `update_messaging job` timer interval to run every 24 hours, run: |
4561 | - |
4562 | -```console |
4563 | -$ sudo pro config set update_messaging_timer=86400 |
4564 | -``` |
4565 | - |
4566 | -## Disable a timer job |
4567 | - |
4568 | -To disable a job, set its interval to zero. For instance, to disable |
4569 | -the `update_messaging` job, run: |
4570 | - |
4571 | -```console |
4572 | -$ sudo pro config set update_messaging_timer=0 |
4573 | -``` |
4574 | diff --git a/docs/howtoguides/create_pro_golden_image.md b/docs/howtoguides/create_pro_golden_image.md |
4575 | deleted file mode 100644 |
4576 | index 99e4265..0000000 |
4577 | --- a/docs/howtoguides/create_pro_golden_image.md |
4578 | +++ /dev/null |
4579 | @@ -1,14 +0,0 @@ |
4580 | -# How to create a customised Cloud Ubuntu Pro image |
4581 | - |
4582 | -* Launch an Ubuntu Pro instance on your cloud of choice |
4583 | -* Customize the instance as you see fit |
4584 | -* Run the command: `sudo rm /etc/machine-id` |
4585 | -* Use your cloud platform to clone or snapshot this VM as a golden image |
4586 | - |
4587 | -```{tip} |
4588 | -Prior to version 27.11 - when launching instances based on this instance, |
4589 | -you will need to re-enable any non-standard Ubuntu Pro services that you |
4590 | -enabled on the image. This will be faster on the new instance because it was |
4591 | -already enabled on the image. You will not need to reboot for e.g. `fips` or |
4592 | -`fips-updates`. |
4593 | -``` |
4594 | diff --git a/docs/howtoguides/disable_enable_apt_news.md b/docs/howtoguides/disable_enable_apt_news.md |
4595 | deleted file mode 100644 |
4596 | index c9ffd59..0000000 |
4597 | --- a/docs/howtoguides/disable_enable_apt_news.md |
4598 | +++ /dev/null |
4599 | @@ -1,45 +0,0 @@ |
4600 | -# How to disable or re-enable APT News |
4601 | - |
4602 | -APT News is a feature that allows for timely package-related news to be displayed during an `apt upgrade`. It is distinct from [Ubuntu Pro 'available update' messages](../explanations/apt_messages.md) that are also displayed during an `apt upgrade`. APT News messages are fetched from [https://motd.ubuntu.com/aptnews.json](https://motd.ubuntu.com/aptnews.json) at most once per day. |
4603 | - |
4604 | -By default, APT News is turned on. In this How-to-guide, we show how to turn off and on the APT News feature for a particular machine. |
4605 | - |
4606 | -## Step 1: Check the current configuration of APT News |
4607 | - |
4608 | -``` |
4609 | -pro config show apt_news |
4610 | -``` |
4611 | - |
4612 | -The default value is `True`, so if you haven't yet modified this setting, you will see: |
4613 | -``` |
4614 | -apt_news True |
4615 | -``` |
4616 | - |
4617 | -## Step 2: Disable APT News |
4618 | - |
4619 | -``` |
4620 | -pro config set apt_news=false |
4621 | -``` |
4622 | - |
4623 | -This should also clear any current APT News you may be seeing on your system during `apt upgrade`. |
4624 | - |
4625 | -You can double-check that the setting was successful by running the following again: |
4626 | - |
4627 | -``` |
4628 | -pro config show apt_news |
4629 | -``` |
4630 | - |
4631 | -You should now see: |
4632 | -``` |
4633 | -apt_news False |
4634 | -``` |
4635 | - |
4636 | -## Step 3: (Optional) Re-enable APT News |
4637 | - |
4638 | -If you change your mind and want APT News to start appearing again in `apt upgrade`, run the following: |
4639 | - |
4640 | -``` |
4641 | -pro config set apt_news=true |
4642 | -``` |
4643 | - |
4644 | -And verify the setting worked with `pro config show apt_news`. |
4645 | diff --git a/docs/howtoguides/enable_cc.md b/docs/howtoguides/enable_cc.md |
4646 | deleted file mode 100644 |
4647 | index 45e9435..0000000 |
4648 | --- a/docs/howtoguides/enable_cc.md |
4649 | +++ /dev/null |
4650 | @@ -1,56 +0,0 @@ |
4651 | -# How to enable CC EAL |
4652 | - |
4653 | -```{note} |
4654 | -CC EAL can be enabled on both Xenial and Bionic, but the installed scripts |
4655 | -that configure CC EAL on those machines will only run on Xenial 16.04.4 and |
4656 | -Bionic 18.04.4 point releases. |
4657 | - |
4658 | -Common Criteria is supported only on 16.04 and 18.04. For more information, |
4659 | -please see https://ubuntu.com/security/cc |
4660 | -``` |
4661 | - |
4662 | -## Enable and auto-install |
4663 | - |
4664 | -To enable CC EAL using the Ubuntu Pro Client, please run: |
4665 | - |
4666 | -```console |
4667 | -$ sudo pro enable cc-eal |
4668 | -``` |
4669 | - |
4670 | -You should see output like the following, indicating that the CC EAL package |
4671 | -has been installed. |
4672 | - |
4673 | -``` |
4674 | -(This will download more than 500MB of packages, so may take some time.) |
4675 | -Installing CC EAL2 packages |
4676 | -CC EAL2 enabled |
4677 | -Please follow instructions in /usr/share/doc/ubuntu-commoncriteria/README to configure EAL2 |
4678 | -``` |
4679 | - |
4680 | -## Enable and manually install |
4681 | - |
4682 | -```{important} |
4683 | -The --access-only flag is introduced in version 27.11 |
4684 | -``` |
4685 | - |
4686 | -If you would like to enable access to the CC EAL apt repository but not install |
4687 | -the packages right away, use the `--access-only` flag while enabling. |
4688 | - |
4689 | -```console |
4690 | -$ sudo pro enable cc-eal --access-only |
4691 | -``` |
4692 | - |
4693 | -With that extra flag you'll see output like the following: |
4694 | - |
4695 | -``` |
4696 | -One moment, checking your subscription first |
4697 | -Updating package lists |
4698 | -Skipping installing packages: ubuntu-commoncriteria |
4699 | -CC EAL2 access enabled |
4700 | -``` |
4701 | - |
4702 | -To install the packages you can then run: |
4703 | - |
4704 | -```console |
4705 | -$ sudo apt install ubuntu-commoncriteria |
4706 | -``` |
4707 | diff --git a/docs/howtoguides/enable_cis.md b/docs/howtoguides/enable_cis.md |
4708 | deleted file mode 100644 |
4709 | index 380075b..0000000 |
4710 | --- a/docs/howtoguides/enable_cis.md |
4711 | +++ /dev/null |
4712 | @@ -1,27 +0,0 @@ |
4713 | -# How to enable CIS |
4714 | - |
4715 | -```{note} |
4716 | -On Focal (and later releases), CIS was |
4717 | -[replaced by USG](https://ubuntu.com/security/certifications/docs/usg), |
4718 | -therefore, just change `cis` to `usg` when running the enable command on those |
4719 | -releases. |
4720 | -``` |
4721 | - |
4722 | -To access the CIS tooling, first enable the software repository as follows: |
4723 | - |
4724 | -```console |
4725 | -$ sudo pro enable cis |
4726 | -``` |
4727 | - |
4728 | -You should see output like the following, indicating that the CIS package has |
4729 | -been installed: |
4730 | - |
4731 | -``` |
4732 | -Installing CIS Audit packages |
4733 | -CIS Audit enabled |
4734 | -Visit https://security-certs.docs.ubuntu.com/en/cis to learn how to use CIS |
4735 | -``` |
4736 | - |
4737 | -Once the feature is enabled please |
4738 | -[follow the documentation](https://ubuntu.com/security/certifications/docs/cis) |
4739 | -for the CIS tooling, to run the provided hardening audit scripts. |
4740 | diff --git a/docs/howtoguides/enable_esm_infra.md b/docs/howtoguides/enable_esm_infra.md |
4741 | deleted file mode 100644 |
4742 | index efdaf55..0000000 |
4743 | --- a/docs/howtoguides/enable_esm_infra.md |
4744 | +++ /dev/null |
4745 | @@ -1,32 +0,0 @@ |
4746 | -# How to enable Expanded Security Maintenance for Infrastructure (`esm-infra`) |
4747 | - |
4748 | -For Ubuntu LTS releases, `esm-infra` will be automatically enabled after |
4749 | -attaching the Ubuntu Pro Client to your account. After `ubuntu-advantage-tools` |
4750 | -is installed and your machine is attached, `esm-infra` should be enabled. If |
4751 | -`esm-infra` is not enabled, you can enable it with the following command: |
4752 | - |
4753 | -```console |
4754 | -$ sudo pro enable esm-infra |
4755 | -``` |
4756 | - |
4757 | -With the `esm-infra` repository enabled, especially on Ubuntu 14.04 and 16.04, |
4758 | -you may see a number of additional package updates available that were not |
4759 | -available previously. |
4760 | - |
4761 | -Even if your system had indicated that it was up to date before installing the |
4762 | -`ubuntu-advantage-tools` and attaching, make sure to check for new package |
4763 | -updates after `esm-infra` is enabled using `apt upgrade`. If you have cron jobs |
4764 | -set to install updates, or other unattended upgrades configured, be aware that |
4765 | -this will likely result in a number of package updates with the `esm-infra` |
4766 | -content. |
4767 | - |
4768 | -Running `apt upgrade` will now apply all available package updates, including |
4769 | -the ones in `esm-infra`. |
4770 | - |
4771 | -```console |
4772 | -$ sudo apt upgrade |
4773 | -``` |
4774 | - |
4775 | -```{seealso} |
4776 | -For more information, see https://ubuntu.com/security/esm |
4777 | -``` |
4778 | diff --git a/docs/howtoguides/enable_fips.md b/docs/howtoguides/enable_fips.md |
4779 | deleted file mode 100644 |
4780 | index 4fe8b8a..0000000 |
4781 | --- a/docs/howtoguides/enable_fips.md |
4782 | +++ /dev/null |
4783 | @@ -1,40 +0,0 @@ |
4784 | -# How to enable FIPS |
4785 | - |
4786 | -```{important} |
4787 | -[FIPS is supported on 16.04, 18.04 and 20.04 releases](https://ubuntu.com/security/certifications/docs/fips). |
4788 | -``` |
4789 | - |
4790 | -To use FIPS, one can either launch existing Ubuntu premium support images which |
4791 | -already have FIPS kernel and security pre-enabled on first boot at |
4792 | -[AWS Ubuntu Pro FIPS images](https://ubuntu.com/aws/fips), |
4793 | -[Azure Pro FIPS images](https://ubuntu.com/azure/fips) and GCP Pro FIPS Images. |
4794 | - |
4795 | -Alternatively, you can enable FIPS using the Ubuntu Pro Client, which will |
4796 | -install a FIPS-certified kernel and core security-related packages such as |
4797 | -`openssh-server/client` and `libssl`. |
4798 | - |
4799 | -```{danger} |
4800 | -Disabling FIPS is not currently supported: only use it on machines intended |
4801 | -expressly for this purpose. |
4802 | -``` |
4803 | - |
4804 | -```{danger} |
4805 | -Enabling FIPS should be performed during a system maintenance window because |
4806 | -this operation makes changes to underlying SSL-related libraries and requires a |
4807 | -reboot into the FIPS-certified kernel. |
4808 | -``` |
4809 | - |
4810 | -To enable FIPS, run: |
4811 | - |
4812 | -```console |
4813 | -$ sudo pro enable fips |
4814 | -``` |
4815 | - |
4816 | -You should see output like the following, indicating that the FIPS packages has |
4817 | -been installed: |
4818 | - |
4819 | -``` |
4820 | -Installing FIPS packages |
4821 | -FIPS enabled |
4822 | -A reboot is required to complete install. |
4823 | -``` |
4824 | diff --git a/docs/howtoguides/enable_in_dockerfile.md b/docs/howtoguides/enable_in_dockerfile.md |
4825 | deleted file mode 100644 |
4826 | index 5501a92..0000000 |
4827 | --- a/docs/howtoguides/enable_in_dockerfile.md |
4828 | +++ /dev/null |
4829 | @@ -1,156 +0,0 @@ |
4830 | -# How to enable Ubuntu Pro Services in a Dockerfile |
4831 | - |
4832 | -```{important} |
4833 | -This requires at least Ubuntu Pro Client version 27.7 |
4834 | -``` |
4835 | - |
4836 | -Ubuntu Pro comes with several services, some of which can be useful in Docker. |
4837 | -For example, Expanded Security Maintenance (ESM) of packages and FIPS-certified |
4838 | -packages may be desirable in a Docker image. In this how-to guide, we show how |
4839 | -you can use the `pro` tool to take advantage of these services in your |
4840 | -Dockerfile. |
4841 | - |
4842 | -## Create an Ubuntu Pro Attach Config file |
4843 | - |
4844 | -```{attention} |
4845 | -The Ubuntu Pro Attach Config file will contain your Ubuntu Pro Contract token |
4846 | -and should be treated as a secret file. |
4847 | -``` |
4848 | - |
4849 | -An Attach Config file for `pro` is a YAML file that specifies some options when |
4850 | -running `pro attach`. The file has two fields, `token` and `enable_services` |
4851 | -and looks something like this: |
4852 | - |
4853 | -```yaml |
4854 | -token: TOKEN |
4855 | -enable_services: |
4856 | - - service1 |
4857 | - - service2 |
4858 | - - service3 |
4859 | -``` |
4860 | - |
4861 | -The `token` field is required and must be set to your Ubuntu Pro token that you |
4862 | -can get from signing into [ubuntu.com/pro](https://ubuntu.com/pro). |
4863 | - |
4864 | -The `enable_services` field value is a list of Ubuntu Pro service names. When |
4865 | -it is set, then the services specified will be automatically enabled after |
4866 | -attaching with your Ubuntu Pro token. |
4867 | - |
4868 | -Service names that you may be interested in enabling in your Docker builds |
4869 | -include: |
4870 | - |
4871 | -- `esm-infra` |
4872 | -- `esm-apps` |
4873 | -- `fips` |
4874 | -- `fips-updates` |
4875 | - |
4876 | -You can find out more about these services by running `pro help service-name` |
4877 | -on any Ubuntu machine. |
4878 | - |
4879 | -## Create a Dockerfile to use `pro` and your Attach Config file |
4880 | - |
4881 | -Your Dockerfile is going to look something like the following -- there are |
4882 | -inline comments explaining each line: |
4883 | - |
4884 | -```dockerfile |
4885 | -# Base off of the LTS of your choice |
4886 | -FROM ubuntu:focal |
4887 | - |
4888 | -# We mount a BuildKit secret here to access the attach config file which should |
4889 | -# be kept separate from the Dockerfile and managed in a secure fashion since it |
4890 | -# needs to contain your Ubuntu Pro token. |
4891 | -# In the next step, we demonstrate how to pass the file as a secret when |
4892 | -# running docker build. |
4893 | -RUN --mount=type=secret,id=pro-attach-config \ |
4894 | - # |
4895 | - # First we update apt so we install the correct versions of packages in |
4896 | - # the next step |
4897 | - apt-get update \ |
4898 | - # |
4899 | - # Here we install `pro` (ubuntu-advantage-tools) as well as ca-certificates, |
4900 | - # which is required to talk to the Ubuntu Pro authentication server securely. |
4901 | - && apt-get install --no-install-recommends -y ubuntu-advantage-tools ca-certificates \ |
4902 | - # |
4903 | - # With pro installed, we attach using our attach config file from the |
4904 | - # previous step |
4905 | - && pro attach --attach-config /run/secrets/pro-attach-config \ |
4906 | - # |
4907 | - ########################################################################### |
4908 | - # At this point, the container has access to all Ubuntu Pro services |
4909 | - # specified in the attach config file. |
4910 | - ########################################################################### |
4911 | - # |
4912 | - # Always upgrade all packages to the latest available version with the Ubuntu Pro |
4913 | - # services enabled. |
4914 | - && apt-get upgrade -y \ |
4915 | - # |
4916 | - # Then, you can install any specific packages you need for your docker |
4917 | - # container. |
4918 | - # Install them here, while Ubuntu Pro is enabled, so that you get the appropriate |
4919 | - # versions. |
4920 | - # Any `apt-get install ...` commands you have in an existing Dockerfile |
4921 | - # that you may be migrating to use Ubuntu Pro should probably be moved here. |
4922 | - && apt-get install -y openssl \ |
4923 | - # |
4924 | - ########################################################################### |
4925 | - # Now that we have upgraded and installed any packages from the Ubuntu Pro |
4926 | - # services, we can clean up. |
4927 | - ########################################################################### |
4928 | - # |
4929 | - # This purges ubuntu-advantage-tools, including all Ubuntu Pro related |
4930 | - # secrets from the system. |
4931 | - ########################################################################### |
4932 | - # IMPORTANT: As written here, this command assumes your container does not |
4933 | - # need ca-certificates so it is purged as well. |
4934 | - # If your container needs ca-certificates, then do not purge it from the |
4935 | - # system here. |
4936 | - ########################################################################### |
4937 | - && apt-get purge --auto-remove -y ubuntu-advantage-tools ca-certificates \ |
4938 | - # |
4939 | - # Finally, we clean up the apt lists which should not be needed anymore |
4940 | - # because any `apt-get install`s should have happened above. Cleaning these |
4941 | - # lists keeps your image smaller. |
4942 | - && rm -rf /var/lib/apt/lists/* |
4943 | - |
4944 | - |
4945 | -# Now, with all of your ubuntu apt packages installed, including all those |
4946 | -# from Ubuntu Pro services, you can continue the rest of your app-specific Dockerfile. |
4947 | -``` |
4948 | - |
4949 | -An important point to note about the above Dockerfile is that all of the `apt` |
4950 | -and `pro` commands happen inside one Dockerfile `RUN` instruction. This is |
4951 | -critical and must not be changed. Keeping everything as written inside of |
4952 | -one `RUN` instruction has two key benefits: |
4953 | - |
4954 | -1. It prevents any Ubuntu Pro Subscription-related tokens and secrets from |
4955 | - being leaked in an image layer. |
4956 | -2. It keeps the image as small as possible by cleaning up extra packages and |
4957 | - files before the layer is finished. |
4958 | - |
4959 | -```{note} |
4960 | -These benefits could also be attained by squashing the image. |
4961 | -``` |
4962 | - |
4963 | -## Build the Docker image |
4964 | - |
4965 | -Now, with our Attach Config file and Dockerfile created, we can build the image |
4966 | -with a command like the following: |
4967 | - |
4968 | -```bash |
4969 | -DOCKER_BUILDKIT=1 docker build . --secret id=pro-attach-config,src=pro-attach-config.yaml -t ubuntu-focal-pro |
4970 | -``` |
4971 | - |
4972 | -There are two important pieces to this command. |
4973 | - |
4974 | -1. We enable BuildKit with `DOCKER_BUILDKIT=1`. This is necessary to support |
4975 | - the secret mount feature. |
4976 | -2. We use the secret mount feature of BuildKit with |
4977 | - `--secret id=pro-attach-config,src=pro-attach-config.yaml`. This is what |
4978 | - passes our Attach Config file in to be securely used by the |
4979 | - `RUN --mount=type=secret,id=pro-attach-config` command in the Dockerfile. |
4980 | - |
4981 | -## Success |
4982 | - |
4983 | -Congratulations! At this point, you should have a docker image that has been |
4984 | -built with Ubuntu Pro packages installed from whichever Ubuntu Pro service you |
4985 | -required. |
4986 | diff --git a/docs/howtoguides/enable_livepatch.md b/docs/howtoguides/enable_livepatch.md |
4987 | deleted file mode 100644 |
4988 | index d220553..0000000 |
4989 | --- a/docs/howtoguides/enable_livepatch.md |
4990 | +++ /dev/null |
4991 | @@ -1,34 +0,0 @@ |
4992 | -# How to enable Livepatch |
4993 | - |
4994 | -```{important} |
4995 | -Check if your kernel is supported by Livepatch here: |
4996 | -https://ubuntu.com/security/livepatch/docs/kernels |
4997 | -``` |
4998 | - |
4999 | -To enable Livepatch, run: |
5000 | - |
Xenial tests: advantage- tools/29~ 16.04~rc1: Published /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= amd64&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= arm64&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= armhf&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= ppcel64& trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= riscv64& trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= s390x&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= amd64&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍 /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= arm64&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍 /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= armhf&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍 /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= ppcel64& trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍 /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= riscv64& trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍 /autopkgtest. ubuntu. com/request. cgi?release= xenial& package= ubuntu- advantage- tools&arch= s390x&trigger= ubuntu- advantage- tools%2F29~ 16.04~rc1& ppa=ua- client% 2Fstaging💍
- Source ubuntu-
+ amd64: https:/
+ arm64: https:/
+ armhf: https:/
+ ppcel64: https:/
+ riscv64: https:/
+ s390x: https:/
+ amd64: https:/
+ arm64: https:/
+ armhf: https:/
+ ppcel64: https:/
+ riscv64: https:/
+ s390x: https:/
Bionic tests:
- Source ubuntu- advantage- tools/29~ 18.04~rc1: Published /autopkgtest. ubuntu. com/request. cgi?release= bionic& package= ubuntu- advantage- tools&arch= amd64&trigger= ubuntu- advantage- tools%2F29~ 18.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= bionic& package= ubuntu- advantage- tools&arch= arm64&trigger= ubuntu- advantage- tools%2F29~ 18.04~rc1& ppa=ua- client% 2Fstaging♻️ /autopkgtest. ubuntu. com/request. cgi?release= bionic& package= ubuntu- advantage- tools&arch= armhf&trigger= ubuntu- advantage- tools%2F29~ 18.04~rc1& ppa=ua- client% 2Fstaging♻️ /a...
+ amd64: https:/
+ arm64: https:/
+ armhf: https:/
+ ppcel64: https:/