man/gssproxy.conf.5.xml - main - githubmirror/gssproxy

man/gssproxy.conf.5.xml
432 строки20 KB
Julien Rische
Fix gssproxy.conf manpage about comments
27 мар 2025, 01:52
27 мар 2025, 01:52c66e429
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<reference>
<title>GssProxy Manual pages</title>
<refentry>
    <refentryinfo>
        <productname>GSS Proxy</productname>
        <orgname>GSS-Proxy - https://github.com/gssapi/gssproxy</orgname>
    </refentryinfo>

    <refmeta>
        <refentrytitle>gssproxy.conf</refentrytitle>
        <manvolnum>5</manvolnum>
    </refmeta>

    <refnamediv id='name'>
        <refname>gssproxy.conf</refname>
        <refpurpose>GssProxy Daemon Configuration file</refpurpose>
    </refnamediv>

    <refsect1 id='description'>
        <title>DESCRIPTION</title>
        <para>
            Optional configuration directives for the gssproxy daemon.
        </para>
        <para>
            GSS-Proxy conf files are classic ini-style configuration files.
            Each option consist of a key = value pair.
            Any line starting with '#' will be treated as comment and will be ignored.
            Boolean parameters accept "1", "true", "yes" and "on" as
            positive values. All other values will be considered as negative
            values.
        </para>
        <para>
            GSS-Proxy conf files must either be named "gssproxy.conf", or be
            of the form "##-foo.conf" (that is, start with two numbers
            followed by a dash, and end in ".conf").  Files not conforming to
            this will be ignored unless specifically requested through command
            line parameters.  Within a single file, any duplicate values or
            sections will be merged.  Across multiple files, duplicates will
            generate a warning, and the first value encountered will take
            precedence (i.e., there is no merging).
        </para>
    </refsect1>

    <refsect1 id='sections'>
        <title>SECTIONS</title>
        <para>
            A section in a GSS-Proxy conf file is identified by the sectionname in square brackets ([sectionname]).
        </para>
        <para>
            There is one special section for global gssproxy settings, called
            [gssproxy].
        </para>
        <para>
            Services such as nfs, apache, ssh, etc. are represented by
            sections like [service/nfs], [service/apache], etc. and are
            identified by the "euid" setting (see below).
        </para>
    </refsect1>

    <refsect1 id='substitutions'>
	<title>VARIABLE SUBSTITUTIONS</title>

	<para>
            String parameters may contain substitution patterns. This allows gssproxy to deal with patterns for
            the storage location of keytabs or credential caches easier.
	</para>

	<para>
	    The supported patterns are:
	</para>

	<variablelist>
            <varlistentry>
                <term>%U</term>
                    <listitem><para>substitutes to the user's numeric uid (e.g. 123)</para></listitem>
            </varlistentry>
            <varlistentry>
                <term>%u</term>
                    <listitem><para>substitutes to the user's username (e.g. john).</para></listitem>
            </varlistentry>
        </variablelist>
    </refsect1>

    <refsect1 id='options'>
        <title>OPTIONS</title>
        <para>
            gssproxy supports the following options:
            <variablelist>

                <varlistentry>
                    <term>allow_any_uid (boolean)</term>
                    <listitem>
                        <para>Allow any process of any user to use this service.</para>
                        <para>Note that absent a custom socket option this
                              option may cause a service definition to mask
                              access to following services. To avoid issues
                              change the order of services in your
                              configuration file so that services with
                              allow_any_uid enabled are listed last, or define
                              a custom socket for other services.</para>
                        <para>Default: false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>allow_protocol_transition (boolean)</term>
                    <listitem>
                        <para>Allow clients to request a ticket to self for an arbitrary user.</para>
                        <para>This option controls whether s4u2self requests are allowed for the
                              requesting client. The configured keytab is used as the service
                              identity for which a ticket is requested. The KDC still needs to allow
                              the operation for it to succeed.</para>
                        <para>Default: false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>allow_constrained_delegation (boolean)</term>
                    <listitem>
                        <para>Allow clients to request a ticket to another service using an
                              evidence ticket.</para>
                        <para>This option controls whether s4u2proxy requests are allowed for
                              the requesting client. The KDC still needs to allow the operation
                              for it to succeed.</para>
                        <para>Default: false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>allow_client_ccache_sync (boolean)</term>
                    <listitem>
                        <para>Allow clients to request credentials to be sent back for better
                              caching.</para>
                        <para>This option allows the proxy, in certain circumstances, to send back
                              an additional option in the response structure of certain calls when
                              it determines that a new ticket may have been added to the internal
                              ccache. Clients can then replace their (encrypted) copy with the
                              updated ccache.</para>
                        <para>Default: false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>cred_store (string)</term>
                    <listitem>
                        <para>This parameter allows one to control in which way gssproxy should use the cred_store interface provided by GSSAPI. The parameter can be defined multiple times per service.</para>
                        <para>The syntax of the cred_store parameter is as
                            follows:
                            <![CDATA[cred_store = <cred_store_option>:<cred_store_value>]]></para>
                        <para>Currently this interface supports the following
                            options:</para>

                        <variablelist>
                            <varlistentry>
                                <term>keytab</term>
                                    <listitem><para>Defines the keytab the service should use. Example: cred_store = keytab:/path/to/keytab</para></listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>client_keytab</term>
                                    <listitem><para>Defines a client keytab the service should use. Example: cred_store = client_keytab:/path/to/client_keytab.</para></listitem>
                            </varlistentry>
                            <varlistentry>
                                <term>ccache</term>
                                    <listitem><para>Defines a credential cache the service should use. Example: cred_store = ccache:/path/to/ccache.</para></listitem>
                            </varlistentry>
                        </variablelist>

                        <para>Notably the client_keytab and the ccache setting
                            typically are used with variable substitution
                            placeholders (see above). For example:</para>

<programlisting>
    <userinput moreinfo="none">cred_store = keytab:/etc/krb5.keytab</userinput>
    <userinput moreinfo="none">cred_store = ccache:FILE:/var/lib/gssproxy/krb5cc_%U</userinput>
    <userinput moreinfo="none">cred_store = client_keytab:/var/lib/gssproxy/%U.keytab</userinput>
</programlisting>

                        <para>Default: cred_store = </para>

                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>cred_usage (string)</term>
                    <listitem>
                        <para>Allow one to restrict the kind of operations permitted for this service.</para>
                        <para>The allowed options are: initiate, accept, both</para>
                        <para>Default: cred_usage = both </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>debug (boolean)</term>
                    <listitem>
                        <para>
                            Enable debugging to syslog.  Setting to true is
                            identical to setting debug_level to 1.
                        </para>
                        <para>Default: debug = false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>debug_level (integer)</term>
                    <listitem>
                        <para>
                            Detail level at which to log debugging messages.
                            0 corresponds to no logging, while 1 turns on
                            basic debug logging.  Level 2 increases verbosity,
                            including more detailed credential verification.
                        </para>
                        <para>
                            At level 3 and above, KRB5_TRACE output is logged.
                            If KRB5_TRACE was already set in the execution
                            environment, trace output is sent to its value
		            instead. Refer to docs/KRB5_TRACE.md for more information.
                        </para>
                        <para>Default: 1 if debug is true, otherwise 0</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>enforce_flags (string)</term>
                    <listitem>
                        <para>
                            A list of GSS Request Flags that are added
                            unconditionally to every context initialization
                            call.
                            Flags can only be added to the list or removed
                            from the list by prepending a +/- sign to the
                            flag name or value.
                        </para>
                        <para>
                            Recognized flag names: DELEGATE, MUTUAL_AUTH,
                            REPLAY_DETECT, SEQUENCE, CONFIDENTIALITY,
                            INTEGRITY, ANONYMOUS
                        </para>
                        <para>Examples:
<programlisting>
    <userinput moreinfo="none">enforce_flags = +REPLAY_DETECT</userinput>
    <userinput moreinfo="none">enforce_flags = -0x0001</userinput>
</programlisting>
                        </para>
                        <para>Default: enforce_flags =</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>euid (integer or string)</term>
                    <listitem>
                        <para>Either the numeric (e.g., 48) or symbolic (e.g.,
                            apache) effective uid of a running process,
			    required to identify a service.</para>
                        <para>The "euid" parameter is imperative, any section
                            without it will be discarded.</para>
                        <para>Default: euid =</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>filter_flags (string)</term>
                    <listitem>
                        <para>
                            A list of GSS Request Flags that are filtered
                            unconditionally from every context initialization
                            call.
                            Flags can only be added to the list or removed
                            from the list by prepending a +/- sign to the
                            flag name or value.
                        </para>
                        <para>
                            NOTE: Because often gssproxy is used to withhold
                            access to credentials the Delegate Flag is filtered
                            by default. To allow a service to delegate
                            credentials use the first example below.
                        </para>
                        <para>
                            Recognized flag names: DELEGATE, MUTUAL_AUTH,
                            REPLAY_DETECT, SEQUENCE, CONFIDENTIALITY,
			    INTEGRITY, ANONYMOUS
                        </para>
                        <para>Examples:
<programlisting>
    <userinput moreinfo="none">filter_flags = -DELEGATE</userinput>
    <userinput moreinfo="none">filter_flags = -0x0001 +ANONYMOUS</userinput>
</programlisting>
                        </para>
                        <para>Default: filter_flags = +DELEGATE</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>impersonate (boolean)</term>
                    <listitem>
                        <para>Use impersonation (s4u2self + s4u2proxy) to obtain credentials</para>
                        <para>Default: impersonate = false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>kernel_nfsd (boolean)</term>
                    <listitem>
                        <para>Boolean flag that allows the Linux kernel to check if gssproxy is running (via <filename>/proc/net/rpc/use-gss-proxy</filename>).</para>
                        <para>Default: kernel_nfsd = false</para>
                    </listitem>
                    </varlistentry>

                <varlistentry>
                    <term>krb5_principal (string)</term>
                    <listitem>
                        <para>
                            The krb5 principal to be used preferred for this
                            service, if one isn't requested by the
                            application.  Note that this does not enforce use
                            of this specific name; it only sets a default.
                        </para>
                        <para>Default: krb5_principal = </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>mechs (string)</term>
                    <listitem>
                        <para>Currently only <parameter>krb5</parameter> is supported.</para>
                        <para>The "mechs" parameter is imperative, any section
                            without it will be discarded.</para>
                        <para>Default: mechs = </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>min_lifetime (integer)</term>
                    <listitem>
                        <para>Minimum lifetime of a cached credential, in seconds.</para>
                        <para>If non-zero, when gssproxy is deciding whether to use
                            a cached credential, it will compare the lifetime of the
                            cached credential to this value.  If the lifetime of the
                            cached credential is lower, gssproxy will treat the cached
                            credential as expired and will attempt to obtain a new
                            credential.
                        </para>
                        <para>Default: min_lifetime = 15</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>program (string)</term>
                    <listitem>
                        <para>If specified, this service will only match when
                              the program being run is the specified string.
                        </para>
                        <para>Programs are assumed to be specified as
                              canonical paths (i.e., no relative paths, no
                              symlinks).  Additionally, the '|' character is
                              reserved for future use and therefore forbidden.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>run_as_user (string)</term>
                    <listitem>
                        <para>The name of the user gssproxy will drop privileges to.</para>
                        <para>This option is only available in the global section.</para>
                        <para>Default: run_as_user = </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>selinux_context (string)</term>
                    <listitem>
                        <para>This option is deprecated.  Use a custom socket
                              or euid instead.
                        </para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>socket (string)</term>
                    <listitem>
                        <para>This parameter allows one to create a per-service socket file over which gssproxy client and server components communicate.
                        </para>
                        <para>When this parameter is not set, gssproxy will
                            use a compiled-in default.</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>syslog_status (boolean)</term>
                    <listitem>
                        <para>Enable per-call debugging output to the syslog.
                        This may be useful for investigating problems in
                        applications using gssproxy.</para>
                        <para>Default: syslog_status = false</para>
                    </listitem>
                </varlistentry>

                <varlistentry>
                    <term>trusted (boolean)</term>
                        <listitem><para>Defines whether this service is considered trusted. Use with caution, this enables impersonation.</para>
                            <para>Default: trusted = false</para>
                        </listitem>
                </varlistentry>

                <varlistentry>
                    <term>worker threads (integer)</term>
                    <listitem>
                        <para>Defines the amount of worker threads gssproxy will create at startup.</para>
                        <para>Default: worker threads = </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>
    </refsect1>

    <refsect1>
        <title>SEE ALSO</title>
        <para>
            <citerefentry>
                <refentrytitle>gssproxy</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry> and
            <citerefentry>
                <refentrytitle>gssproxy-mech</refentrytitle><manvolnum>8</manvolnum>
            </citerefentry>.
        </para>
    </refsect1>

</refentry>
</reference>