Add example configuration documentation.

 * And also install example pkcs11.conf file.

5 files changed, 68 insertions, 3 deletions

diff --git a/.gitignore b/.gitignore
index cb01fcb..f4e65d0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -60,6 +60,7 @@ temp.txt
 
 /p11-kit/p11-kit.pc
 /p11-kit/p11-kit-1.pc
+/p11-kit/pkcs11.conf.example
 
 /po/POTFILES
 /po/stamp-po
diff --git a/configure.ac b/configure.ac
index 45330f4..9900258 100644
--- a/configure.ac
+++ b/configure.ac
@@ -60,8 +60,9 @@ AC_ARG_WITH([pkcs11-dir],
             [pkcs11_dir=$sysconfdir/pkcs11])
 
 # We expand these so we have concrete paths
-p11_system_conf=$(eval echo $pkcs11_dir/pkcs11.conf)
-p11_system_modules=$(eval echo $pkcs11_dir/modules)
+p11_system_dir=$(eval echo $pkcs11_dir)
+p11_system_conf=$(eval echo $p11_system_dir/pkcs11.conf)
+p11_system_modules=$(eval echo $p11_system_dir/modules)
 p11_user_conf="~/.pkcs11/pkcs11.conf"
 p11_user_modules="~/.pkcs11/modules"
 
@@ -70,6 +71,7 @@ AC_DEFINE_UNQUOTED(P11_SYSTEM_MODULES, "$p11_system_modules", [System modules di
 AC_DEFINE_UNQUOTED(P11_USER_CONF, "$p11_user_conf", [User configuration file])
 AC_DEFINE_UNQUOTED(P11_USER_MODULES, "$p11_user_modules", [User modules dir])
 
+AC_SUBST(p11_system_dir)
 AC_SUBST(p11_system_conf)
 AC_SUBST(p11_system_modules)
 AC_SUBST(p11_user_conf)
@@ -178,6 +180,7 @@ AC_CONFIG_FILES([Makefile
 	po/Makefile.in
 	p11-kit/Makefile
 	p11-kit/p11-kit-1.pc
+	p11-kit/pkcs11.conf.example
 	tests/Makefile
 	tools/Makefile
 ])
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index f12f274..89ba7e7 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -20,6 +20,54 @@
 		</para>
 	</section>
 
+	<section id="config-example">
+		<title>Example</title>
+
+		<para>The following sections describe the config format in detail. But first
+		an example which shows the various features. The configuration below, loads
+		two modules called 'my-module' and 'nss'. The user settings override some
+		aspects of the system settings.</para>
+
+<para>Global configuration file: <literal>/etc/pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This setting controls whether to load user configuration from the
+# ~/.pkcs11 directory. Possible values:
+#    none: No user configuration (default)
+#    merge: Merge the user configuration over the system configuration
+#    only: Only user configuration, ignore system configuration
+user-config: merge
+</programlisting>
+
+<para>One module configuration file per module: <literal>/etc/pkcs11/modules/my-module</literal></para>
+<programlisting>
+# This setting controls the actual module library to load. This config file might
+# be installed by the package that installs this module library.
+module: /usr/lib/my-pkcs11-module.so
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This is an empty file. Files that do not exist are treated as empty.
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/my-module</literal></para>
+<programlisting>
+# Merge with the settings in the system my-module config file. In this case
+# a developer has overridden to load a different module for my-module instead.
+module: /home/user/src/custom-module/my-module.so
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/nss</literal></para>
+<programlisting>
+# Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass
+# some custom non-standard initialization arguments, as NSS expects.
+module: /usr/lib/libsoftokn3.so
+x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db'
+</programlisting>
+
+
+</section>
+
 	<section id="config-format">
 		<title>File format</title>
 
diff --git a/p11-kit/Makefile.am b/p11-kit/Makefile.am
index da06ebd..9d28b5e 100644
--- a/p11-kit/Makefile.am
+++ b/p11-kit/Makefile.am
@@ -46,8 +46,12 @@ libp11_kit_testable_la_SOURCES = $(MODULE_SRCS)
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = p11-kit-1.pc
 
+exampledir = $(p11_system_dir)
+example_DATA = pkcs11.conf.example
+
 EXTRA_DIST = \
-	p11-kit-1.pc.in
+	p11-kit-1.pc.in \
+	pkcs11.conf.example.in
 
 # Proxy module is actually same as library, so install a link
 install-exec-hook:
diff --git a/p11-kit/pkcs11.conf.example.in b/p11-kit/pkcs11.conf.example.in
new file mode 100644
index 0000000..bfc2cb3
--- /dev/null
+++ b/p11-kit/pkcs11.conf.example.in
@@ -0,0 +1,9 @@
+# This is an example @p11_system_conf@ file. Copy it into
+# place before use.
+
+# This setting controls whether to load user configuration from the
+# ~/.pkcs11 directory. Possible values:
+#    none: No user configuration (default)
+#    merge: Merge the user configuration over the system configuration
+#    only: Only user configuration, ignore system configuration
+user-config: merge