1 files changed, 29 insertions, 9 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 9fb5cff06d..1b77881eb6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4456,17 +4456,18 @@ that will be added to the environment directly.
 
 @item --pure
 Unset existing environment variables when building the new environment, except
-those specified with @option{--inherit} (see below.)  This has the effect of
+those specified with @option{--preserve} (see below.)  This has the effect of
 creating an environment in which search paths only contain package inputs.
 
-@item --inherit=@var{regexp}
-When used alongside @option{--pure}, inherit all the environment variables
+@item --preserve=@var{regexp}
+@itemx -E @var{regexp}
+When used alongside @option{--pure}, preserve the environment variables
 matching @var{regexp}---in other words, put them on a ``white list'' of
 environment variables that must be preserved.  This option can be repeated
 several times.
 
 @example
-guix environment --pure --inherit=^SLURM --ad-hoc openmpi @dots{} \
+guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
   -- mpirun @dots{}
 @end example
 
@@ -10695,6 +10696,7 @@ account.  System accounts are sometimes treated specially; for instance,
 graphical login managers do not list them.
 
 @anchor{user-account-password}
+@cindex password, for user accounts
 @item @code{password} (default: @code{#f})
 You would normally leave this field to @code{#f}, initialize user
 passwords as @code{root} with the @command{passwd} command, and then let
@@ -10702,11 +10704,29 @@ users change it with @command{passwd}.  Passwords set with
 @command{passwd} are of course preserved across reboot and
 reconfiguration.
 
-If you @emph{do} want to have a preset password for an account, then
-this field must contain the encrypted password, as a string.
-@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
-on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
-Manual}, for information on Guile's @code{crypt} procedure.
+If you @emph{do} want to set an initial password for an account, then
+this field must contain the encrypted password, as a string.  You can use the
+@code{crypt} procedure for this purpose:
+
+@example
+(user-account
+  (name "charlie")
+  (home-directory "/home/charlie")
+  (group "users")
+
+  ;; Specify a SHA-512-hashed initial password.
+  (password (crypt "InitialPassword!" "$6$abc")))
+@end example
+
+@quotation Note
+The hash of this initial password will be available in a file in
+@file{/gnu/store}, readable by all the users, so this method must be used with
+care.
+@end quotation
+
+@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
+more information on password encryption, and @ref{Encryption,,, guile, GNU
+Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
 
 @end table
 @end deftp