Add example configuration documentation.

 * And also install example pkcs11.conf file.

diff --git a/.gitignore b/.gitignore
index cb01fcb3bd88b1aca9a2f0546faad5a1b41e6171..f4e65d0a36066c38e385f64bd4b3705936aa5ac4 100644 (file)
--- 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 45330f4b42443f80a2902269db347eef568cd12e..99002588c5741e0962e9fcbe9fce8bc8bb2a8422 100644 (file)
--- 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 f12f274e868b3f5b413ad1a121e7130bf55d6a92..89ba7e7619fbfbefe8ef02dfe7112aacff8e27d3 100644 (file)
--- 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 da06ebdd277268cb36be6838c3884915cd1d2ff3..9d28b5e85f18376890d1f562464b817e648029ad 100644 (file)
--- 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 (file)
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