ssh & systemd: hint at file embedding instead of inlining

[Okeanos]

With butane 0.18.0 and the correct variants and versions file embedding of SSH keys and systemd (dropins) is possible.

Fixes #511

---

First stab at this. I am not entirely happy about the systemd situation. There is no clear & good place that I could identify where to provide good details (vs. the dedicated authentication document for SSH) besides a tutorial or two dedicated to a particular thing (instead of the overall options). This strikes me as something that could be generally improved. Thoughts?

[travier]

Could you split this PR in two, one with all the styling / grammar fixes so that we can merge it right away and this one with the file inclusion specific change to discuss it?

I think we should convert most examples from the tutorial to use the new format.

[Okeanos]

I can absolutely do that. Wanted to go over the PR again anyway.

[Okeanos]

I'll update this PR once #523 is through.

[Okeanos]

Currently doing some rebasing and proofreading.

I stumbled across the following in the SSH key locations section within the FCOS Documentation:

Key files are read in alphabetical order, ignoring dotfiles. The standard ~/.ssh/authorized_keys file is read afterward, in the usual way.

However, the OpenSSH documentation on AuthorizedKeysCommand (which is used by ssh-key-dir) states:

AuthorizedKeysCommand is tried after the usual AuthorizedKeysFile files and will not be executed if a matching key is found there.

There appears to be some mistake or am I looking at the wrong OpenSSH documentation? However, this is the manual that can be retrieved via Fedora Docs --> OpenSSH Project --> Manuals --> SSHD Config.

---

I also noticed a couple of additional typos I missed in #523 – I'll include them here for now and possibly split them out again into another separate PR after clarifying above point and any other changes you want.

[bgilbert]

Apparently the key evaluation order was changed and subsequently documented in the OpenSSH release on 2020-05-27. I originally wrote that text on 2020-06-29 (#95), and my sshd(8) man page at the time would have still been the old one.

Please go ahead and correct the docs. Great catch!

[Okeanos]

Fixed that finding.

Before proceeding further I have another conceptual question … apparently this PR is the first to require the --files-dir syntax within the docs and the current ci/check.py script invoking the container version of butane is not handling that yet:

• the parameter is not specified
• no mounted volume is declared to push the files into the container with
• there is no immediately obvious location where to place dummy files (similar to what happens in butane/test) within the docs repo

Any thoughts?

[bgilbert]

I think it makes sense to extend ci/check.py as you've suggested. If we want to commit the files-dir files directly to Git, a subdirectory within ci would make sense. If we want to create them on the fly as Butane's test does, check.py should probably just create a tempfile.TemporaryDirectory().

The more ambitious approach is for check.py to parse the Butane YAML to figure out which files to create, but I don't think that's strictly necessary.

[dustymabe]

just scanned this, the docs changes LGTM

[bgilbert]

Please squash your commits together.

[travier]

Thanks @Okeanos !