On 07/27/2012 09:28 PM, Nick Guay wrote:
On 26/07/12 08:31, Pavel Březina wrote:
On 07/26/2012 02:24 PM, Nick Guay wrote:
Two grammar fixes for the rule caching mechanism section:
s/kind/kinds
s/large/large amounts of
Ack otherwise.
Thanks. Patch is attached.
One last thing I missed. Add the manpage to the spec file so it gets
installed if necessary.
Good catch. Thanks. New patch is attached.
From e90ab8f3226eb1bdbcf55e4949ef5a4a902d7db4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pavel=20B=C5=99ezina?= <pbrez...@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
---
contrib/sssd.spec.in | 1 +
src/man/Makefile.am | 4 +
src/man/include/seealso.xml | 6 ++
src/man/po/po4a.cfg | 1 +
src/man/sssd-sudo.5.xml | 210 +++++++++++++++++++++++++++++++++++++++++++
5 files changed, 222 insertions(+), 0 deletions(-)
create mode 100644 src/man/sssd-sudo.5.xml
diff --git a/contrib/sssd.spec.in b/contrib/sssd.spec.in
index efabc86027d7061c5729f0564be0e0da66521e58..b444b86d3292f89d97b633aea2151e06ba9ca761 100644
--- a/contrib/sssd.spec.in
+++ b/contrib/sssd.spec.in
@@ -369,6 +369,7 @@ rm -rf $RPM_BUILD_ROOT
%{_mandir}/man5/sssd-krb5.5*
%{_mandir}/man5/sssd-ldap.5*
%{_mandir}/man5/sssd-simple.5*
+%{_mandir}/man5/sssd-sudo.5*
%{_mandir}/man8/sssd.8*
%if (0%{?enable_experimental} == 1)
%{_mandir}/man1/sss_ssh_authorizedkeys.1*
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/po/po4a.cfg b/src/man/po/po4a.cfg
index cc84578ef34ff1bcff478443384422c242e11c4f..1f05c7a4631465141ef265944a13a775b0c963a6 100644
--- a/src/man/po/po4a.cfg
+++ b/src/man/po/po4a.cfg
@@ -8,6 +8,7 @@
[type:docbook] sssd-simple.5.xml $lang:$(builddir)/$lang/sssd-simple.5.xml
[type:docbook] sssd-ipa.5.xml $lang:$(builddir)/$lang/sssd-ipa.5.xml
[type:docbook] sssd-ad.5.xml $lang:$(builddir)/$lang/sssd-ad.5.xml
+[type:docbook] sssd-sudo.5.xml $lang:$(builddir)/$lang/sssd-sudo.5.xml
[type:docbook] sssd.8.xml $lang:$(builddir)/$lang/sssd.8.xml
[type:docbook] sss_obfuscate.8.xml $lang:$(builddir)/$lang/sss_obfuscate.8.xml
[type:docbook] sss_useradd.8.xml $lang:$(builddir)/$lang/sss_useradd.8.xml
diff --git a/src/man/sssd-sudo.5.xml b/src/man/sssd-sudo.5.xml
new file mode 100644
index 0000000000000000000000000000000000000000..d796a1d836a7a55d1e8e1183b8c09c124f54b1c3
--- /dev/null
+++ b/src/man/sssd-sudo.5.xml
@@ -0,0 +1,210 @@
+<?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 the <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 configuring the sudoers search order from the
+ nsswitch.conf file as well as information about the 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>
+ The following example illustrates setting up SSSD to download
+ sudo rules from an IPA server. It is necessary to use the LDAP
+ provider and set appropriate connection parameters to authenticate
+ correctly against the IPA server, because SSSD does not have native
+ support of IPA provider for sudo yet.
+ </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>The SUDO rule caching mechanism</title>
+ <para>
+ The biggest challenge, when developing sudo support in SSSD, was to
+ ensure that running sudo with SSSD as the data source provides the
+ same user experience and is as fast as sudo but keeps providing
+ the most current set of rules as possible. To satisfy these
+ requirements, SSSD uses three kinds of updates. They are referred to
+ as 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 do not generate large amounts of network traffic.
+ </para>
+ <para>
+ The <emphasis>full refresh</emphasis> simply deletes all sudo rules
+ stored in the cache and replaces them 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, full refresh
+ may produce a lot of traffic and thus it should be run only
+ occasionally depending on the size and stability of the sudo rules.
+ </para>
+ <para>
+ The <emphasis>rules refresh</emphasis> ensures that we do not grant
+ the user more permission than defined. It is triggered each time the
+ user runs sudo. Rules refresh 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 rules are missing on the server, the
+ SSSD will do an out of band full refresh because more rules
+ (that apply to other users) may have been deleted.
+ </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 values
+ in <emphasis>sudoHost</emphasis> attribute:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ keyword ALL
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ regular expression
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ netgroup (in the form "+netgroup")
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ hostname or fully qualified domain name of this machine
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ one of the IP addresses of this machine
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ one of the IP addresses of the network
+ (in the form "address/mask")
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ There are many configuration options that can be used to adjust
+ the behaviour. Please refer to "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
_______________________________________________
sssd-devel mailing list
sssd-devel@lists.fedorahosted.org
https://lists.fedorahosted.org/mailman/listinfo/sssd-devel
