Re: sepgsql documentation fixes

Started by Robert Haasover 14 years ago3 messages
#1Robert Haas
robertmhaas@gmail.com
1 attachment(s)

On Tue, Jul 19, 2011 at 6:10 AM, Kohei Kaigai <Kohei.Kaigai@emea.nec.com> wrote:

/etc/selinux/targeted/contexts/sepgsql_contexts:  line 33 has invalid object
type db_blobs

It is not an error, but just a notification to inform users that
sepgsql_contexts
file contains invalid lines. It is harmless, so we can ignore them.
I don't think sepgsql.sgml should mention about this noise, because it purely
come from the problem in libselinux and refpolicy; these are external packages
from viewpoint of PostgreSQL.

This is in contradiction with the current phrase in the documentation
that's right after the sepgsql.sql loading: "If the installation process
completes without error, you can now start the server normally". IMHO if
there are warnings that can be ignored, it would limit confusion for
sepgsql users if the documentation would say it at this point, e.g. "If
the installation process completes without error, you can now start the
server normally. Warnings from errors in sepgsql_contexts, a file
external to PostgreSQL, are harmless and can be ignored."

Indeed, it might be confusable to understand whether the installation got
completed correctly, or not.
So, I appended more descriptions about this messages, as follows:

+  <para>
+   Please note that you may see the following notifications depending on
+   the combination of a particular version of <productname>libselinux</>
+   and <productname>selinux-policy</>.
+<screen>
+/etc/selinux/targeted/contexts/sepgsql_contexts:  line 33 has invalid object ty
+</screen>
+   It is harmless messages and already fixed. So, you can ignore these
+   messages or update related packages to the latest version.
+  </para>

See the attached patch, that contains other 3 documentation updates.

Thank you for this clarification. I have some ideas of things that if
they were in the documentation they'd helped me. Instead of seeking
agreement on each item, I propose that I gather documentation additions
in a patch later after the review, and leave it up to you guys whether
to include them or not.

OK, I like to check them. In addition, I'll also revise the wikipage in
parallel to inform correctly.

Does all of this apply to both 9.1 and 9.2devel?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Attachments:

pgsql-sepgsql-doc-revise.2.patchapplication/octet-stream; name=pgsql-sepgsql-doc-revise.2.patchDownload
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index 8a01b94..a62f02a 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -198,6 +198,36 @@ SECURITY LABEL FOR selinux ON TABLE mytable IS 'system_u:object_r:sepgsql_table_
  </refsect1>
 
  <refsect1>
+  <title>See Also</title>
+  <para>
+   These modules requires <command>SECURITY LABEL</command> command
+   for their foundation. Also see the section for more details.
+  </para>
+  <variablelist>
+   <varlistentry>
+    <term><xref linkend="sepgsql"></term>
+    <listitem>
+     <para>
+      <filename>sepgsql</> is a loadable module which supports label-based
+      mandatory access control (MAC) based on <productname>SELinux</> security
+      policy.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><xref linkend="dummy-seclabel"></term>
+    <listitem>
+     <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>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
   <title>Compatibility</title>
   <para>
    There is no <command>SECURITY LABEL</command> command in the SQL standard.
diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index db9b64c..4b9e1f3 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -96,11 +96,13 @@ Policy from config file:        targeted
 
   <para>
    The following instructions that assume your installation is under the
-   <filename>/usr/local/pgsql</> directory. Adjust the paths shown below as
-   appropriate for your installation.
+   <filename>/usr/local/pgsql</> directory and the database cluster is
+   under the <filename>/path/to/database</> directory. Adjust the paths
+   shown below as appropriate for your installation.
   </para>
 
 <screen>
+$ export PGDATA=/path/to/database
 $ initdb
 $ vi $PGDATA/postgresql.conf
 $ for DBNAME in template0 template1 postgres; do
@@ -113,6 +115,17 @@ $ for DBNAME in template0 template1 postgres; do
    If the installation process completes without error, you can now start the
    server normally.
   </para>
+
+  <para>
+   Please note that you may see the following notifications depending on
+   the combination of a particular version of <productname>libselinux</>
+   and <productname>selinux-policy</>.
+<screen>
+/etc/selinux/targeted/contexts/sepgsql_contexts:  line 33 has invalid object type db_blobs
+</screen>
+   It is harmless messages and already fixed. So, you can ignore these
+   messages or update related packages to the latest version.
+  </para>
  </sect2>
 
  <sect2 id="sepgsql-regression">
@@ -124,7 +137,16 @@ $ for DBNAME in template0 template1 postgres; do
   </para>
 
   <para>
-   First, build and install the policy package for the regression test.
+   First, setup <productname>sepgsql</productname> according to
+   the <xref linkend="sepgsql-installation">.
+   We intend this regression test is run on the working system using
+   <command>make installcheck</command>, so the server system must be
+   correctly set up to allow current user of shell process to connect
+   database as superuser without authentication.
+  </para>
+
+  <para>
+   Second, build and install the policy package for the regression test.
    The <filename>sepgsql-regtest.pp</> is a special purpose policy package
    which provides a set of rules to be allowed during the regression tests.
    It should be built from the policy source file 
@@ -149,7 +171,7 @@ sepgsql-regtest 1.03
 </screen>
 
   <para>
-   Second, turn on <literal>sepgsql_regression_test_mode</>.
+   Third, turn on <literal>sepgsql_regression_test_mode</>.
    We don't enable all the rules in the <filename>sepgsql-regtest.pp</>
    by default, for your system's safety.
    The <literal>sepgsql_regression_test_mode</literal> parameter is associated
#2Kohei KaiGai
kaigai@kaigai.gr.jp
In reply to: Robert Haas (#1)

2011/7/20 Robert Haas <robertmhaas@gmail.com>:

On Tue, Jul 19, 2011 at 6:10 AM, Kohei Kaigai <Kohei.Kaigai@emea.nec.com> wrote:

/etc/selinux/targeted/contexts/sepgsql_contexts:  line 33 has invalid object
type db_blobs

It is not an error, but just a notification to inform users that
sepgsql_contexts
file contains invalid lines. It is harmless, so we can ignore them.
I don't think sepgsql.sgml should mention about this noise, because it purely
come from the problem in libselinux and refpolicy; these are external packages
from viewpoint of PostgreSQL.

This is in contradiction with the current phrase in the documentation
that's right after the sepgsql.sql loading: "If the installation process
completes without error, you can now start the server normally". IMHO if
there are warnings that can be ignored, it would limit confusion for
sepgsql users if the documentation would say it at this point, e.g. "If
the installation process completes without error, you can now start the
server normally. Warnings from errors in sepgsql_contexts, a file
external to PostgreSQL, are harmless and can be ignored."

Indeed, it might be confusable to understand whether the installation got
completed correctly, or not.
So, I appended more descriptions about this messages, as follows:

+  <para>
+   Please note that you may see the following notifications depending on
+   the combination of a particular version of <productname>libselinux</>
+   and <productname>selinux-policy</>.
+<screen>
+/etc/selinux/targeted/contexts/sepgsql_contexts:  line 33 has invalid object ty
+</screen>
+   It is harmless messages and already fixed. So, you can ignore these
+   messages or update related packages to the latest version.
+  </para>

See the attached patch, that contains other 3 documentation updates.

Thank you for this clarification. I have some ideas of things that if
they were in the documentation they'd helped me. Instead of seeking
agreement on each item, I propose that I gather documentation additions
in a patch later after the review, and leave it up to you guys whether
to include them or not.

OK, I like to check them. In addition, I'll also revise the wikipage in
parallel to inform correctly.

Does all of this apply to both 9.1 and 9.2devel?

This update came from feedbacks when people tried to install contrib/sepgsql
of v9.1 and got troubled.
So, I think it is helpful to apply v9.1 also.

Thanks,
--
KaiGai Kohei <kaigai@kaigai.gr.jp>

#3Robert Haas
robertmhaas@gmail.com
In reply to: Kohei KaiGai (#2)

On Wed, Jul 20, 2011 at 8:50 AM, Kohei KaiGai <kaigai@kaigai.gr.jp> wrote:

Does all of this apply to both 9.1 and 9.2devel?

This update came from feedbacks when people tried to install contrib/sepgsql
of v9.1 and got troubled.
So, I think it is helpful to apply v9.1 also.

OK, done, with some corrections.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company