<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">

<document>
  <header>
    <title>Configuration</title>
  </header>
  <body>
  <p>The configuration for Templeton merges the normal Hadoop configuration with
     the Templeton specific variables.  Because Templeton is designed to connect services
     that are not normally connected, the configuration is more complex than might be
     desirable.</p>

  <p>The Templeton specific configuration is split into two layers:</p>

  <ol>
   <li><strong>webhcat-default.xml</strong> - All the configuration variables
    that Templeton needs. This file sets the defaults that ship with Templeton and
    should only be changed by Templeton developers. Do not copy this file and/or
    change it to maintain local installation settings. Because webhcat-default.xml
    is present in the Templeton war file, editing a local copy of it will not change the
    configuration.</li>

   <li><strong>webhcat-site.xml</strong> - The (possibly empty) configuration
    file in which the system administrator can set variables for their Hadoop cluster.
    Create this file and maintain entries in it for configuration variables
    that require you to override default values based on your local installation.</li>
  </ol>

  <p>The configuration files are loaded in this order with later files overriding
     earlier ones.</p>

  <p><strong>Note:</strong> the Templeton server will require restart
     after any change to the configuration.</p>

  <p>To find the configuration files, Templeton first attempts to load a file from the
     <code>CLASSPATH</code> and then looks in the directory specified in the
     <code>TEMPLETON_HOME</code> environment variable.</p>

  <p>Configuration files may access the special environment variable
     <code>env</code> for all environment variables. For example, the pig executable
     could be specified using:</p>

<source>
${env.PIG_HOME}/bin/pig
</source>

  <p>Configuration variables that use a filesystem path try to have reasonable defaults.
     However, it's always safe to specify the full and complete path if there is any
     uncertainty.</p>

  <p><strong>Note:</strong> The location of the log files created by Templeton and some other properties
     of the logging system are set in the webhcat-log4j2.properties file.</p>

  <section>
  <title>Variables</title>
  <table>
  <tr><th>Name</th><th>Default</th><th>Description</th></tr>

  <tr>
    <td><strong>templeton.port</strong></td>
    <td><code>50111</code></td>
    <td>The HTTP port for the main server.</td>
  </tr>

  <tr>
    <td><strong>templeton.hadoop.config.dir</strong></td>
    <td><code>$(env.HADOOP_CONFIG_DIR)</code></td>
    <td>The path to the Hadoop configuration.</td>
  </tr>

  <tr>
    <td><strong>templeton.jar</strong></td>
    <td><code>${env.TEMPLETON_HOME}/share/webhcat/svr/webhcat-0.5.0-SNAPSHOT.jar</code></td>
    <td>The path to the Templeton jar file.</td>
  </tr>

  <tr>
    <td><strong>templeton.libjars</strong></td>
    <td><code>${env.TEMPLETON_HOME}/share/webhcat/svr/lib/zookeeper-3.4.3.jar</code></td>
    <td>Jars to add to the classpath.</td>
  </tr>

  <tr>
    <td><strong>templeton.override.jars</strong></td>
    <td><code>hdfs:///user/templeton/ugi.jar</code></td>
    <td>Jars to add to the HADOOP_CLASSPATH for all Map Reduce jobs.
        These jars must exist on HDFS.</td>
  </tr>

  <tr>
    <td><strong>templeton.override.enabled</strong></td>
    <td><code>false</code></td>
    <td>Enable the override path in templeton.override.jars</td>
  </tr>

  <tr>
    <td><strong>templeton.streaming.jar</strong></td>
    <td><code>hdfs:///user/templeton/hadoop-streaming.jar</code></td>
    <td>The hdfs path to the Hadoop streaming jar file.</td>
  </tr>

  <tr>
    <td><strong>templeton.hadoop</strong></td>
    <td><code>${env.HADOOP_PREFIX}/bin/hadoop</code></td>
    <td>The path to the Hadoop executable.</td>
  </tr>

  <tr>
    <td><strong>templeton.pig.archive</strong></td>
    <td><code>hdfs:///user/templeton/pig-0.10.1.tar.gz</code></td>
    <td>The path to the Pig archive.</td>
  </tr>

  <tr>
    <td><strong>templeton.pig.path</strong></td>
    <td><code>pig-0.10.1.tar.gz/pig-0.10.1/bin/pig</code></td>
    <td>The path to the Pig executable.</td>
  </tr>

  <tr>
    <td><strong>templeton.hcat</strong></td>
    <td><code>${env.HCAT_PREFIX}/bin/hcat</code></td>
    <td>The path to the Hcatalog executable.</td>
  </tr>

 <tr>
    <td><strong>templeton.hive.archive</strong></td>
    <td><code>hdfs:///user/templeton/hive-0.10.0.tar.gz</code></td>
    <td>The path to the Hive archive.</td>
  </tr>

  <tr>
    <td><strong>templeton.hive.path</strong></td>
    <td><code>hive-0.10.0.tar.gz/hive-0.10.0/bin/hive</code></td>
    <td>The path to the Hive executable.</td>
  </tr>

  <tr>
    <td><strong>templeton.hive.properties</strong></td>
    <td>
<code>hive.metastore.uris=thrift://localhost:9933,
hive.metastore.sasl.enabled=false</code></td>
    <td>Properties to set when running hive. To use it in a cluster with 
kerberos security enabled set hive.metastore.sasl.enabled=false and add hive.metastore.execute.setugi=true
Using localhost in metastore uri does not work with kerberos security.
</td>
  </tr>

  <tr>
    <td><strong>templeton.exec.encoding</strong></td>
    <td><code>UTF-8</code></td>
    <td>The encoding of the stdout and stderr data.</td>
  </tr>

  <tr>
    <td><strong>templeton.exec.timeout</strong></td>
    <td><code>10000</code></td>
    <td>How long in milliseconds a program is allowed to run on the
      Templeton box.
    </td>
  </tr>

  <tr>
    <td><strong>templeton.exec.max-procs</strong></td>
    <td><code>16</code></td>
    <td>The maximum number of processes allowed to run at once.</td>
  </tr>

  <tr>
    <td><strong>templeton.exec.max-output-bytes</strong></td>
    <td><code>1048576</code></td>
    <td>The maximum number of bytes from stdout or stderr stored in ram.</td>
  </tr>

  <tr>
    <td><strong>templeton.controller.mr.child.opts</strong></td>
    <td><code>-server -Xmx256m -Djava.net.preferIPv4Stack=true</code></td>
    <td>Java options to be passed to templeton controller map task.</td>
  </tr>

  <tr>
    <td><strong>templeton.exec.envs</strong></td>
    <td><code>HADOOP_PREFIX,HADOOP_HOME,JAVA_HOME,HIVE_HOME</code></td>
    <td>The environment variables passed through to exec.</td>
  </tr>

  <tr>
    <td><strong>templeton.zookeeper.hosts</strong></td>
    <td><code>127.0.0.1:5181</code></td>
    <td>ZooKeeper servers, as comma separated host:port pairs</td>
  </tr>

  <tr>
    <td><strong>templeton.zookeeper.session-timeout</strong></td>
    <td><code>30000</code></td>
    <td>ZooKeeper session timeout in milliseconds</td>
  </tr>

  <tr>
    <td><strong>templeton.callback.retry.interval</strong></td>
    <td><code>10000</code></td>
    <td>How long to wait between callback retry attempts in milliseconds</td>
  </tr>

  <tr>
    <td><strong>templeton.callback.retry.attempts</strong></td>
    <td><code>5</code></td>
    <td>How many times to retry the callback</td>
  </tr>

  <tr>
    <td><strong>templeton.storage.class</strong></td>
    <td><code>org.apache.hive.hcatalog.templeton.tool.ZooKeeperStorage</code></td>
    <td>The class to use as storage</td>
  </tr>

  <tr>
    <td><strong>templeton.storage.root</strong></td>
    <td><code>/templeton-hadoop</code></td>
    <td>The path to the directory to use for storage</td>
  </tr>

  <tr>
    <td><strong>templeton.hdfs.cleanup.interval</strong></td>
    <td><code>43200000</code></td>
    <td>The maximum delay between a thread's cleanup checks</td>
  </tr>

  <tr>
    <td><strong>templeton.hdfs.cleanup.maxage</strong></td>
    <td><code>604800000</code></td>
    <td>The maximum age of a templeton job</td>
  </tr>

  <tr>
    <td><strong>templeton.zookeeper.cleanup.interval</strong></td>
    <td><code>43200000</code></td>
    <td>The maximum delay between a thread's cleanup checks</td>
  </tr>

  <tr>
    <td><strong>templeton.zookeeper.cleanup.maxage</strong></td>
    <td><code>604800000</code></td>
    <td>The maximum age of a templeton job</td>
  </tr>

  <tr>
    <td><strong>templeton.kerberos.secret</strong></td>
    <td>A random value</td>
    <td>The secret used to sign the HTTP cookie value. The default
        value is a random value. Unless multiple Templeton instances
        need to share the secret the random value is adequate.</td>
  </tr>

  <tr>
    <td><strong>templeton.kerberos.principal</strong></td>
    <td>None</td>
    <td>The Kerberos principal to used by the server. As stated by the
        Kerberos SPNEGO specification, it should be
        <code>USER/${HOSTNAME}@{REALM}</code>. It does not have a
        default value.</td>
  </tr>

  <tr>
    <td><strong>templeton.kerberos.keytab</strong></td>
    <td>None</td>
    <td>The keytab file containing the credentials for the Kerberos
        principal.</td>
  </tr>

   <tr>
     <td><strong>webhcat.proxyuser.#USER#.hosts</strong></td>
     <td>None</td>
     <td>List of client hosts from which the '#USER#' user is allowed to perform
         'doAs' operations.

         The '#USER#' must be replaced with the username of the user who is
         allowed to perform 'doAs' operations.

         The value can be the '*' wildcard, which means every host is allowed,
         or a comma-separated list of hostnames.

         If value is a blank string or webhcat.proxyuser.#USER#.hosts is missing,
         no hosts will be allowed.

         For multiple users copy this property and replace the user name
         in the property name.</td>
   </tr>
   <tr>
     <td><strong>webhcat.proxyuser.#USER#.groups</strong></td>
     <td>None</td>
     <td>List of groups the '#USER#' user is allowed to impersonate users
         from to perform 'doAs' operations.

         The '#USER#' must be replaced with the username of the user who is
         allowed to perform 'doAs' operations.

         The value can be the '*' wildcard, which means any doAs value is
         allowed, or a comma-separated list of groups.

         If value is an empty list or webhcat.proxyuser.#USER#.groups is missing,
         every doAs call value will fail.

         For multiple users copy this property and replace the user name
         in the property name.

         The username->usergroup mapping is performed using Hadoop API which is
         controlled by hadoop.security.group.mapping property.</td>
    </tr>

  </table>
  </section>

  </body>
</document>
