journald: add examples to show user journal logs

docs/provisioning/config-transpiler/examples.md

@@ -172,6 +172,11 @@ This example creates a new systemd unit called hello.service, enables it so it w
 ```yaml
 variant: flatcar
 version: 1.0.0
+passwd:
+  users:
+    - name: flatcar
+      groups:
+        - systemd-journal
 storage:
   directories:
     - path: /etc/systemd/user/default.target.wants
@@ -198,6 +203,8 @@ storage:
 
 This example creates a new systemd user unit called `hello.service`, enables it with an explicit symlink (workaround for Ignition) so it will run on boot, and defines the contents to simply echo `"Hello, World!"`.
 
+_Note_: Adding a regular user like "flatcar" to the `systemd-journal` group can be useful if you want to access the journal logs with `journalctl --user --unit hello.service`. You can already access logs with `journactl --user-unit hello.service` from the default `core` user.
+
 ## networkd units
 
 ```yaml

docs/setup/customization/adding-users.md

@@ -7,13 +7,15 @@ aliases:
     - ../../clusters/customization/adding-users
 ---
 
-You can create user accounts on a Flatcar Container Linux machine manually with `useradd` or via a [Container Linux Config][cl-config] when the machine is created.
+You can create user accounts on a Flatcar Container Linux machine manually with `useradd` or via a [Butane Config][butane-config] when the machine is created.
 
-## Add Users via Container Linux Configs
+## Add Users via Butane Configs
 
-In your Container Linux Config, you can specify many [different parameters][config-spec] for each user. Here's an example:
+In your Butane Config, you can specify many [different parameters][config-spec] for each user. Here's an example:
 
 ```yaml
+variant: flatcar
+version: 1.0.0
 passwd:
   users:
     - name: core
@@ -26,6 +28,27 @@ passwd:
       groups: [ sudo, docker ]
 ```
 
+Because `usermod` does not work to add a user to a predefined system group, you can use [systemd-userdb][systemd-userdb] to define membership. Here's the same example with userdb:
+
+```
+variant: flatcar
+version: 1.0.0
+passwd:
+  users:
+    - name: elroy
+      password_hash: "$6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm..."
+      ssh_authorized_keys:
+        - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDGdByTgSVHq......."
+storage:
+  files:
+    - path: /etc/userdb/elroy:sudo.membership
+      contents:
+        inline: " "
+    - path: /etc/userdb/elroy:docker.membership
+      contents:
+        inline: " "
+```
+
 ## Add user manually
 
 If you'd like to add a user manually, SSH to the machine and use the `useradd` tool. To create the user `user`, run:
@@ -74,5 +97,6 @@ $ sudo cat /etc/sudoers.d/user1
 user1 ALL=(ALL) NOPASSWD: ALL
 ```
 
-[cl-config]: ../../provisioning/cl-config
+[cl-config]: ../../provisioning/config-transpiler
 [config-spec]: ../../provisioning/config-transpiler/configuration
+[systemd-userdb]: https://www.freedesktop.org/software/systemd/man/systemd-userdbd.service.html

docs/setup/debug/reading-the-system-log.md

@@ -38,6 +38,21 @@ Dec 22 12:32:39 localhost docker[9772]: /usr/sbin/apache2ctl: 87: ulimit: error
 Dec 22 12:32:39 localhost docker[9772]: apache2: Could not reliably determine the server's fully qualified domain name, using 172.17.0.6 for ServerName
 ```
 
+## Read the user journal from the current user
+
+It might be required to add a user different from `core` user to the `systemd-journal` group to read the user journal. It can be done with this Butane config:
+```yaml
+variant: flatcar
+version: 1.0.0
+passwd:
+  users:
+    - name: flatcar
+      groups:
+        - systemd-journal
+```
+
+Then from `flatcar` login: `journalctl --user`.
+
 ## Read entries since boot
 
 Reading just the entries since the last boot is an easy way to troubleshoot services that are failing to start properly: