<?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>GssProxy Manual pages</title>
<refentry>
<refentryinfo>
<productname>GSS Proxy</productname>
<orgname>GSS-Proxy - http://fedorahosted.org/gss-proxy</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 characters behind '#' will be treated as comments 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.
</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
configuation 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_usage (string)</term>
<listitem>
<para>Allow 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>cred_store (string)</term>
<listitem>
<para>This parameter allows 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>debug (boolean)</term>
<listitem>
<para>Enable debugging to syslog.</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.
</para>
<para>Default: 1 if debug is true, otherwise 0</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>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>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 withold
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 by this service.</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>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 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>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>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>