From 9dfe44c73d2cac39e1e970aca67617fe68ad4b2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pavel=20B=C5=99ezina?= <pbrezina@redhat.com>
Date: Mon, 23 Jul 2012 15:46:31 +0200
Subject: [PATCH] manpage: sssd-sudo - documents how sudo works with sssd

https://fedorahosted.org/sssd/ticket/1418
---
 src/man/Makefile.am         |    4 +
 src/man/include/seealso.xml |    6 ++
 src/man/sssd-sudo.5.xml     |  198 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 208 insertions(+), 0 deletions(-)
 create mode 100644 src/man/sssd-sudo.5.xml

diff --git a/src/man/Makefile.am b/src/man/Makefile.am
index ca1a22611e67f95b2b4021cb0be8eb252f5fd1f4..4ed76c8ab244da77fc746eef6476456def33ea64 100644
--- a/src/man/Makefile.am
+++ b/src/man/Makefile.am
@@ -48,6 +48,10 @@ if BUILD_SSH
 man_MANS += sss_ssh_authorizedkeys.1 sss_ssh_knownhostsproxy.1
 endif
 
+if BUILD_SUDO
+man_MANS += sssd-sudo.5
+endif
+
 SUFFIXES = .1.xml .1 .3.xml .3 .5.xml .5 .8.xml .8
 .1.xml.1:
 	$(XMLLINT) $(XMLLINT_FLAGS) $<
diff --git a/src/man/include/seealso.xml b/src/man/include/seealso.xml
index 6fa7359f32b0eeac06b012ab6a8cd831a024d45a..80c228e31cd7982dcf076f25cf19938541bda7da 100644
--- a/src/man/include/seealso.xml
+++ b/src/man/include/seealso.xml
@@ -22,6 +22,12 @@
             <citerefentry>
                 <refentrytitle>sssd-ad</refentrytitle><manvolnum>5</manvolnum>
             </citerefentry>,
+            <phrase condition="with_sudo">
+                <citerefentry>
+                    <refentrytitle>sssd-sudo</refentrytitle>
+                    <manvolnum>5</manvolnum>
+                </citerefentry>,
+            </phrase>
             <citerefentry>
                 <refentrytitle>sss_cache</refentrytitle><manvolnum>8</manvolnum>
             </citerefentry>,
diff --git a/src/man/sssd-sudo.5.xml b/src/man/sssd-sudo.5.xml
new file mode 100644
index 0000000000000000000000000000000000000000..b4a3c79230aaa82e9b44079b1cc5ffa5e128b3d6
--- /dev/null
+++ b/src/man/sssd-sudo.5.xml
@@ -0,0 +1,198 @@
+<?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-sudo</refname>
+        <refpurpose>the configuration file for SSSD</refpurpose>
+    </refnamediv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            This manual page describes how to configure
+            <citerefentry>
+                <refentrytitle>sudo</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry> to work with
+            <citerefentry>
+                <refentrytitle>sssd</refentrytitle>
+                <manvolnum>8</manvolnum>
+            </citerefentry> and how SSSD caches sudo rules.
+        </para>
+    </refsect1>
+    
+    <refsect1 id='sudo'>
+        <title>Configuring sudo to cooperate with SSSD</title>
+        <para>
+            To enable SSSD as a source for sudo rules, add
+            <emphasis>sss</emphasis> to <emphasis>sudoers</emphasis> entry in 
+            <citerefentry>
+                <refentrytitle>nsswitch.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>.
+        </para>
+        <para>
+            For example, to configure sudo to first lookup rules in the standard
+            <citerefentry>
+                <refentrytitle>sudoers</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> file (which should contain rules that apply to
+            local users) and then in SSSD, the nsswitch.conf file should contain
+            the following line:
+        </para>
+        <para>
+<programlisting>
+sudoers: files sss
+</programlisting>
+        </para>
+        <para>
+            More information about sudoers nsswitch.conf format as well as
+            information about an LDAP schema that is used to store sudo rules in
+            the directory can be found in
+            <citerefentry>
+                <refentrytitle>sudoers.ldap</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>.        
+        </para>
+    </refsect1>
+    
+    <refsect1 id='sssd'>
+        <title>Configuring SSSD to fetch sudo rules</title>
+        <para>
+            The following example shows how to configure SSSD to download sudo
+            rules from an LDAP server.
+        </para>
+        <para>
+<programlisting>
+[sssd]
+config_file_version = 2
+services = nss, pam, sudo
+domains = EXAMPLE
+
+[domain/EXAMPLE]
+id_provider = ldap
+sudo_provider = ldap
+ldap_uri = ldap://example.com
+ldap_sudo_search_base = ou=sudoers,dc=example,dc=com
+</programlisting>
+        </para>
+        <para>
+            Below given is shown how to configure SSSD to download sudo 
+            rules from an IPA server. Because SSSD does not have native
+            support of IPA provider for sudo yet, it is necessary to use LDAP
+            provider and set appropriate connection parameters.
+        </para>
+        <para>
+<programlisting>
+[sssd]
+config_file_version = 2
+services = nss, pam, sudo
+domains = EXAMPLE
+
+[domain/EXAMPLE]
+id_provider = ipa
+ipa_domain = example.com
+ipa_server = ipa.example.com
+ldap_tls_cacert = /etc/ipa/ca.crt
+
+sudo_provider = ldap
+ldap_uri = ldap://ipa.example.com
+ldap_sudo_search_base = ou=sudoers,dc=example,dc=com
+ldap_sasl_mech = GSSAPI
+ldap_sasl_authid = host/hostname.example.com
+ldap_sasl_realm = EXAMPLE.COM
+krb5_server = ipa.example.com
+</programlisting>
+        </para>
+    </refsect1>
+    
+    <refsect1 id='cache'>
+        <title>How does SSSD cache sudo rules</title>
+        <para>
+            The biggest challenge, when developing sudo support in SSSD, was to
+            ensure that running sudo with SSSD as the data source gives the
+            same user experience and is as fast as sudo but keeps providing
+            the most current set of rules as possible. To accomplish these
+            points, SSSD use three kind of updates. We call them full refresh,
+            smart refresh and rules refresh.
+        </para>
+        <para>
+            The <emphasis>smart refresh</emphasis> periodically downloads rules
+            that are new or were modified after the last update. Its primary
+            goal is to keep the database growing by fetching only small
+            increments that does not overload bandwith.
+        </para>
+        <para>
+            The <emphasis>full refresh</emphasis> simply deletes everything
+            that is in the cache and replaces it with all rules that are stored
+            on the server. This is used to keep the cache consistent by removing
+            every rule which was deleted from the server. Hovewer, it may
+            produce a lot of traffic (depending on how many rules exist) and
+            it should be run only few times a day.
+        </para>
+        <para>
+            At least one of those two refresh types has to be enabled to be run
+            periodically.
+        </para>
+        <para>
+            The <emphasis>rules refresh</emphasis> ensures that we do not give
+            the user more permission that defined. It is triggered each time the
+            user runs sudo. It will find all rules that apply to this user,
+            check their expiration time and redownload them if expired. In the
+            case that any of these rule is missing on the server, the SSSD will
+            do an out of band full refresh because it is very probable that more
+            rules (that apply to other users) were deleted as well. 
+        </para>
+        <para>
+            If enabled, SSSD will store only rules that can be applied to this
+            machine. This means rules that contain one of the following in 
+            <emphasis>sudoHost</emphasis> attribute:
+        </para>
+        <para>
+            * keyword ALL
+        </para>
+        <para>
+            * regullar expression
+        </para>
+        <para>
+            * netgroup (in the form "+netgroup")
+        </para>
+        <para>
+            * hostname or fully qualified domain name of this machine
+        </para>
+        <para>
+            * one of the IP addresses of this machine
+        </para>
+        <para>
+            * one of the IP addresses of the network
+            (in the form "address/mask")
+        </para>
+        <para>
+            There are many configuration options that can be used to adjust
+            the behaviour. Take a look at "ldap_sudo_*" in
+            <citerefentry>
+                <refentrytitle>sssd-ldap</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry> and "sudo_*" in
+            <citerefentry>
+                <refentrytitle>sssd.conf</refentrytitle>
+                <manvolnum>5</manvolnum>
+            </citerefentry>.     
+        </para>
+    </refsect1>
+
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/seealso.xml" />
+
+</refentry>
+</reference>
-- 
1.7.6.5

