From 11f3f0effb14be788e320d2f75b0d2d769058966 Mon Sep 17 00:00:00 2001
From: Stef Walter <stefw@collabora.co.uk>
Date: Wed, 14 Sep 2011 13:45:03 +0200
Subject: Add documentation about the configuration paths
* Default module path
* How to lookup paths using pkg-config
---
doc/p11-kit-config.xml | 37 ++++++++++++++++++++++---------------
doc/p11-kit-docs.sgml | 1 +
doc/p11-kit-notes.xml | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/p11-kit.xml | 3 +++
doc/style.css | 2 ++
5 files changed, 76 insertions(+), 15 deletions(-)
create mode 100644 doc/p11-kit-notes.xml
(limited to 'doc')
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index 76b3fa2..7c28f86 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -40,9 +40,11 @@ user-config: merge
<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
+# This setting controls the actual module library to load. This config file
+# might be installed by the package that installs this module library. This
+# is not an absolute path name. Relative path names are loaded from the
+# $(libdir)/pkcs11 directory by default.
+module: my-pkcs11-module.so
# This controls whether the module is required to successfully initialize. If 'yes', then
# a failure to load or initialize this module will result in a p11-kit system failure.
@@ -110,20 +112,22 @@ critical: yes
<section id="config-module">
<title>Module Configuration</title>
- <para>Each configured PKCS#11 module has its own config file. The
- location(s) of these files are described below. Most importantly each
- config file specifies the location of the PKCS#11 module to load. Each
- module config file has the following fields:</para>
+ <para>Each configured PKCS#11 module has its own config file. These files
+ can be <link linkend="config-locations">placed in various locations</link>.
+ Most importantly each config file specifies the path of the PKCS#11 module to
+ load. A module config file has the following fields:</para>
<variablelist>
<varlistentry>
<term>module:</term>
<listitem>
- <para>The absolute path to the PKCS#11 module to load.
+ <para>The filename of the PKCS#11 module to load.
This should include an extension like <literal>.so</literal></para>
<para>If this value is blank, then the module will be ignored.
This can be used in the user configs to override loading of a module
specified in the system configuration.</para>
+ <para>If this is a relative path, then the module will be loaded
+ from the <link linkend="notes-paths-modules">default module directory</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -174,16 +178,19 @@ critical: yes
files and a file for global configuration. Optionally each user can provide
additional configuration or override the system configuration.</para>
- <para>The system global configuration file is in
+ <para>The system global configuration file is usually in
<literal>/etc/pkcs11/pkcs11.conf</literal> and the user global
configuration file is in <literal>~/.pkcs11/pkcs11.conf</literal> in the
user's home directory.</para>
- <para>
- The module config files are located in the
- <literal>/etc/pkcs11/modules</literal> directory, with one configuration
- file per module. In addition the <literal>~/.pkcs11/modules</literal>
- directory can be used for modules installed by the user.
- </para>
+ <para>The module config files are usually located in the
+ <literal>/etc/pkcs11/modules</literal> directory, with one configuration
+ file per module. In addition the <literal>~/.pkcs11/modules</literal> directory
+ can be used for modules installed by the user.</para>
+
+ <para>The default system config file and module directory can be changed
+ when building p11-kit. Always
+ <link linkend="notes-paths">lookup these paths</link> using
+ <literal>pkg-config</literal>.</para>
</section>
</chapter>
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 1bfb571..8e8c933 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -13,6 +13,7 @@
<xi:include href="p11-kit-config.xml"/>
<xi:include href="p11-kit-sharing.xml"/>
+ <xi:include href="p11-kit-notes.xml"/>
<chapter xml:id="reference">
<title>Reference</title>
diff --git a/doc/p11-kit-notes.xml b/doc/p11-kit-notes.xml
new file mode 100644
index 0000000..e030824
--- /dev/null
+++ b/doc/p11-kit-notes.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="config">
+ <title>Developer and Packager Notes</title>
+
+ <section id="notes-paths">
+ <title>Using pkg-config to determine paths</title>
+
+ <para>Developers or packagers of PKCS#11 modules need to install various
+ files into specific locations so that p11-kit will recognize and load the
+ module correctly.</para>
+
+ <para>You should use <literal>pkg-config</literal> as described below
+ to determine configuration paths. p11-kit installs a
+ <literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>.
+ This file contains all the information about the various paths that p11-kit
+ looks for files at.</para>
+
+ <section id="notes-paths-config">
+ <title>Path to place module configuration</title>
+
+ <para>As described in the <link linkend="config-module">module configuration</link>
+ documentation, each PKCS#11 module should install a config file describing
+ that module. These config files should be installed to a specific directory which
+ can be determined by running:</para>
+
+ <programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_system_config_modules</command>
+/etc/pkcs11/modules</programlisting>
+ </section>
+
+ <section id="notes-paths-modules">
+ <title>Default path for modules with relative paths</title>
+
+ <para>If a <link linkend="config-module">module configuration</link>
+ contains a relative path in its <literal>module:</literal> setting,
+ then that module will be loaded from the default module path. This
+ path can be determined by running:</para>
+
+ <programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_module_path</command>
+/usr/lib64/pkcs11</programlisting>
+ </section>
+
+ </section>
+
+</chapter>
diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml
index a040da8..3c8a318 100644
--- a/doc/p11-kit.xml
+++ b/doc/p11-kit.xml
@@ -33,5 +33,8 @@
<xi:include href="p11-kit-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:fallback/>
</xi:include>
+ <xi:include href="p11-kit-notes.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:fallback/>
+ </xi:include>
</article>
diff --git a/doc/style.css b/doc/style.css
index 67ffff3..a4aa19e 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -79,5 +79,7 @@ H2 {
}
H3 {
+ position: relative;
+ left: -1em;
font-weight: normal !important;
}
--
cgit v1.1