Add authctl docs #1179

adombeck · 2026-01-05T19:07:38Z

Important

This is based on #1087

Generate authctl docs via cobra.

UDENG-8760

adombeck · 2026-01-06T13:29:35Z

@edibotopic do you understand why the build of the docs fails in the CI but not when I build it locally via make html? The command-line options passed to sphinx seem to be about the same.

In the CI I these warnings which I assume are the reason the build fails:

/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_group.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_group_set-gid.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_lock.md.rst:1: WARNING: Document headings start at H2, not H1
looking for now-outdated files... /home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_set-uid.md.rst:1: WARNING: Document headings start at H2, not H1
/home/docs/checkouts/readthedocs.org/user_builds/canonical-authd/checkouts/1179/docs/reference/cli/authctl_user_unlock.md.rst:1: WARNING: Document headings start at H2, not H1

I don't see those locally.

adombeck · 2026-01-06T16:34:16Z

In the CI I these warnings which I assume are the reason the build fails:

FTR, we were able to resolve that - @edibotopic figured out how to ignore these warnings

edibotopic · 2026-01-06T16:38:07Z

FTR, we were able to resolve that - @edibotopic figured out how to ignore these warnings

Thanks @adombeck .

I think it's OK to ignore these warnings for now so that we are better able to support users with these docs. In the long run, we should fix the header levels so that they conform with the rest of the docs.

In future, we can work on improving the doc generation and formatting of the rendered output, depending on capacity, etc.

adombeck · 2026-01-06T16:39:18Z

@edibotopic I think this is now ready for an initial review. Please ignore all the commits which are not touching the documentation, those are from #1087.

The documentation is very rudimentary for now, we might want to write a more extensive overview of authctl and maybe inline the documentation of the separate commands in the index.md. As discussed on MM, we might also want to use gencodo to improve the generated markdown.

adombeck · 2026-01-06T16:42:29Z

we might also want to use gencodo to improve the generated markdown.

For later reference, I pushed a WIP commit which uses gencodo to https://github.com/adombeck/authd/tree/authctl-docs-gencodo

edibotopic

Excellent work @adombeck .

I've left a few minor suggestions and comments.

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command, example:

I think that's probably just a limitation of the native Cobra docgen, but it's something we can look at in future.

docs/reference/cli/index.md

cmd/authctl/group/group.go

cmd/authctl/user/lock.go

cmd/authctl/user/set-uid.go

edibotopic · 2026-01-07T11:16:57Z

cmd/authctl/user/set-uid.go

+Files outside the user's home directory are not updated and must be changed
+manually. Note that changing a UID can be unsafe if files on the system are
+still owned by the original UID: those files may become accessible to a different
+account that is later assigned that UID. To change ownership of all files on the
+system from the old UID to the new UID, run:


Suggested change

Files outside the user's home directory are not updated and must be changed

manually. Note that changing a UID can be unsafe if files on the system are

still owned by the original UID: those files may become accessible to a different

account that is later assigned that UID. To change ownership of all files on the

system from the old UID to the new UID, run:

Files outside the user's home directory are not updated and must be changed

manually.

Note that changing a UID can be unsafe if files on the system are

still owned by the original UID: those files may become accessible to a different

account that is later assigned that UID. To change ownership of all files on the

system from the old UID to the new UID, run:

I think these are separate paragraphs.

I see that starting the sentence with "Note ..." makes it feel like a new paragraph, but conceptually it's about the exact same thing: ownership of files outside the user's home directory must be updated manually

Maybe we could rephrase things to make better fit the sentences into the same paragraph?

I think it just needs something like this to provide a link between the first and second sentences:

Note that changing a UID manually can be unsafe if files on the system are
still owned by the original UID

Note that changing a UID in this way can be unsafe if files on the system are
still owned by the original UID

What do you think?

No, that's not the intended meaning. It's not the "manual change [of file ownership]" in the first sentence which can be unsafe. It's the change of the UID, i.e. the authctl user set-uid command which can be unsafe if there are files on the system still owned by that UID. So what we want to say is "make sure that you do update file ownerships manually for files outside the home directory". Does that make it clearer? If not, I can try to explain the issue in more detail.

Yes, indeed, that makes it more clear.

How do we best rephrase this sentence to also make it clear to the user?

I think we should leave it as the original. The misinterpretation was my own and I understand that after your clarification.

If this was a regular doc, I would probably put the note in its own block so that the first and third sentences flow together more clearly but we can revisit that another time.

cmd/authctl/user/unlock.go

cmd/authctl/group/set-gid.go

edibotopic · 2026-01-07T11:21:29Z

cmd/authctl/group/set-gid.go

+Files outside users' home directories are not updated and must be changed
+manually. Note that changing a GID can be unsafe if files on the system are
+still owned by the original GID: those files may become accessible to a
+different group that is later assigned that GID. To change group ownership of
+all files on the system from the old GID to the new GID, run:


Suggested change

Files outside users' home directories are not updated and must be changed

manually. Note that changing a GID can be unsafe if files on the system are

still owned by the original GID: those files may become accessible to a

different group that is later assigned that GID. To change group ownership of

all files on the system from the old GID to the new GID, run:

Files outside users' home directories are not updated and must be changed

manually.

Note that changing a GID can be unsafe if files on the system are

still owned by the original GID: those files may become accessible to a

different group that is later assigned that GID. To change group ownership of

all files on the system from the old GID to the new GID, run:

Can reconsider based on discussion of similar case above.

adombeck · 2026-01-07T14:53:45Z

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command

Yeah, that also annoyed me. I think the description just doesn't belong in the "Synopsis" section. My understanding of a "Synopsis" is that it's only the formal description of how to run the command what command line options it takes (like authctl user lock <user> [flags]). In my opinion the description should go in a separate section, like in man pages. I already opened a PR upstream to change that: spf13/cobra#2344

This is an issue which we could fix with gencodo.

edibotopic · 2026-01-07T15:51:07Z

Some of the more elaborate synopses tend to push the basic usage example (Use) quite far down, and visually pair it with a separate command

Yeah, that also annoyed me.
[...]
This is an issue which we could fix with gencodo.

Thanks for the context @adombeck . I agree, let's wait for gencodo. It's OK for now.

There's nothing encrypted in this string.

... instead of prefixing the error message with "permission denied"

Required to change the ownership of the user's home directory when changing the user's UID.

We use this to recursively change the owner and group of the user's home directory when changing the user's UID.

Needed to test fileutils.ChownRecursiveFrom. We can't use bubblewrap for that because bubblewrap only creates UID mapping for one user, using chown with a different UID fails with: chown: changing ownership of 'file': Invalid argument

Do the same usermod does when changing a UID of a user: If the home directory is currently owned by the user, recursively change the owner and group of the home directory and all files in the home directory from the old UID and GID to the new UID and GID.

We need that for the SetUserID tests

We now support chown in bubblewrap, so we don't have to run the test as root anymore.

When executing `unshare --map-user` via exec.Command and connecting the process's stdout or stderr, the command hangs forever if unprivileged user namespaces are disabled. We avoid that by checking via `unshare --user` if unprivileged user namespaces are enabled.

The "Run autopkgtests" CI job runs the tests in an LXD container which doesn't allow using bubblewrap. It fails with: bwrap: Failed to make / slave: Permission denied To avoid that these jobs fail, we allow them to skip the bubblewrap tests. We still run the tests in the "Go Tests" CI jobs.

Running our tests with -v produces so much output that it makes it harder to inspect test failures, for example when viewing the logs of the "Run autopkgtests" CI job in GitHub. Running the tests without -v still prints the logs of the failed tests which should include all the information we need to debug test failures.

As suggested by reviewer. It's not implemented for now, warnings are always returned in English.

Produces prettier docs

So that it can be imported by the docgen tool we're about to add.

Copied from https://cobra.dev/docs/how-to-guides/clis-for-llms/

Indenting with four spaces formats the command as a code block in the generated markdown document.

Having the "This command requires root privileges." sentence after the `chown -R` command was confusing, it sounded like it was referring to that command instead of the authctl command.

To generate the CLI docs

The auto-generated Cobra markdown docs use headings starting at H2, not H1. That results in Sphinx printing warnings, which causes the build to fail in the CI (but not locally). Let's ignore these kind of warnings for now.

Co-authored-by: Shane Crowley <[email protected]>

Thanks to Shane for spotting that.

Via `go generate ./docs/...`

edibotopic

Great work! Nice to have this in the docs.

adombeck force-pushed the authctl-docs branch from 34c8cf5 to aed7e2a Compare January 6, 2026 12:39

adombeck force-pushed the authctl-docs branch from faaa81d to e865d20 Compare January 6, 2026 16:31

adombeck marked this pull request as ready for review January 6, 2026 16:34

adombeck requested a review from a team as a code owner January 6, 2026 16:34

adombeck requested a review from edibotopic January 6, 2026 16:34

edibotopic requested changes Jan 7, 2026

View reviewed changes

adombeck force-pushed the authctl-docs branch from 109d6d1 to e52807e Compare January 7, 2026 16:16

adombeck added 16 commits January 12, 2026 14:55

refactor: Split cmd/authctl/user/user_test.go

3a25dd7

Fix comment

beb98ae

There's nothing encrypted in this string.

Add gRPC method SetUserID

07ab3e3

Add authctl user set-uid command

da51e70

Return a gRPC error with code PermissionDenied

ade5c8e

... instead of prefixing the error message with "permission denied"

debian/authd.service.in: Grant capability CAP_DAC_READ_SEARCH

6f08095

Required to change the ownership of the user's home directory when changing the user's UID.

fileutils: Add ChownRecursiveFrom

aefcfe3

We use this to recursively change the owner and group of the user's home directory when changing the user's UID.

testutils: Add RunTestAsRoot

a6ded36

Needed to test fileutils.ChownRecursiveFrom. We can't use bubblewrap for that because bubblewrap only creates UID mapping for one user, using chown with a different UID fails with: chown: changing ownership of 'file': Invalid argument

Add TestChownRecursiveFrom

e8182c2

Add TestSetUIDCommand

bce17b1

Add db_test.TestSetUserID

55e00ff

Support creating users/groups in bubblewrap

bf7ac1a

We need that for the SetUserID tests

tests: Support chown in bubblewrap

66279be

tests: Run TestChownRecursiveFrom in bubblewrap

4a29f2d

We now support chown in bubblewrap, so we don't have to run the test as root anymore.

refactor: Remove unused parameter from runInBubbleWrap

1abdc6a

adombeck and others added 27 commits January 12, 2026 14:55

tests: Make chown work with bubblewrap executed via sudo

b42ae41

ci: Group log lines of llvm-symbolizer installation

e4e1c51

Check if user is busy before changing its UID

e7e9a58

authctl: Add argument completion

ea93e47

testlog: Fix duplicate newlines

75cc1ee

tests: Improve logging of bubblewrap commands

2fc22cf

tests: Improve logging when building authd and authctl

8a30e8e

tests: Improve logging of authctl tests

37253d1

authctl: Tell authd which language to return warnings in

d29de3e

As suggested by reviewer. It's not implemented for now, warnings are always returned in English.

authctl: Use cobra's Example field

b694e95

Produces prettier docs

authctl: Move root command to separate package

e217be7

So that it can be imported by the docgen tool we're about to add.

authctl: Add docgen tool

3355bb3

Copied from https://cobra.dev/docs/how-to-guides/clis-for-llms/

authctl: Format chown command as code block

f62f707

Indenting with four spaces formats the command as a code block in the generated markdown document.

authctl: Improve set-uid and set-gid description

25f3251

Having the "This command requires root privileges." sentence after the `chown -R` command was confusing, it sounded like it was referring to that command instead of the authctl command.

authctl: Disable "auto generated by cobra" line

ca60147

authctl: Add "long" descriptions for lock and unlock commands

a114830

docs: Add generate.go

1d57531

To generate the CLI docs

docs: Add "authctl" to wordlist

aaded91

docs: Suppress warnings relating to headers

eeae34b

The auto-generated Cobra markdown docs use headings starting at H2, not H1. That results in Sphinx printing warnings, which causes the build to fail in the CI (but not locally). Let's ignore these kind of warnings for now.

Update cmd/authctl/user/set-uid.go

08f6ba3

Co-authored-by: Shane Crowley <[email protected]>

Update cmd/authctl/group/set-gid.go

60a8136

Co-authored-by: Shane Crowley <[email protected]>

authctl: Fix grammar of lock/unlock command description

0d2cd4b

Thanks to Shane for spotting that.

docs: Generate CLI docs

63cd457

Via `go generate ./docs/...`

docs: Link to CLI docs on reference page

62920d5

adombeck force-pushed the authctl-docs branch from e52807e to 62920d5 Compare January 12, 2026 14:03

adombeck requested a review from edibotopic January 12, 2026 14:08

edibotopic approved these changes Jan 12, 2026

View reviewed changes

Add authctl docs #1179

Are you sure you want to change the base?

Add authctl docs #1179

Uh oh!

Conversation

adombeck commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Jan 6, 2026

Uh oh!

edibotopic commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adombeck commented Jan 6, 2026

Uh oh!

edibotopic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

edibotopic Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

adombeck Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edibotopic Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

adombeck Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edibotopic Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

adombeck Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

edibotopic Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

edibotopic Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

edibotopic Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

adombeck commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

edibotopic commented Jan 7, 2026

Uh oh!

edibotopic left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adombeck commented Jan 5, 2026 •

edited

Loading

adombeck commented Jan 6, 2026 •

edited

Loading

edibotopic commented Jan 6, 2026 •

edited

Loading

adombeck commented Jan 6, 2026 •

edited

Loading

adombeck Jan 7, 2026 •

edited

Loading

adombeck Jan 7, 2026 •

edited

Loading

edibotopic Jan 12, 2026 •

edited

Loading

adombeck commented Jan 7, 2026 •

edited

Loading