MAN: Describe session recording configuration

Reviewed-by: Pavel Březina <pbrezina@redhat.com>

6 files changed, 268 insertions, 1 deletions

diff --git a/contrib/sssd.spec.in b/contrib/sssd.spec.in
index cb1a09c42..74affd39f 100644
--- a/contrib/sssd.spec.in
+++ b/contrib/sssd.spec.in
@@ -990,6 +990,7 @@ done
 %{_mandir}/man5/sssd-files.5*
 %{_mandir}/man5/sssd-simple.5*
 %{_mandir}/man5/sssd-sudo.5*
+%{_mandir}/man5/sssd-session-recording.5*
 %if (0%{?with_secrets} == 1)
 %{_mandir}/man5/sssd-secrets.5*
 %endif
diff --git a/src/man/Makefile.am b/src/man/Makefile.am
index 3a063614f..0e35ac277 100644
--- a/src/man/Makefile.am
+++ b/src/man/Makefile.am
@@ -65,7 +65,7 @@ man_MANS = \
     sssd-krb5.5 sssd-simple.5 sss-certmap.5 \
     sssd_krb5_locator_plugin.8 sss_groupshow.8 \
     pam_sss.8 sss_obfuscate.8 sss_cache.8 sss_debuglevel.8 sss_seed.8 \
-    sss_override.8 idmap_sss.8 sssctl.8 \
+    sss_override.8 idmap_sss.8 sssctl.8 sssd-session-recording.5 \
     $(NULL)
 
 if BUILD_SAMBA
diff --git a/src/man/include/seealso.xml b/src/man/include/seealso.xml
index 2e9c646c4..9b9a72ce2 100644
--- a/src/man/include/seealso.xml
+++ b/src/man/include/seealso.xml
@@ -35,6 +35,10 @@
                 </citerefentry>,
             </phrase>
             <citerefentry>
+                <refentrytitle>sssd-session-recording</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>,
+            <citerefentry>
                 <refentrytitle>sss_cache</refentrytitle><manvolnum>8</manvolnum>
             </citerefentry>,
             <citerefentry>
diff --git a/src/man/po/po4a.cfg b/src/man/po/po4a.cfg
index f325b1afa..e9492cfe1 100644
--- a/src/man/po/po4a.cfg
+++ b/src/man/po/po4a.cfg
@@ -31,6 +31,7 @@
 [type:docbook] sssctl.8.xml $lang:$(builddir)/$lang/sssctl.8.xml
 [type:docbook] sssd-files.5.xml $lang:$(builddir)/$lang/sssd-files.5.xml
 [type:docbook] sssd-secrets.5.xml $lang:$(builddir)/$lang/sssd-secrets.5.xml
+[type:docbook] sssd-session-recording.5.xml $lang:$(builddir)/$lang/sssd-session-recording.5.xml
 [type:docbook] sssd-kcm.8.xml $lang:$(builddir)/$lang/sssd-kcm.8.xml
 [type:docbook] include/service_discovery.xml $lang:$(builddir)/$lang/include/service_discovery.xml opt:"-k 0"
 [type:docbook] include/upstream.xml $lang:$(builddir)/$lang/include/upstream.xml opt:"-k 0"
diff --git a/src/man/sssd-session-recording.5.xml b/src/man/sssd-session-recording.5.xml
new file mode 100644
index 000000000..b53d4e143
--- /dev/null
+++ b/src/man/sssd-session-recording.5.xml
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
+
+    <refmeta>
+        <refentrytitle>sssd-sudo</refentrytitle>
+        <manvolnum>5</manvolnum>
+        <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>sssd-session-recording</refname>
+        <refpurpose>Configuring session recording with SSSD</refpurpose>
+    </refnamediv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            This manual page describes how to configure
+            <citerefentry>
+                <refentrytitle>sssd</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry> to work with
+            <citerefentry>
+                <refentrytitle>tlog-rec-session</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry>, a part of tlog package, to implement user session
+            recording on text terminals.
+            For a detailed configuration syntax reference, refer to the
+            <quote>FILE FORMAT</quote> section of the
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> manual page.
+        </para>
+        <para>
+            SSSD can be set up to enable recording of everything specific
+            users see or type during their sessions on text terminals. E.g.
+            when users log in on the console, or via SSH. SSSD itself doesn't
+            record anything, but makes sure tlog-rec-session is started upon
+            user login, so it can record according to its configuration.
+        </para>
+        <para>
+            For users with session recording enabled, SSSD replaces the user
+            shell with tlog-rec-session in NSS responses, and adds a variable
+            specifying the original shell to the user environment, upon PAM
+            session setup. This way tlog-rec-session can be started in place
+            of the user shell, and know which actual shell to start, once it
+            set up the recording.
+        </para>
+    </refsect1>
+
+    <refsect1 id='configuration-options'>
+        <title>CONFIGURATION OPTIONS</title>
+            <para>
+                These options can be used to configure the session recording.
+            </para>
+            <variablelist>
+                <varlistentry>
+                    <term>scope (string)</term>
+                    <listitem>
+                        <para>
+                            One of the following strings specifying the scope
+                            of session recording:
+                            <variablelist>
+                                <varlistentry>
+                                    <term>"none"</term>
+                                    <listitem>
+                                        <para>
+                                            No users are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>"some"</term>
+                                    <listitem>
+                                        <para>
+                                            Users/groups specified by
+                                            <replaceable>users</replaceable>
+                                            and
+                                            <replaceable>groups</replaceable>
+                                            options are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>"all"</term>
+                                    <listitem>
+                                        <para>
+                                            All users are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                            </variablelist>
+                        </para>
+                        <para>
+                            Default: "none"
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>users (string)</term>
+                    <listitem>
+                        <para>
+                            A comma-separated list of users which should have
+                            session recording enabled. Matches user names as
+                            returned by NSS. I.e. after the possible space
+                            replacement, case changes, etc.
+                        </para>
+                        <para>
+                            Default: Empty. Matches no users.
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>groups (string)</term>
+                    <listitem>
+                        <para>
+                            A comma-separated list of groups, members of which
+                            should have session recording enabled. Matches
+                            group names as returned by NSS. I.e. after the
+                            possible space replacement, case changes, etc.
+                        </para>
+                        <para>
+                            NOTE: using this option (having it set to
+                            anything) has a considerable performance cost,
+                            because each uncached request for a user requires
+                            retrieving and matching the groups the user is
+                            member of.
+                        </para>
+                        <para>
+                            Default: Empty. Matches no groups.
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+    </refsect1>
+
+    <refsect1 id='example'>
+        <title>EXAMPLE</title>
+        <para>
+            The following snippet of sssd.conf enables session recording for
+            users "contractor1" and "contractor2", and group "students".
+        </para>
+        <para>
+<programlisting>
+[session_recording]
+scope = some
+users = contractor1, contractor2
+groups = students
+</programlisting>
+        </para>
+    </refsect1>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
+
+</refentry>
+</reference>
diff --git a/src/man/sssd.conf.5.xml b/src/man/sssd.conf.5.xml
index 7c4cd1f2e..b9eaf5edd 100644
--- a/src/man/sssd.conf.5.xml
+++ b/src/man/sssd.conf.5.xml
@@ -1518,6 +1518,105 @@ pam_account_locked_message = Account locked, please contact help desk.
             </variablelist>
         </refsect2>
 
+        <refsect2 id='SESSION_RECORDING'>
+            <title>Session recording configuration options</title>
+            <para>
+                Session recording works in conjunction with
+                <citerefentry>
+                    <refentrytitle>tlog-rec-session</refentrytitle>
+                    <manvolnum>8</manvolnum>
+                </citerefentry>, a part of tlog package, to log what users see
+                and type when they log in on a text terminal.
+                See also
+                <citerefentry>
+                    <refentrytitle>sssd-session-recording</refentrytitle>
+                    <manvolnum>5</manvolnum>
+                </citerefentry>.
+            </para>
+            <para>
+                These options can be used to configure session recording.
+            </para>
+            <variablelist>
+                <varlistentry>
+                    <term>scope (string)</term>
+                    <listitem>
+                        <para>
+                            One of the following strings specifying the scope
+                            of session recording:
+                            <variablelist>
+                                <varlistentry>
+                                    <term>"none"</term>
+                                    <listitem>
+                                        <para>
+                                            No users are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>"some"</term>
+                                    <listitem>
+                                        <para>
+                                            Users/groups specified by
+                                            <replaceable>users</replaceable>
+                                            and
+                                            <replaceable>groups</replaceable>
+                                            options are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>"all"</term>
+                                    <listitem>
+                                        <para>
+                                            All users are recorded.
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                            </variablelist>
+                        </para>
+                        <para>
+                            Default: "none"
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>users (string)</term>
+                    <listitem>
+                        <para>
+                            A comma-separated list of users which should have
+                            session recording enabled. Matches user names as
+                            returned by NSS. I.e. after the possible space
+                            replacement, case changes, etc.
+                        </para>
+                        <para>
+                            Default: Empty. Matches no users.
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>groups (string)</term>
+                    <listitem>
+                        <para>
+                            A comma-separated list of groups, members of which
+                            should have session recording enabled. Matches
+                            group names as returned by NSS. I.e. after the
+                            possible space replacement, case changes, etc.
+                        </para>
+                        <para>
+                            NOTE: using this option (having it set to
+                            anything) has a considerable performance cost,
+                            because each uncached request for a user requires
+                            retrieving and matching the groups the user is
+                            member of.
+                        </para>
+                        <para>
+                            Default: Empty. Matches no groups.
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect2>
+
     </refsect1>
 
     <refsect1 id='domain-sections'>