diff options
Diffstat (limited to 'src/man/include')
| -rw-r--r-- | src/man/include/ad_modified_defaults.xml | 110 | ||||
| -rw-r--r-- | src/man/include/autofs_attributes.xml | 70 | ||||
| -rw-r--r-- | src/man/include/autofs_restart.xml | 6 | ||||
| -rw-r--r-- | src/man/include/debug_levels.xml | 113 | ||||
| -rw-r--r-- | src/man/include/debug_levels_tools.xml | 87 | ||||
| -rw-r--r-- | src/man/include/failover.xml | 132 | ||||
| -rw-r--r-- | src/man/include/homedir_substring.xml | 18 | ||||
| -rw-r--r-- | src/man/include/ipa_modified_defaults.xml | 123 | ||||
| -rw-r--r-- | src/man/include/krb5_options.xml | 167 | ||||
| -rw-r--r-- | src/man/include/ldap_id_mapping.xml | 317 | ||||
| -rw-r--r-- | src/man/include/ldap_search_bases.xml | 36 | ||||
| -rw-r--r-- | src/man/include/local.xml | 20 | ||||
| -rw-r--r-- | src/man/include/override_homedir.xml | 84 | ||||
| -rw-r--r-- | src/man/include/param_help.xml | 10 | ||||
| -rw-r--r-- | src/man/include/param_help_py.xml | 10 | ||||
| -rw-r--r-- | src/man/include/seealso.xml | 88 | ||||
| -rw-r--r-- | src/man/include/service_discovery.xml | 48 | ||||
| -rw-r--r-- | src/man/include/upstream.xml | 4 |
18 files changed, 1443 insertions, 0 deletions
diff --git a/src/man/include/ad_modified_defaults.xml b/src/man/include/ad_modified_defaults.xml new file mode 100644 index 0000000..65c9a01 --- /dev/null +++ b/src/man/include/ad_modified_defaults.xml @@ -0,0 +1,110 @@ +<refsect1 id='modified-default-options'> + <title>MODIFIED DEFAULT OPTIONS</title> + <para> + Certain option defaults do not match their respective backend + provider defaults, these option names and AD provider-specific + defaults are listed below: + </para> + <refsect2 id='krb5_modifications'> + <title>KRB5 Provider</title> + <itemizedlist> + <listitem> + <para> + krb5_validate = true + </para> + </listitem> + <listitem> + <para> + krb5_use_enterprise_principal = true + </para> + </listitem> + </itemizedlist> + </refsect2> + <refsect2 id='ldap_modifications'> + <title>LDAP Provider</title> + <itemizedlist> + <listitem> + <para> + ldap_schema = ad + </para> + </listitem> + <listitem> + <para> + ldap_force_upper_case_realm = true + </para> + </listitem> + <listitem> + <para> + ldap_id_mapping = true + </para> + </listitem> + <listitem> + <para> + ldap_sasl_mech = GSS-SPNEGO + </para> + </listitem> + <listitem> + <para> + ldap_referrals = false + </para> + </listitem> + <listitem> + <para> + ldap_account_expire_policy = ad + </para> + </listitem> + <listitem> + <para> + ldap_use_tokengroups = true + </para> + </listitem> + <listitem> + <para> + ldap_sasl_authid = sAMAccountName@REALM (typically SHORTNAME$@REALM) + </para> + <para> + The AD provider looks for a different principal than the + LDAP provider by default, because in an Active Directory + environment the principals are divided into two groups + - User Principals and Service Principals. Only User + Principal can be used to obtain a TGT and by default, + computer object's principal is constructed from + its sAMAccountName and the AD realm. The well-known + host/hostname@REALM principal is a Service Principal + and thus cannot be used to get a TGT with. + </para> + </listitem> + </itemizedlist> + </refsect2> + <refsect2 id='nss_modifications'> + <title>NSS configuration</title> + <itemizedlist> + <listitem> + <para> + fallback_homedir = /home/%d/%u + </para> + <para> + The AD provider automatically sets + "fallback_homedir = /home/%d/%u" to provide personal + home directories for users without the homeDirectory + attribute. If your AD Domain is properly + populated with Posix attributes, and you want to avoid + this fallback behavior, you can explicitly + set "fallback_homedir = %o". + </para> + <para> + Note that the system typically expects a home directory + in /home/%u folder. If you decide to use a different + directory structure, some other parts of your system may + need adjustments. + </para> + <para> + For example automated creation of home directories in + combination with selinux requires selinux adjustment, + otherwise the home directory will be created with wrong + selinux context. + </para> + </listitem> + </itemizedlist> + </refsect2> +</refsect1> diff --git a/src/man/include/autofs_attributes.xml b/src/man/include/autofs_attributes.xml new file mode 100644 index 0000000..9775a57 --- /dev/null +++ b/src/man/include/autofs_attributes.xml @@ -0,0 +1,70 @@ +<variablelist> + <varlistentry> + <term>ldap_autofs_map_object_class (string)</term> + <listitem> + <para> + The object class of an automount map entry in LDAP. + </para> + <para> + Default: nisMap (rfc2307, autofs_provider=ad), + otherwise automountMap + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ldap_autofs_map_name (string)</term> + <listitem> + <para> + The name of an automount map entry in LDAP. + </para> + <para> + Default: nisMapName (rfc2307, + autofs_provider=ad), otherwise automountMapName + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ldap_autofs_entry_object_class (string)</term> + <listitem> + <para> + The object class of an automount entry + in LDAP. The entry usually corresponds to a mount + point. + </para> + <para> + Default: nisObject (rfc2307, autofs_provider=ad), + otherwise automount + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ldap_autofs_entry_key (string)</term> + <listitem> + <para> + The key of an automount entry in LDAP. The + entry usually corresponds to a mount point. + </para> + <para> + Default: cn (rfc2307, autofs_provider=ad), + otherwise automountKey + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ldap_autofs_entry_value (string)</term> + <listitem> + <para> + The key of an automount entry in LDAP. The + entry usually corresponds to a mount point. + </para> + <para> + Default: nisMapEntry (rfc2307, + autofs_provider=ad), otherwise automountInformation + </para> + </listitem> + </varlistentry> +</variablelist> diff --git a/src/man/include/autofs_restart.xml b/src/man/include/autofs_restart.xml new file mode 100644 index 0000000..901855b --- /dev/null +++ b/src/man/include/autofs_restart.xml @@ -0,0 +1,6 @@ +<para> + Please note that the automounter only reads the master + map on startup, so if any autofs-related changes are made + to the sssd.conf, you typically also need to restart the + automounter daemon after restarting the SSSD. +</para> diff --git a/src/man/include/debug_levels.xml b/src/man/include/debug_levels.xml new file mode 100644 index 0000000..f43091e --- /dev/null +++ b/src/man/include/debug_levels.xml @@ -0,0 +1,113 @@ +<listitem> + <para> + SSSD supports two representations for specifying the debug level. The + simplest is to specify a decimal value from 0-9, which represents + enabling that level and all lower-level debug messages. The more + comprehensive option is to specify a hexadecimal bitmask to enable or + disable specific levels (such as if you wish to suppress a level). + </para> + <para> + Please note that each SSSD service logs into its own log + file. Also please note that enabling <quote>debug_level</quote> + in the <quote>[sssd]</quote> section only enables debugging just + for the sssd process itself, not for the responder or provider + processes. The <quote>debug_level</quote> parameter should be + added to all sections that you wish to produce debug logs from. + </para> + <para> + In addition to changing the log level in the config file using + the <quote>debug_level</quote> parameter, which is persistent, but + requires SSSD restart, it is also possible to change the debug level + on the fly using the + <citerefentry> + <refentrytitle>sss_debuglevel</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + tool. + </para> + <para> + Currently supported debug levels: + </para> + <para> + <emphasis>0</emphasis>, + <emphasis>0x0010</emphasis>: + Fatal failures. Anything that would prevent SSSD from starting up or + causes it to cease running. + </para> + <para> + <emphasis>1</emphasis>, + <emphasis>0x0020</emphasis>: + Critical failures. An error that doesn't kill SSSD, but one that + indicates that at least one major feature is not going to work + properly. + </para> + <para> + <emphasis>2</emphasis>, + <emphasis>0x0040</emphasis>: Serious failures. An error announcing + that a particular request or operation has failed. + </para> + <para> + <emphasis>3</emphasis>, + <emphasis>0x0080</emphasis>: Minor failures. These are the errors that + would percolate down to cause the operation failure of 2. + </para> + <para> + <emphasis>4</emphasis>, + <emphasis>0x0100</emphasis>: Configuration settings. + </para> + <para> + <emphasis>5</emphasis>, + <emphasis>0x0200</emphasis>: Function data. + </para> + <para> + <emphasis>6</emphasis>, + <emphasis>0x0400</emphasis>: Trace messages for operation functions. + </para> + <para> + <emphasis>7</emphasis>, + <emphasis>0x1000</emphasis>: Trace messages for internal control + functions. + </para> + <para> + <emphasis>8</emphasis>, + <emphasis>0x2000</emphasis>: Contents of function-internal variables + that may be interesting. + </para> + <para> + <emphasis>9</emphasis>, + <emphasis>0x4000</emphasis>: Extremely low-level tracing information. + </para> + <para> + <emphasis>9</emphasis>, + <emphasis>0x20000</emphasis>: Performance and statistical data, + please note that due to the way requests are processed internally the + logged execution time of a request might be longer than it actually + was. + </para> + <para> + <emphasis>10</emphasis>, + <emphasis>0x10000</emphasis>: Even more low-level libldb tracing + information. Almost never really required. + </para> + <para> + To log required bitmask debug levels, simply add their numbers together + as shown in following examples: + </para> + <para> + <emphasis>Example</emphasis>: To log fatal failures, critical failures, + serious failures and function data use 0x0270. + </para> + <para> + <emphasis>Example</emphasis>: To log fatal failures, configuration + settings, function data, trace messages for internal control functions + use 0x1310. + </para> + <para> + <emphasis>Note</emphasis>: The bitmask format of debug levels was + introduced in 1.7.0. + </para> + <para> + <emphasis>Default</emphasis>: 0x0070 (i.e. fatal, critical and serious + failures; corresponds to setting 2 in decimal notation) + </para> +</listitem> diff --git a/src/man/include/debug_levels_tools.xml b/src/man/include/debug_levels_tools.xml new file mode 100644 index 0000000..46a3c7d --- /dev/null +++ b/src/man/include/debug_levels_tools.xml @@ -0,0 +1,87 @@ +<listitem> + <para> + SSSD supports two representations for specifying the debug level. The + simplest is to specify a decimal value from 0-9, which represents + enabling that level and all lower-level debug messages. The more + comprehensive option is to specify a hexadecimal bitmask to enable or + disable specific levels (such as if you wish to suppress a level). + </para> + <para> + Currently supported debug levels: + </para> + <para> + <emphasis>0</emphasis>, + <emphasis>0x0010</emphasis>: + Fatal failures. Anything that would prevent SSSD from starting up or + causes it to cease running. + </para> + <para> + <emphasis>1</emphasis>, + <emphasis>0x0020</emphasis>: + Critical failures. An error that doesn't kill SSSD, but one that + indicates that at least one major feature is not going to work + properly. + </para> + <para> + <emphasis>2</emphasis>, + <emphasis>0x0040</emphasis>: Serious failures. An error announcing + that a particular request or operation has failed. + </para> + <para> + <emphasis>3</emphasis>, + <emphasis>0x0080</emphasis>: Minor failures. These are the errors that + would percolate down to cause the operation failure of 2. + </para> + <para> + <emphasis>4</emphasis>, + <emphasis>0x0100</emphasis>: Configuration settings. + </para> + <para> + <emphasis>5</emphasis>, + <emphasis>0x0200</emphasis>: Function data. + </para> + <para> + <emphasis>6</emphasis>, + <emphasis>0x0400</emphasis>: Trace messages for operation functions. + </para> + <para> + <emphasis>7</emphasis>, + <emphasis>0x1000</emphasis>: Trace messages for internal control + functions. + </para> + <para> + <emphasis>8</emphasis>, + <emphasis>0x2000</emphasis>: Contents of function-internal variables + that may be interesting. + </para> + <para> + <emphasis>9</emphasis>, + <emphasis>0x4000</emphasis>: Extremely low-level tracing information. + </para> + <para> + <emphasis>10</emphasis>, + <emphasis>0x10000</emphasis>: Even more low-level libldb tracing + information. Almost never really required. + </para> + <para> + To log required bitmask debug levels, simply add their numbers together + as shown in following examples: + </para> + <para> + <emphasis>Example</emphasis>: To log fatal failures, critical failures, + serious failures and function data use 0x0270. + </para> + <para> + <emphasis>Example</emphasis>: To log fatal failures, configuration + settings, function data, trace messages for internal control functions + use 0x1310. + </para> + <para> + <emphasis>Note</emphasis>: The bitmask format of debug levels was + introduced in 1.7.0. + </para> + <para> + <emphasis>Default</emphasis>: 0x0070 (i.e. fatal, critical and serious + failures; corresponds to setting 2 in decimal notation) + </para> +</listitem> diff --git a/src/man/include/failover.xml b/src/man/include/failover.xml new file mode 100644 index 0000000..758270d --- /dev/null +++ b/src/man/include/failover.xml @@ -0,0 +1,132 @@ +<refsect1 id='failover'> + <title>FAILOVER</title> + <para> + The failover feature allows back ends to automatically switch to + a different server if the current server fails. + </para> + <refsect2 id='failover_syntax'> + <title>Failover Syntax</title> + <para> + The list of servers is given as a comma-separated list; any + number of spaces is allowed around the comma. The servers are + listed in order of preference. The list can contain any number + of servers. + </para> + <para> + For each failover-enabled config option, two variants exist: + <emphasis>primary</emphasis> and <emphasis>backup</emphasis>. + The idea is that servers in the primary list are preferred and + backup servers are only searched if no primary servers can be + reached. If a backup server is selected, a timeout of 31 seconds + is set. After this timeout SSSD will periodically try to reconnect + to one of the primary servers. If it succeeds, it will replace + the current active (backup) server. + </para> + </refsect2> + <refsect2 id='failover_mechanism'> + <title>The Failover Mechanism</title> + <para> + The failover mechanism distinguishes between a machine and a + service. The back end first tries to resolve the hostname of a + given machine; if this resolution attempt fails, the machine is + considered offline. No further attempts are made to connect + to this machine for any other service. If the resolution + attempt succeeds, the back end tries to connect to a service + on this machine. If the service connection attempt fails, + then only this particular service is considered offline and + the back end automatically switches over to the next service. + The machine is still considered online and might still be tried + for another service. + </para> + <para> + Further connection attempts are made to machines or services + marked as offline after a specified period of time; this is + currently hard coded to 30 seconds. + </para> + <para> + If there are no more machines to try, the back end as a whole + switches to offline mode, and then attempts to reconnect + every 30 seconds. + </para> + </refsect2> + <refsect2 id='failover_tuning'> + <title>Failover time outs and tuning</title> + <para> + Resolving a server to connect to can be as simple as running + a single DNS query or can involve several steps, such as finding + the correct site or trying out multiple host names in case some + of the configured servers are not reachable. The more complex + scenarios can take some time and SSSD needs to balance between + providing enough time to finish the resolution process but on + the other hand, not trying for too long before falling back + to offline mode. If the SSSD debug logs show that the server + resolution is timing out before a live server is contacted, + you can consider changing the time outs. + </para> + <para> + This section lists the available tunables. Please refer to their + description in the + <citerefentry> + <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + manual page. + <variablelist> + <varlistentry> + <term> + dns_resolver_server_timeout + </term> + <listitem> + <para> + Time in milliseconds that sets how long would SSSD + talk to a single DNS server before trying next one. + </para> + <para> + Default: 1000 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + dns_resolver_op_timeout + </term> + <listitem> + <para> + Time in seconds to tell how long would SSSD try + to resolve single DNS query (e.g. resolution of a + hostname or an SRV record) before trying the next + hostname or discovery domain. + </para> + <para> + Default: 3 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + dns_resolver_timeout + </term> + <listitem> + <para> + How long would SSSD try to resolve a failover + service. This service resolution internally might + include several steps, such as resolving DNS SRV + queries or locating the site. + </para> + <para> + Default: 6 + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + For LDAP-based providers, the resolve operation is performed + as part of an LDAP connection operation. Therefore, also the + <quote>ldap_opt_timeout</quote> timeout should be set to + a larger value than <quote>dns_resolver_timeout</quote> + which in turn should be set to a larger value than + <quote>dns_resolver_op_timeout</quote> which should be larger + than <quote>dns_resolver_server_timeout</quote>. + </para> + </refsect2> +</refsect1> diff --git a/src/man/include/homedir_substring.xml b/src/man/include/homedir_substring.xml new file mode 100644 index 0000000..54d9bc9 --- /dev/null +++ b/src/man/include/homedir_substring.xml @@ -0,0 +1,18 @@ +<varlistentry> + <term>homedir_substring (string)</term> + <listitem> + <para> + The value of this option will be used in the expansion of the + <emphasis>override_homedir</emphasis> option if the template + contains the format string <emphasis>%H</emphasis>. An LDAP + directory entry can directly contain this template so that this + option can be used to expand the home directory path for each + client machine (or operating system). It can be set per-domain or + globally in the [nss] section. A value specified in a domain + section will override one set in the [nss] section. + </para> + <para> + Default: /home + </para> + </listitem> +</varlistentry> diff --git a/src/man/include/ipa_modified_defaults.xml b/src/man/include/ipa_modified_defaults.xml new file mode 100644 index 0000000..1f4d48b --- /dev/null +++ b/src/man/include/ipa_modified_defaults.xml @@ -0,0 +1,123 @@ +<refsect1 id='modified-default-options'> + <title>MODIFIED DEFAULT OPTIONS</title> + <para> + Certain option defaults do not match their respective backend + provider defaults, these option names and IPA provider-specific + defaults are listed below: + </para> + <refsect2 id='krb5_modifications'> + <title>KRB5 Provider</title> + <itemizedlist> + <listitem> + <para> + krb5_validate = true + </para> + </listitem> + <listitem> + <para> + krb5_use_fast = try + </para> + </listitem> + <listitem> + <para> + krb5_canonicalize = true + </para> + </listitem> + </itemizedlist> + </refsect2> + <refsect2 id='ldap_general_modifications'> + <title>LDAP Provider - General</title> + <itemizedlist> + <listitem> + <para> + ldap_schema = ipa_v1 + </para> + </listitem> + <listitem> + <para> + ldap_force_upper_case_realm = true + </para> + </listitem> + <listitem> + <para> + ldap_sasl_mech = GSSAPI + </para> + </listitem> + <listitem> + <para> + ldap_sasl_minssf = 56 + </para> + </listitem> + <listitem> + <para> + ldap_account_expire_policy = ipa + </para> + </listitem> + <listitem> + <para> + ldap_use_tokengroups = true + </para> + </listitem> + </itemizedlist> + </refsect2> + <refsect2 id='ldap_user_modifications'> + <title>LDAP Provider - User options</title> + <itemizedlist> + <listitem> + <para> + ldap_user_member_of = memberOf + </para> + </listitem> + <listitem> + <para> + ldap_user_uuid = ipaUniqueID + </para> + </listitem> + <listitem> + <para> + ldap_user_ssh_public_key = ipaSshPubKey + </para> + </listitem> + <listitem> + <para> + ldap_user_auth_type = ipaUserAuthType + </para> + </listitem> + </itemizedlist> + </refsect2> + <refsect2 id='ldap_group_modifications'> + <title>LDAP Provider - Group options</title> + <itemizedlist> + <listitem> + <para> + ldap_group_object_class = ipaUserGroup + </para> + </listitem> + <listitem> + <para> + ldap_group_object_class_alt = posixGroup + </para> + </listitem> + <listitem> + <para> + ldap_group_member = member + </para> + </listitem> + <listitem> + <para> + ldap_group_uuid = ipaUniqueID + </para> + </listitem> + <listitem> + <para> + ldap_group_objectsid = ipaNTSecurityIdentifier + </para> + </listitem> + <listitem> + <para> + ldap_group_external_member = ipaExternalMember + </para> + </listitem> + </itemizedlist> + </refsect2> +</refsect1> diff --git a/src/man/include/krb5_options.xml b/src/man/include/krb5_options.xml new file mode 100644 index 0000000..d82be7b --- /dev/null +++ b/src/man/include/krb5_options.xml @@ -0,0 +1,167 @@ +<variablelist> + <varlistentry> + <term>krb5_auth_timeout (integer)</term> + <listitem> + <para> + Timeout in seconds after an online authentication request + or change password request is aborted. If possible, the + authentication request is continued offline. + </para> + <para> + Default: 6 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>krb5_validate (boolean)</term> + <listitem> + <para> + Verify with the help of krb5_keytab that the TGT + obtained has not been spoofed. The keytab is checked for + entries sequentially, and the first entry with a matching + realm is used for validation. If no entry matches the realm, the last + entry in the keytab is used. This process can be used to validate + environments using cross-realm trust by placing the appropriate + keytab entry as the last entry or the only entry in the keytab file. + </para> + <para> + Default: false (IPA and AD provider: true) + </para> + <para> + Please note that the ticket validation is the first step when + checking the PAC (see 'pac_check' in the + <citerefentry> + <refentrytitle>sssd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> manual page for details). If ticket + validation is disabled the PAC checks will be skipped as well. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>krb5_renewable_lifetime (string)</term> + <listitem> + <para> + Request a renewable ticket with a total + lifetime, given as an integer immediately followed + by a time unit: + </para> + <para> + <emphasis>s</emphasis> for seconds + </para> + <para> + <emphasis>m</emphasis> for minutes + </para> + <para> + <emphasis>h</emphasis> for hours + </para> + <para> + <emphasis>d</emphasis> for days. + </para> + <para> + If there is no unit given, <emphasis>s</emphasis> is + assumed. + </para> + <para> + NOTE: It is not possible to mix units. To set + the renewable lifetime to one and a half hours, + use '90m' instead of '1h30m'. + </para> + <para> + Default: not set, i.e. the TGT is not renewable + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>krb5_lifetime (string)</term> + <listitem> + <para> + Request ticket with a lifetime, given as an + integer immediately followed by a time unit: + </para> + <para> + <emphasis>s</emphasis> for seconds + </para> + <para> + <emphasis>m</emphasis> for minutes + </para> + <para> + <emphasis>h</emphasis> for hours + </para> + <para> + <emphasis>d</emphasis> for days. + </para> + <para> + If there is no unit given <emphasis>s</emphasis> is + assumed. + </para> + <para> + NOTE: It is not possible to mix units. + To set the lifetime to one and a half + hours please use '90m' instead of '1h30m'. + </para> + <para> + Default: not set, i.e. the default ticket lifetime + configured on the KDC. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>krb5_renew_interval (string)</term> + <listitem> + <para> + The time in seconds between two checks if the TGT + should be renewed. TGTs are renewed if about half + of their lifetime is exceeded, given as an integer + immediately followed by a time unit: + </para> + <para> + <emphasis>s</emphasis> for seconds + </para> + <para> + <emphasis>m</emphasis> for minutes + </para> + <para> + <emphasis>h</emphasis> for hours + </para> + <para> + <emphasis>d</emphasis> for days. + </para> + <para> + If there is no unit given, <emphasis>s</emphasis> is + assumed. + </para> + <para> + NOTE: It is not possible to mix units. To set + the renewable lifetime to one and a half hours, + use '90m' instead of '1h30m'. + </para> + <para> + If this option is not set or is 0 the automatic + renewal is disabled. + </para> + <para> + Default: not set + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>krb5_canonicalize (boolean)</term> + <listitem> + <para> + Specifies if the host and user principal should be + canonicalized. This feature is available with MIT + Kerberos 1.7 and later versions. + </para> + + <para> + Default: false + </para> + </listitem> + </varlistentry> +</variablelist> diff --git a/src/man/include/ldap_id_mapping.xml b/src/man/include/ldap_id_mapping.xml new file mode 100644 index 0000000..25cb6e5 --- /dev/null +++ b/src/man/include/ldap_id_mapping.xml @@ -0,0 +1,317 @@ +<refsect1 id='idmap'> + <title>ID MAPPING</title> + <para> + The ID-mapping feature allows SSSD to act as a client of Active + Directory without requiring administrators to extend user attributes + to support POSIX attributes for user and group identifiers. + </para> + <para> + NOTE: When ID-mapping is enabled, the uidNumber and gidNumber + attributes are ignored. This is to avoid the possibility of conflicts + between automatically-assigned and manually-assigned values. If you + need to use manually-assigned values, ALL values must be + manually-assigned. + </para> + <para> + Please note that changing the ID mapping related configuration + options will cause user and group IDs to change. At the moment, + SSSD does not support changing IDs, so the SSSD database must + be removed. Because cached passwords are also stored in the + database, removing the database should only be performed while + the authentication servers are reachable, otherwise users might + get locked out. In order to cache the password, an authentication + must be performed. It is not sufficient to use + <citerefentry> + <refentrytitle>sss_cache</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> + to remove the database, rather the process + consists of: + <itemizedlist> + <listitem> + <para> + Making sure the remote servers are reachable + </para> + </listitem> + <listitem> + <para> + Stopping the SSSD service + </para> + </listitem> + <listitem> + <para> + Removing the database + </para> + </listitem> + <listitem> + <para> + Starting the SSSD service + </para> + </listitem> + </itemizedlist> + Moreover, as the change of IDs might necessitate the adjustment + of other system properties such as file and directory ownership, + it's advisable to plan ahead and test the ID mapping configuration + thoroughly. + </para> + + <refsect2 id='idmap_algorithm'> + <title>Mapping Algorithm</title> + <para> + Active Directory provides an objectSID for every user and group + object in the directory. This objectSID can be broken up into + components that represent the Active Directory domain identity and + the relative identifier (RID) of the user or group object. + </para> + <para> + The SSSD ID-mapping algorithm takes a range of available UIDs and + divides it into equally-sized component sections - called + "slices"-. Each slice represents the space available to an Active + Directory domain. + </para> + <para> + When a user or group entry for a particular domain is encountered + for the first time, the SSSD allocates one of the available slices + for that domain. In order to make this slice-assignment repeatable + on different client machines, we select the slice based on the + following algorithm: + </para> + <para> + The SID string is passed through the murmurhash3 algorithm to + convert it to a 32-bit hashed value. We then take the modulus of + this value with the total number of available slices to pick the + slice. + </para> + <para> + NOTE: It is possible to encounter collisions in the hash and + subsequent modulus. In these situations, we will select the next + available slice, but it may not be possible to reproduce the same + exact set of slices on other machines (since the order that they + are encountered will determine their slice). In this situation, it + is recommended to either switch to using explicit POSIX attributes + in Active Directory (disabling ID-mapping) or configure a default + domain to guarantee that at least one is always consistent. See + <quote>Configuration</quote> for details. + </para> + </refsect2> + + <refsect2 id='idmap_config'> + <title>Configuration</title> + <para> + Minimum configuration (in the <quote>[domain/DOMAINNAME]</quote> + section): + </para> + <para> +<programlisting> +ldap_id_mapping = True +ldap_schema = ad +</programlisting> + </para> + <para> + The default configuration results in configuring 10,000 slices, + each capable of holding up to 200,000 IDs, starting from 200,000 + and going up to 2,000,200,000. This should be sufficient for + most deployments. + </para> + <refsect3 id='idmap_advanced_config'> + <title>Advanced Configuration</title> + <variablelist> + <varlistentry> + <term>ldap_idmap_range_min (integer)</term> + <listitem> + <para> + Specifies the lower (inclusive) bound of the range + of POSIX IDs to use for mapping Active Directory + user and group SIDs. It is the first POSIX ID which + can be used for the mapping. + </para> + <para> + NOTE: This option is different from + <quote>min_id</quote> in that <quote>min_id</quote> + acts to filter the output of requests to this domain, + whereas this option controls the range of ID + assignment. This is a subtle distinction, but the + good general advice would be to have + <quote>min_id</quote> be less-than or equal to + <quote>ldap_idmap_range_min</quote> + </para> + <para> + Default: 200000 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_range_max (integer)</term> + <listitem> + <para> + Specifies the upper (exclusive) bound of the range + of POSIX IDs to use for mapping Active Directory + user and group SIDs. It is the first POSIX ID which + cannot be used for the mapping anymore, i.e. one + larger than the last one which can be used for the + mapping. + </para> + <para> + NOTE: This option is different from + <quote>max_id</quote> in that <quote>max_id</quote> + acts to filter the output of requests to this domain, + whereas this option controls the range of ID + assignment. This is a subtle distinction, but the + good general advice would be to have + <quote>max_id</quote> be greater-than or equal to + <quote>ldap_idmap_range_max</quote> + </para> + <para> + Default: 2000200000 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_range_size (integer)</term> + <listitem> + <para> + Specifies the number of IDs available for each slice. + If the range size does not divide evenly into the min + and max values, it will create as many complete slices + as it can. + </para> + <para> + NOTE: The value of this option must be at least as large as the + highest user RID planned for use on the Active Directory server. User + lookups and login will fail for any user whose RID is greater than + this value. + </para> + <para> + For example, if your most recently-added Active Directory user has + objectSid=S-1-5-21-2153326666-2176343378-3404031434-1107, + <quote>ldap_idmap_range_size</quote> must be at least 1108 as + range size is equal to maximal SID minus minimal SID plus one + (e.g. 1108 = 1107 - 0 + 1). + </para> + <para> + It is important to plan ahead for future expansion, as changing this + value will result in changing all of the ID mappings on the system, + leading to users with different local IDs than they previously had. + </para> + <para> + Default: 200000 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_default_domain_sid (string)</term> + <listitem> + <para> + Specify the domain SID of the default domain. This + will guarantee that this domain will always be + assigned to slice zero in the ID map, bypassing + the murmurhash algorithm described above. + </para> + <para> + Default: not set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_default_domain (string)</term> + <listitem> + <para> + Specify the name of the default domain. + </para> + <para> + Default: not set + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_autorid_compat (boolean)</term> + <listitem> + <para> + Changes the behavior of the ID-mapping algorithm + to behave more similarly to winbind's + <quote>idmap_autorid</quote> algorithm. + </para> + <para> + When this option is configured, domains will be + allocated starting with slice zero and increasing + monotonically with each additional domain. + </para> + <para> + NOTE: This algorithm is non-deterministic (it + depends on the order that users and groups are + requested). If this mode is required for + compatibility with machines running winbind, it + is recommended to also use the + <quote>ldap_idmap_default_domain_sid</quote> + option to guarantee that at least one domain is + consistently allocated to slice zero. + </para> + <para> + Default: False + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ldap_idmap_helper_table_size (integer)</term> + <listitem> + <para> + Maximal number of secondary slices that is tried when + performing mapping from UNIX id to SID. + </para> + <para> + Note: Additional secondary slices might be generated + when SID is being mapped to UNIX id and RID part of + SID is out of range for secondary slices generated so + far. If value of ldap_idmap_helper_table_size is equal + to 0 then no additional secondary slices are + generated. + </para> + <para> + Default: 10 + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect3> + </refsect2> + + <refsect2 id='well_known_sids'> + <title>Well-Known SIDs</title> + <para> + SSSD supports to look up the names of Well-Known SIDs, i.e. SIDs + with a special hardcoded meaning. Since the generic users and groups + related to those Well-Known SIDs have no equivalent in a Linux/UNIX + environment no POSIX IDs are available for those objects. + </para> + <para> + The SID name space is organized in authorities which can be seen as + different domains. The authorities for the Well-Known SIDs are + <itemizedlist> + <listitem><para>Null Authority</para></listitem> + <listitem><para>World Authority</para></listitem> + <listitem><para>Local Authority</para></listitem> + <listitem><para>Creator Authority</para></listitem> + <listitem><para>Mandatory Label Authority</para></listitem> + <listitem><para>Authentication Authority</para></listitem> + <listitem><para>NT Authority</para></listitem> + <listitem><para>Built-in</para></listitem> + </itemizedlist> + The capitalized version of these names are used as domain names when + returning the fully qualified name of a Well-Known SID. + </para> + <para> + Since some utilities allow to modify SID based access control + information with the help of a name instead of using the SID + directly SSSD supports to look up the SID by the name as well. To + avoid collisions only the fully qualified names can be used to look + up Well-Known SIDs. As a result the domain names <quote>NULL + AUTHORITY</quote>, <quote>WORLD AUTHORITY</quote>, <quote>LOCAL + AUTHORITY</quote>, <quote>CREATOR AUTHORITY</quote>, + <quote>MANDATORY LABEL AUTHORITY</quote>, <quote>AUTHENTICATION + AUTHORITY</quote>, <quote>NT AUTHORITY</quote> and + <quote>BUILTIN</quote> should not be used as domain names in + <filename>sssd.conf</filename>. + </para> + </refsect2> + +</refsect1> diff --git a/src/man/include/ldap_search_bases.xml b/src/man/include/ldap_search_bases.xml new file mode 100644 index 0000000..49dd940 --- /dev/null +++ b/src/man/include/ldap_search_bases.xml @@ -0,0 +1,36 @@ +<listitem> + <para> + An optional base DN, search scope and LDAP filter + to restrict LDAP searches for this attribute type. + </para> + <para> + syntax: +<programlisting> +search_base[?scope?[filter][?search_base?scope?[filter]]*] +</programlisting> + </para> + <para> + The scope can be one of "base", "onelevel" or "subtree". The + scope functions as specified in section 4.5.1.2 of + http://tools.ietf.org/html/rfc4511 + </para> + <para> + The filter must be a valid LDAP search + filter as specified by + http://www.ietf.org/rfc/rfc2254.txt + </para> + <para> + For examples of this syntax, please refer to the + <quote>ldap_search_base</quote> examples section. + </para> + <para> + Default: the value of + <emphasis>ldap_search_base</emphasis> + </para> + <para> + Please note that specifying scope or filter is not supported for + searches against an Active Directory Server that might yield a + large number of results and trigger the Range Retrieval extension + in the response. + </para> +</listitem> diff --git a/src/man/include/local.xml b/src/man/include/local.xml new file mode 100644 index 0000000..913ed82 --- /dev/null +++ b/src/man/include/local.xml @@ -0,0 +1,20 @@ +<refsect1 id='local'> + <title>THE LOCAL DOMAIN</title> + <para> + In order to function correctly, a domain with + <quote>id_provider=local</quote> must be created and the SSSD must + be running. + </para> + <para> + The administrator might want to use the SSSD local users instead + of traditional UNIX users in cases where the group nesting (see + <citerefentry> + <refentrytitle>sss_groupadd</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>) is needed. The local users are also useful for + testing and development of the SSSD without having to deploy + a full remote server. The <command>sss_user*</command> and + <command>sss_group*</command> tools use a local LDB storage to + store users and groups. + </para> +</refsect1> diff --git a/src/man/include/override_homedir.xml b/src/man/include/override_homedir.xml new file mode 100644 index 0000000..be6663b --- /dev/null +++ b/src/man/include/override_homedir.xml @@ -0,0 +1,84 @@ +<varlistentry> +<term>override_homedir (string)</term> +<listitem> + <para> + Override the user's home directory. You + can either provide an absolute value or a + template. In the template, the following + sequences are substituted: + <variablelist> + <varlistentry> + <term>%u</term> + <listitem><para>login name</para></listitem> + </varlistentry> + <varlistentry> + <term>%U</term> + <listitem><para>UID number</para></listitem> + </varlistentry> + <varlistentry> + <term>%d</term> + <listitem><para>domain name</para></listitem> + </varlistentry> + <varlistentry> + <term>%f</term> + <listitem><para>fully qualified user name (user@domain)</para></listitem> + </varlistentry> + <varlistentry> + <term>%l</term> + <listitem><para>The first letter of the login name.</para></listitem> + </varlistentry> + <varlistentry> + <term>%P</term> + <listitem><para>UPN - User Principal Name (name@REALM)</para></listitem> + </varlistentry> + <varlistentry> + <term>%o</term> + <listitem><para> + The original home directory retrieved + from the identity provider. + </para></listitem> + </varlistentry> + <varlistentry> + <term>%h</term> + <listitem><para> + The original home directory retrieved + from the identity provider, but in lower case. + </para></listitem> + </varlistentry> + <varlistentry> + <term>%H</term> + <listitem><para> + The value of configure option + <emphasis>homedir_substring</emphasis>. + </para></listitem> + </varlistentry> + <varlistentry> + <term>%%</term> + <listitem><para>a literal '%'</para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + This option can also be set per-domain. + </para> + <para> + example: + <programlisting> +override_homedir = /home/%u + </programlisting> + </para> + <para> + Default: Not set (SSSD will use the value + retrieved from LDAP) + </para> + <para> + Please note, the home directory from a specific override for the user, + either locally (see + <citerefentry><refentrytitle>sss_override</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>) or centrally managed IPA + id-overrides, has a higher precedence and will be used instead of the + value given by override_homedir. + </para> +</listitem> +</varlistentry> diff --git a/src/man/include/param_help.xml b/src/man/include/param_help.xml new file mode 100644 index 0000000..d28020b --- /dev/null +++ b/src/man/include/param_help.xml @@ -0,0 +1,10 @@ +<varlistentry> + <term> + <option>-?</option>,<option>--help</option> + </term> + <listitem> + <para> + Display help message and exit. + </para> + </listitem> +</varlistentry> diff --git a/src/man/include/param_help_py.xml b/src/man/include/param_help_py.xml new file mode 100644 index 0000000..a2478bf --- /dev/null +++ b/src/man/include/param_help_py.xml @@ -0,0 +1,10 @@ +<varlistentry> + <term> + <option>-h</option>,<option>--help</option> + </term> + <listitem> + <para> + Display help message and exit. + </para> + </listitem> +</varlistentry> diff --git a/src/man/include/seealso.xml b/src/man/include/seealso.xml new file mode 100644 index 0000000..747691b --- /dev/null +++ b/src/man/include/seealso.xml @@ -0,0 +1,88 @@ + <refsect1 id='see_also'> + <title>SEE ALSO</title> + <para> + <citerefentry> + <refentrytitle>sssd</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-ldap</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-ldap-attributes</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-krb5</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-simple</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-ipa</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd-ad</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <phrase condition="with_files_provider"> + <citerefentry> + <refentrytitle>sssd-files</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + </phrase> + <phrase condition="with_sudo"> + <citerefentry> + <refentrytitle>sssd-sudo</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>, + </phrase> + <citerefentry> + <refentrytitle>sssd-session-recording</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sss_cache</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sss_debuglevel</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sss_obfuscate</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sss_seed</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sssd_krb5_locator_plugin</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <phrase condition="with_ssh"> + <citerefentry> + <refentrytitle>sss_ssh_authorizedkeys</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>sss_ssh_knownhostsproxy</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, + </phrase> + <phrase condition="with_ifp"> + <citerefentry> + <refentrytitle>sssd-ifp</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry>, + </phrase> + <citerefentry> + <refentrytitle>pam_sss</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>. + <citerefentry> + <refentrytitle>sss_rpcidmapd</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> + <phrase condition="with_stap"> + <citerefentry> + <refentrytitle>sssd-systemtap</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> + </phrase> + </para> + </refsect1> diff --git a/src/man/include/service_discovery.xml b/src/man/include/service_discovery.xml new file mode 100644 index 0000000..5b96ad8 --- /dev/null +++ b/src/man/include/service_discovery.xml @@ -0,0 +1,48 @@ +<refsect1 id='service_discovery'> + <title>SERVICE DISCOVERY</title> + <para> + The service discovery feature allows back ends to automatically + find the appropriate servers to connect to using a special DNS + query. This feature is not supported for backup servers. + </para> + <refsect2 id='configuration'> + <title>Configuration</title> + <para> + If no servers are specified, the back end automatically + uses service discovery to try to find a server. Optionally, + the user may choose to use both fixed server addresses + and service discovery by inserting a special keyword, + <quote>_srv_</quote>, in the list of servers. The order + of preference is maintained. This feature is useful if, for + example, the user prefers to use service discovery whenever + possible, and fall back to a specific server when no servers + can be discovered using DNS. + </para> + </refsect2> + <refsect2 id='domain_name'> + <title>The domain name</title> + <para> + Please refer to the <quote>dns_discovery_domain</quote> + parameter in the + <citerefentry> + <refentrytitle>sssd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </citerefentry> + manual page for more details. + </para> + </refsect2> + <refsect2 id='search_protocol'> + <title>The protocol</title> + <para> + The queries usually specify _tcp as the protocol. Exceptions + are documented in respective option description. + </para> + </refsect2> + <refsect2 id='reference'> + <title>See Also</title> + <para> + For more information on the service discovery mechanism, + refer to RFC 2782. + </para> + </refsect2> +</refsect1> diff --git a/src/man/include/upstream.xml b/src/man/include/upstream.xml new file mode 100644 index 0000000..53726b2 --- /dev/null +++ b/src/man/include/upstream.xml @@ -0,0 +1,4 @@ +<refentryinfo> + <productname>SSSD</productname> + <orgname>The SSSD upstream - https://github.com/SSSD/sssd/</orgname> +</refentryinfo> |