cheatsheets: hints for .profile

diff --git a/cheatsheet-bash.txt b/cheatsheet-bash.txt
index 47e539d9d781097dfebbd9a100674b160585e6e0..e1447519fd48a4b3d77402aa56cd872e58737e3d 100644 (file)
--- a/cheatsheet-bash.txt
+++ b/cheatsheet-bash.txt
@@ -59,3 +59,89 @@ ctrl+p
     Scroll forward through next entry in command history for the current session
 ctrl+r
     Reverse search through history (type parts of the command to initiate query).
+
+
+2025-09-04-openrc-user-services
+  Title                     sys-apps/openrc user services introduction
+  Author                    Sam James <sam@gentoo.org>
+  Posted                    2025-09-04
+  Revision                  1
+
+OpenRC 0.62 (*) introduces user services as a new feature. The functionality
+is documented on the wiki [0] and has a similar interface to conventional
+system-wide services.
+
+Support for user services is enabled by default via the pam_openrc module
+in sys-auth/pambase, but it can be disabled via an OpenRC configuration
+option as described below.
+
+Some ebuilds already provide OpenRC user service init scripts, like
+app-editors/emacs. More will follow, but use of user services is optional.
+
+Requirements
+============
+
+User services currently require the XDG_RUNTIME_DIR environment variable to
+be set, which may be done via sys-auth/elogind, sys-apps/systemd, or manually
+via e.g. pam_env. In the future, pam_xdg may be packaged [1] as another option.
+
+If the XDG_RUNTIME_DIR environment variable isn't set and user services have
+not been disabled, the setup will fail gracefully but will appear in syslog
+and rc-update.
+
+Opting-out of user services
+===========================
+
+If users wish to disable OpenRC user services, they can set
+rc_autostart_user="NO" in /etc/rc.conf:
+
+ ...
+ # Set to "NO" if you don't want pam_openrc autostarting user services. This
+ # effectively disables the pam module, without the need of removing it from
+ # the pam configuration files.
+ rc_autostart_user="NO"
+ ...
+
+~/.profile and friends
+======================
+
+After stabilization, some users reported hangs when logging in [2]. None
+were reported during the extensive period of testing in ~arch or by other
+distributions who deployed newer versions of OpenRC. User services require
+that ~/.profile, ~/.bash_profile run safely under a non-interactive
+shell.
+
+Commands in these shell startup files may be executed by a non-interactive
+shell so commands that require a TTY, reading from stdin, and so on should
+be guarded with a check for TTY like:
+
+ if [ -t 0 ] ; then
+     # Interactive commands here
+     ...
+ fi
+
+Please make sure to check your shell startup files for suspicious constructs
+like the following:
+
+ ...
+ if [ -x /usr/bin/keychain ] ; then # BAD
+     keychain ...
+ fi
+ ...
+
+... replacing them with:
+
+ ...
+ if [ -t 0 ] && [ -x /usr/bin/keychain ] ; then # GOOD
+     keychain ...
+ fi
+ ...
+
+(*) User services were originally in sys-apps/openrc-navi and later as
+    part of >= OpenRC 0.62. The functionality was declared stable with 0.62.6
+    which was the first version with User Services stabled in Gentoo.
+
+[0] https://wiki.gentoo.org/wiki/OpenRC#User_services
+[1] https://bugs.gentoo.org/908431
+[2] https://bugs.gentoo.org/962214
+