Updated documentation.

1 files changed, 50 insertions, 5 deletions

diff --git a/cups-programme.conf b/cups-programme.conf
index a7f33d3357bc..ceb277b41b04 100644
--- a/cups-programme.conf
+++ b/cups-programme.conf
@@ -1,15 +1,60 @@
 ### Warning: This file will be bash-sourced. Beware.
 
+# su_variant:
+# 
 # Controls which programme is selected to use to run a command as
 # another user.
-# Do not but arbitrary executables or full path's here; the value of
-# this variable will not directly be executed, but it will be parsed to
-# internally decide what to do.
-# Supported values:
-#  'su', 'sudo', 'sudo-askpass' (sudo with askpass helper), 'kdesu', 'kdesudo'.
+# 
+# When the print backend is run, there is no terminal input, so no
+# password can be entered easily.
+# 
+# So you need to either configure sudo such that you do not need a
+# password and use a sudo-based su_variant, or select a su_variant which
+# gives a graphical password prompt.
+# 
+# 'su' is most probably only usefull if no password will be asked for
+# in general, e.g. when CUPS is running it's backends as root.
+# 
+# Possible values for su_variant are:
+# - 'su' -- uses 'su', also allows to change the group. Not graphical,
+#   so only useful if no password is required in the first place.
+# - 'sudo' -- uses 'sudo', also allows to change the group. Not
+#   graphical, so only useful if no password is required. sudo can be
+#   configured to allow specific commands as specific users without
+#   password (e.g. in /etc/sudoers, /etc/sudoers.d).
+# - 'sudo-askpass' -- uses 'sudo' with an external command to ask for
+#   the password. Also allows to change the group. The external askpass
+#   command needs to be specified in $askpass_cmd. May be a graphical
+#   programme.
+# - 'kdesu' -- uses 'kdesu', does not allow to change the group.
+#   Graphical.
+# - 'kdesudo' -- uses 'kdesudo', does not allow to change the group.
+#   Graphical.
+# 
+# Note that changing the group is in all cases only possible if CUPS
+# runs the printing backend as root, which most probably is not the
+# case.
+
 su_variant=sudo-askpass
 # su_variant=kdesu
 
+
+# askpass_cmd:
+# 
 # askpass programme to use when $su_variant is set to 'sudo-askpass'.
+# 
+# On Arch Linux, there are for example:
+# - '/usr/lib/ssh/x11-ssh-askpass', provided by the package
+#   'x11-ssh-askpass',
+# - '/usr/bin/lxqt-openssh-askpass', provided by the package
+#   'lxqt-openssh-askpass',
+# - '/usr/bin/qt4-ssh-askpass', provided by the package
+#   'openssh-askpass',
+# - '/usr/bin/ksshaskpass', provided by the package 'ksshaskpass', 
+# - '/usr/lib/seahorse/ssh-askpass', provided by the package 'seahorse'.
+
 askpass_cmd=/usr/lib/ssh/x11-ssh-askpass
 # askpass_cmd=/usr/bin/lxqt-openssh-askpass
+# askpass_cmd=/usr/bin/ksshaskpass
+# askpass_cmd=/usr/bin/qt4-ssh-askpass
+# askpass_cmd=/usr/lib/seahorse/ssh-askpass