From 45768d10e3abd513b4c959efeb5907798f2fac3f Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Wed, 17 Nov 2010 20:46:19 -0500
Subject: [PATCH] Document the dummy_seclabel contrib module.

KaiGai Kohei, with editing and markup fixes by me.
---
 doc/src/sgml/contrib.sgml        |  1 +
 doc/src/sgml/dummy-seclabel.sgml | 75 ++++++++++++++++++++++++++++++++++++++++
 doc/src/sgml/filelist.sgml       |  1 +
 3 files changed, 77 insertions(+)
 create mode 100644 doc/src/sgml/dummy-seclabel.sgml

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index c31041614b..9057996014 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -90,6 +90,7 @@ psql -d dbname -f <replaceable>SHAREDIR</>/contrib/<replaceable>module</>.sql
  &dblink;
  &dict-int;
  &dict-xsyn;
+ &dummy-seclabel;
  &earthdistance;
  &fuzzystrmatch;
  &hstore;
diff --git a/doc/src/sgml/dummy-seclabel.sgml b/doc/src/sgml/dummy-seclabel.sgml
new file mode 100644
index 0000000000..5b5089c201
--- /dev/null
+++ b/doc/src/sgml/dummy-seclabel.sgml
@@ -0,0 +1,75 @@
+<!-- doc/src/sgml/dummy_seclabel.sgml -->
+
+<sect1 id="dummy-seclabel">
+ <title>dummy_seclabel</title>
+
+ <indexterm zone="dummy-seclabel">
+  <primary>dummy_seclabel</primary>
+ </indexterm>
+
+ <para>
+  The <filename>dummy_seclabel</> module exists only to support regression
+  testing of the <command>SECURITY LABEL</> statement.  It is not intended
+  to be used in production.
+ </para>
+
+ <sect2>
+  <title>Rationale</title>
+
+  <para>
+   The <command>SECURITY LABEL</> statement allows the user to assign security
+   labels to database objects; however, security labels can only be assigned
+   when specifically allowed by a loadable module, so this module is provided
+   to allow proper regression testing.
+  </para>
+
+  <para>
+   Security label providers intended to be used in production will typically be
+   dependent on a platform-specific feature such as
+   <productname>SE-Linux</productname>.  This module is platform-independent,
+   and therefore better-suited to regression testing.
+  </para>
+ </sect2>
+
+ <sect2>
+  <title>Usage</title>
+
+  <para>
+   Here's a simple example of usage:
+  </para>
+
+<programlisting>
+# postgresql.conf
+shared_preload_libraries = 'dummy_label'
+</programlisting>
+
+<programlisting>
+postgres=# CREATE TABLE t (a int, b text);
+CREATE TABLE
+postgres=# SECURITY LABEL ON TABLE t IS 'classified';
+SECURITY LABEL
+</programlisting>
+
+  <para>
+   The <filename>dummy_seclabel</> provides only four hardcoded
+   labels: <literal>unclassified</>, <literal>classified</>,
+   <literal>secret</>, <literal>top secret</> and <literal>trusted</>.
+
+   It does not allow any other strings as security labels.
+  </para>
+  <para>
+   These labels are not used to enforce access controls.  They are only used
+   to check whether the <command>SECURITY LABEL</> statement works as expected,
+   or not.
+  </para>
+ </sect2>
+
+ <sect2>
+  <title>Author</title>
+
+  <para>
+   KaiGai Kohei <email>kaigai@ak.jp.nec.com</email>
+  </para>
+ </sect2>
+
+</sect1>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 9b1de856b0..39cfcee961 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -102,6 +102,7 @@
 <!entity dblink          SYSTEM "dblink.sgml">
 <!entity dict-int        SYSTEM "dict-int.sgml">
 <!entity dict-xsyn       SYSTEM "dict-xsyn.sgml">
+<!entity dummy-seclabel  SYSTEM "dummy-seclabel.sgml">
 <!entity earthdistance   SYSTEM "earthdistance.sgml">
 <!entity fuzzystrmatch   SYSTEM "fuzzystrmatch.sgml">
 <!entity hstore          SYSTEM "hstore.sgml">
-- 
2.11.0