3.7 Configuration: revise the discussion of pam_xdg and pam_dumb_runtime_dir

crux-wiki/Handbook3-7-Configuration

@@ -83,7 +83,7 @@ argument '''stop'''.
 !!! [[#LocaleGeneration]] Generating locales
 Starting with CRUX 2.5, glibc does not contain all possible locales anymore,
 thus you'll have to generate the locales you need/use. To ensure proper
-operation of %fn%pkgmk%%, the locale C.UTF-8 is generated as part of the CRUX
+operation of '''pkgmk''', the locale C.UTF-8 is generated as part of the CRUX
 installation. Any other desired locales must be created by the administrator. A
 typical setup for swedish users would use the following commands, so replace
 @@sv_SE*@@ with the locale you want:
@@ -219,21 +219,22 @@ To associate with a WPA2-protected wireless network, you should first create a
 configuration file for %fn%wpa_supplicant%% to use, then launch wpa_supplicant
 on that interface.
 
- $ wpa-passphrase MYNETWORK MYPASSWORD > /etc/wpa_supplicant-wlan0.conf
+ $ wpa-passphrase MYNETWORK MYPASS > /etc/wpa_supplicant-wlan0.conf
  $ wpa_supplicant -i wlan0 -c /etc/wpa_supplicant-wlan0.conf
 
--> Replace '''wlan0''' with the name of your actual network interface. Run
-%fn%ip link%% to see the list of all available interfaces.
+-> Replace '''MYNETWORK''' with the ssid of your network, '''MYPASS''' with its
+passphrase, and '''wlan0''' with the name of your actual network interface. Run
+@@ip link@@ to see the list of all available interfaces.
 
 If the %fn%wpa_supplicant%% output indicates a successful authentication, you
-can background the process and run %fn%dhcpcd wlan0%% to request an address from
+can background the process and run @@dhcpcd wlan0@@ to request an address from
 the DHCP server.
 
 The '''wpa_supplicant''' package provides two startup scripts in
 %fn%/etc/rc.d%%. You might choose to put '''wlan''' in the SERVICES array of
-%fn%/etc/rc.conf%% (replacing '''net'''), which will let %fn%wpa_supplicant%%
+%fn%/etc/rc.conf%% (replacing '''net'''), which will let '''wpa_supplicant'''
 manage all your network interfaces. Another option is to let the '''net'''
-startup script call %fn%wpa_supplicant%% as needed, by copying into
+startup script call '''wpa_supplicant''' as needed, by copying into
 %fn%/lib/dhcpcd/dhcpcd-hooks/%% the example file
 %fn%/usr/share/dhcpcd/hooks/10-wpa_supplicant%%.
 
@@ -251,14 +252,14 @@ and understands DES passwords as well).
 Also configurable in %fn%/etc/login.defs%% are the settings that govern how
 @@useradd(8)@@ behaves when you create a new non-root user, such as CREATE_HOME
 and USERGROUPS_ENAB. First-time CRUX administrators might be surprised to learn
-that creating a new user via %fn%useradd -m%% will not automatically populate
+that creating a new user via @@useradd -m@@ will not automatically populate
 the home directory with a basic shell startup file, as happens on other Linux
 distributions whose %fn%/etc/skel/%% contains their idea of an initial home
 directory. No such decisions are imposed on CRUX administrators, who get to work
 with the upstream tools in their unmodified state.
 
 The core packages '''linux-pam''' and '''dumb_runtime_dir''', and the contrib
-package '''pam_xdg''', provide a number of modules that can be loaded upon
+package '''pam_xdg''', provide a variety of modules that can be loaded upon
 logging in. The files in %fn%/etc/pam.d%% govern the association between
 the type of login (eg., tty, SSH, su, X Display Manager) and the modules that
 get loaded (eg., pam_env, pam_exec, pam_limits). Some typical situations that
@@ -266,14 +267,29 @@ can be handled cleanly with PAM modules are listed in the table below.
 
 ||cellpadding="3" rules="all" frame="box"
 ||! file in /etc/pam.d ||! Typical usage
+||%fn%pam_dumb_runtime_dir.so%% || create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification
 ||%fn%pam_env.so%% || export some common environment variables, no matter what login shell the user has chosen
+||%fn%pam_xdg.so%% || export the XDG environment variables defined in the freedesktop.org specification
 ||%fn%pam_limits.so%% || increase the allowed number of opened files, to ensure proper operation of some games
 ||%fn%pam_xauth.so%% || grant another user access to the X display of the logged-in user, so that programs invoked with ''su'' can work properly
 ||%fn%pam_mount.so%% || automatically mount a LUKS-encrypted home partition after successful authentication
-||%fn%pam_dumb_runtime_dir.so%% || create an XDG_RUNTIME_DIR for applications that conform to the freedesktop.org specification
-||%fn%pam_xdg.so%% || export the XDG environment variables defined in the freedesktop.org specification
 
-If you find yourself in one of the situations in the table above, read the man
+->%lfloat% http://crux.nu/doc/images/note.png
+'''Note'''[[]]
+-> The existence of a writable XDG_RUNTIME_DIR is required for proper operation of
+many desktop applications. A ''clean'' CRUX 3.7 installation will place a line
+in %fn%/etc/pam.d/common-session%% that loads the module fn%pam_dumb_runtime_dir.so%%
+to satisfy this requirement. An ''upgrade'' to CRUX 3.7 might not do so,
+depending on your UPGRADE directives in %%fn%/etc/pkgadd.conf%%. But any
+configuration that allows desktop applications to run smoothly on CRUX 3.6 will
+probably continue working after an upgrade to 3.7.
+-> While '''pam_dumb_runtime_dir''' has a simple design and restricts itself to
+the creation of the runtime dir, the 'contrib' collection offers an alternative,
+'''pam_xdg''', which exports all the environment variables defined in the
+freedesktop.org specification. You should choose ONE of these two options and
+edit %fn%/etc/pam.d/common-session%% accordingly.
+
+If you find yourself in one of the other situations in the table above, read the man
 page for the corresponding PAM module to learn how to accomplish the desired
 configuration.