<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
    <!ENTITY cmdname "globus-gatekeeper">
    <!ENTITY cmd "<command>globus-gatekeeper</command>">
]>
<!-- Canonical version of this document lives in 
$Header: /home/globdev/CVS/globus-packages/gatekeeper/source/globus-gatekeeper-manual.xml,v 1.3.20.1 2012/01/06 16:46:03 bester Exp $
-->


<refentry id="gram5-globus-gatekeeper">
<refmeta>
<refentrytitle>&cmdname;</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class="author">University of Chicago</refmiscinfo>
</refmeta>

<refnamediv>
<refname>&cmdname;</refname>
<refpurpose>Authorize and execute a grid service on behalf of a user</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
&cmd;
<arg>-help</arg>
<sbr/>
<arg>-conf <replaceable>PARAMETER_FILE</replaceable></arg>
<sbr/>
<arg>-test</arg>
<group>
    <arg choice="plain">-d</arg>
    <arg choice="plain">-debug</arg>
</group>
<sbr/>
<group choice="req">
    <arg choice="plain">-inetd</arg>
    <arg choice="plain">-f</arg>
</group>
<sbr/>
<group>
    <arg choice="plain">-p <replaceable>PORT</replaceable></arg>
    <arg choice="plain">-port <replaceable>PORT</replaceable></arg>
</group>
<sbr/>
<arg>-home <replaceable>PATH</replaceable></arg>
<group>
    <arg choice="plain">-l <replaceable>LOGFILE</replaceable></arg>
    <arg choice="plain">-logfile <replaceable>LOGFILE</replaceable></arg>
</group>
<arg>-lf <replaceable>LOG_FACILITY</replaceable></arg>
<sbr/>
<arg>-acctfile <replaceable>ACCTFILE</replaceable></arg>
<sbr/>
<arg>-e <replaceable>LIBEXECDIR</replaceable></arg>
<sbr/>
<arg>-launch_method
    <group choice="req">
        <arg choice="plain">fork_and_exit</arg>
        <arg choice="plain">fork_and_wait</arg>
        <arg choice="plain">dont_fork</arg>
    </group>
</arg>
<sbr/>
<arg>-grid_services <replaceable>SERVICEDIR</replaceable></arg>
<sbr/>
<arg>-globusid <replaceable>GLOBUSID</replaceable></arg>
<sbr/>
<arg>-gridmap <replaceable>GRIDMAP</replaceable></arg>
<sbr/>
<arg>-x509_cert_dir <replaceable>TRUSTED_CERT_DIR</replaceable></arg>
<sbr/>
<arg>-x509_cert_file <replaceable>TRUSTED_CERT_FILE</replaceable></arg>
<sbr/>
<arg>-x509_user_cert <replaceable>CERT_PATH</replaceable></arg>
<sbr/>
<arg>-x509_user_key <replaceable>KEY_PATH</replaceable></arg>
<sbr/>
<arg>-x509_user_proxy <replaceable>PROXY_PATH</replaceable></arg>
<sbr/>
<arg>-k</arg>
<sbr/>
<arg>-globuskmap <replaceable>KMAP</replaceable></arg>
<sbr/>
<arg>-pidfile <replaceable>PIDFILE</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
The &cmd; program is a meta-server similar to
<command>inetd</command> or <command>xinetd</command> that starts other
services after authenticating a TCP connection using GSSAPI and mapping the
client's credential to a local account.
</para>

<para>
The most common use for the &cmd; program is to
start instances of the
<citerefentry><refentrytitle>globus-job-manager</refentrytitle><manvolnum>8</manvolnum></citerefentry> service. A single &cmd;
deployment can handle multiple different service configurations by having
entries in the <filename>/etc/grid-services</filename> directory.
</para>

<para>
Typically, users interact with the &cmd;
program via client applications such as <citerefentry><refentrytitle>globusrun</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<command>globus-job-submit</command>, or tools
such as CoG jglobus or Condor-G.
</para>

<para>
The full set of command-line options to &cmd; consists of:

<variablelist>
    <varlistentry>
        <term>-help</term>
        <listitem><simpara>Display a help message to standard error and exit</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-conf <replaceable>PARAMETER_FILE</replaceable></term>
        <listitem><simpara>Load configuration parameters from
        <replaceable>PARAMETER_FILE</replaceable>. The parameters in that file
        are treated as additional command-line options.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-test</term>
        <listitem><simpara>Parse the configuration file and print out the POSIX
        user id of the &cmd; process, service home directory, service execution
        directory, and X.509 subject name and then exits.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-d</term>
        <term>-debug</term>
        <listitem><simpara>Run the &cmd; process in the foreground.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-inetd</term>
        <listitem><simpara>Flag to indicate that the &cmd; process was started
        via <command>inetd</command> or a similar super-server. If this flag is
        set and the &cmd; was not started via inetd, a warning will be printed
        in the gatekeeper log.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-f</term>
        <listitem><simpara>Flag to indicate that the &cmd; process should run
        in the foreground. This flag has no effect when the &cmd; is started
        via inetd.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-p <replaceable>PORT</replaceable></term>
        <term>-port <replaceable>PORT</replaceable></term>
        <listitem><simpara>Listen for connections on the TCP/IP port
        <replaceable>PORT</replaceable>. This option has no effect if the &cmd;
        is started via inetd or a similar service. If not specified and the
        gatekeeper is running as root, the default of <literal>2119</literal>
        is used. Otherwise, the gatekeeper defaults to an ephemeral
        port.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-home <replaceable>PATH</replaceable></term>
        <listitem><simpara>Sets the gatekeeper deployment directory to
        <replaceable>PATH</replaceable>. This is used to interpret relative
        paths for accounting files, libexecdir, certificate paths, and also to
        set the <envar>GLOBUS_LOCATION</envar> environment variable in the
        service environment. If not specified, the gatekeeper looks for service
        executables in <filename>/usr/sbin</filename>, configuration in
        <filename>/etc</filename>, and writes logs and accounting files to 
        <filename>/var/log</filename>.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-l <replaceable>LOGFILE</replaceable></term>
        <term>-logfile <replaceable>LOGFILE</replaceable></term>
        <listitem><simpara>Write log entries to
        <replaceable>LOGFILE</replaceable>. If
        <replaceable>LOGFILE</replaceable> is equal to
        <literal>logoff</literal> or <literal>LOGOFF</literal>, then logging
        will be disabled, both to file and to syslog.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-lf <replaceable>LOG_FACILITY</replaceable></term>
        <listitem><simpara>Open syslog using the <replaceable>LOG_FACILITY</replaceable>. If not specified, <literal>LOG_DAEMON</literal> will be used as the default when using syslog.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term><option>-acctfile <replaceable>ACCTFILE</replaceable></option></term>
        <listitem><simpara>Set the path to write accounting records to
        <replaceable>ACCTFILE</replaceable>. If not set, records
        will be written to the log file.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-e <replaceable>LIBEXECDIR</replaceable></term>
        <listitem><simpara>Look for service executables in
        <replaceable>LIBEXECDIR</replaceable>. If not specified, the 
        <filename>sbin</filename> subdirectory of
        the parameter to <option>-home</option> is used, or
        <filename>/usr/sbin</filename> if that is not set.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-launch_method <literal>fork_and_exit</literal>|<literal>fork_and_wait</literal>|<literal>dont_fork</literal></term>
        <listitem><simpara>Determine how to launch services. The method may be
        either <literal>fork_and_exit</literal> (the service runs completely
        independently of the gatekeeper, which exits after creating the new
        service process), <literal>fork_and_wait</literal> (the service is run
        in a separate process from the gatekeeper but the gatekeeper does not
        exit until the service terminates), or <literal>dont_fork</literal>,
        where the gatekeeper process becomes the service process via the
        <function>exec()</function> system call.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-grid_services <replaceable>SERVICEDIR</replaceable></term>
        <listitem><simpara>Look for service descriptions in
        <replaceable>SERVICEDIR</replaceable>.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-globusid <replaceable>GLOBUSID</replaceable></term>
        <listitem><simpara>Sets the <envar>GLOBUSID</envar> environment
        variable to <replaceable>GLOBUSID</replaceable>. This variable is used
        to construct the gatekeeper contact string if it can not be parsed from
        the service credential.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-gridmap <replaceable>GRIDMAP</replaceable></term>
        <listitem><simpara>Use the file at <replaceable>GRIDMAP</replaceable>
        to map GSSAPI names to POSIX user names.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-x509_cert_dir <replaceable>TRUSTED_CERT_DIR</replaceable></term>
        <listitem><simpara>Use the directory
        <replaceable>TRUSTED_CERT_DIR</replaceable> to locate trusted CA X.509
        certificates. The gatekeeper sets the environment variable
        <envar>X509_CERT_DIR</envar> to this value.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-x509_user_cert <replaceable>CERT_PATH</replaceable></term>
        <listitem><simpara>Read the service X.509 certificate from
        <replaceable>CERT_PATH</replaceable>. The gatekeeper sets the
        <envar>X509_USER_CERT</envar> environment variable to this
        value.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-x509_user_key <replaceable>KEY_PATH</replaceable></term>
        <listitem><simpara>Read the private key for the service from
        <replaceable>KEY_PATH</replaceable>. The gatekeeper sets the
        <envar>X509_USER_KEY</envar> environment variable to this
        value.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-x509_user_proxy <replaceable>PROXY_PATH</replaceable></term>
        <listitem><simpara>Read the X.509 proxy certificate from
        <replaceable>PROXY_PATH</replaceable>. The gatekeeper sets the
        <envar>X509_USER_PROXY</envar> environment variable to this
        value.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-k</term>
        <listitem><simpara>Use the <command>globus-k5</command> command
        to acquire Kerberos 5 credentials before starting the
        service.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-globuskmap <replaceable>KMAP</replaceable></term>
        <listitem><simpara>Use <replaceable>KMAP</replaceable> as the path to
        the Grid credential to kerberos initialization mapping
        file.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>-pidfile <replaceable>PIDFILE</replaceable></term>
        <listitem><simpara>Write the process id of the &cmd; to the
        file named by <replaceable>PIDFILE</replaceable>.
        </simpara></listitem>
    </varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1><title>ENVIRONMENT</title>
<para>
If the following variables affect the execution of &cmd;:

<variablelist>
    <varlistentry>
        <term>X509_CERT_DIR</term>
        <listitem><simpara>Directory containing X.509 trust anchors and signing
        policy files.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>X509_USER_PROXY</term>
        <listitem><simpara>Path to file containing an X.509
        proxy.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>X509_USER_CERT</term>
        <listitem><simpara>Path to file containing an X.509 user
        certificate.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>X509_USER_KEY</term>
        <listitem><simpara>Path to file containing an X.509 user
        key.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term>GLOBUS_LOCATION</term>
        <listitem><simpara>Default path to gatekeeper service
        files.</simpara></listitem>
    </varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1><title>Files</title>
<para>
<variablelist>
    <varlistentry>
        <term><filename>/etc/grid-services/<replaceable>SERVICENAME</replaceable></filename></term>
        <listitem><simpara>Service configuration for
        <replaceable>SERVICENAME</replaceable>.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term><filename>/etc/grid-security/grid-mapfile</filename></term>
        <listitem><simpara>Default file mapping Grid identities to POSIX
        identities.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term><filename>/etc/globuskmap</filename></term>
        <listitem><simpara>Default file mapping Grid identities to Kerberos 5
        principals.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term><filename>/etc/globus-nologin</filename></term>
        <listitem><simpara>File to disable the &cmd; program.</simpara></listitem>
    </varlistentry>
    <varlistentry>
        <term><filename>/var/log/globus-gatekeeper.log</filename></term>
        <listitem><simpara>Default gatekeeper log.</simpara></listitem>
    </varlistentry>
</variablelist>
</para>
</refsect1>

<refsect1><title>See also</title>
<para>
<citerefentry><refentrytitle>globus-k5</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 
<citerefentry><refentrytitle>globusrun</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 
<citerefentry><refentrytitle>globus-job-manager</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>