You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafodion.apache.org by db...@apache.org on 2016/02/18 17:14:54 UTC
[03/13] incubator-trafodion git commit: Backup checking for changes
in the Provisioning Guide.
Backup checking for changes in the Provisioning Guide.
Project: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/commit/b763c5fa
Tree: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/tree/b763c5fa
Diff: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/diff/b763c5fa
Branch: refs/heads/master
Commit: b763c5fa6a0e152af0ae05b9b53c1f93577c5e9a
Parents: 4b71bcc
Author: Gunnar Tapper <gt...@esgyn.local>
Authored: Sun Feb 14 00:43:08 2016 -0700
Committer: Gunnar Tapper <gt...@esgyn.local>
Committed: Sun Feb 14 00:43:08 2016 -0700
----------------------------------------------------------------------
docs/provisioning_guide/pom.xml | 2 +
.../src/asciidoc/_chapters/about.adoc | 5 +-
.../src/asciidoc/_chapters/activate.adoc | 28 ++
.../src/asciidoc/_chapters/enable_security.adoc | 485 +++++++++++++++++++
.../src/asciidoc/_chapters/install.adoc | 148 ++++++
.../src/asciidoc/_chapters/install_prepare.adoc | 39 --
.../src/asciidoc/_chapters/introduction.adoc | 126 +++++
.../src/asciidoc/_chapters/prepare.adoc | 301 ++++++++++++
.../src/asciidoc/_chapters/requirements.adoc | 246 ++++++----
.../src/asciidoc/_chapters/upgrade.adoc | 30 ++
docs/provisioning_guide/src/asciidoc/index.adoc | 11 +-
docs/src/site/markdown/index.md | 2 +-
.../site/resources/images/logos/egg-logo.png | Bin 0 -> 7241 bytes
docs/src/site/site.xml | 2 +-
pom.xml | 4 +-
15 files changed, 1285 insertions(+), 144 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/pom.xml
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/pom.xml b/docs/provisioning_guide/pom.xml
index 04e865d..eb7b4c3 100644
--- a/docs/provisioning_guide/pom.xml
+++ b/docs/provisioning_guide/pom.xml
@@ -201,6 +201,8 @@
<sourceHighlighter>coderay</sourceHighlighter>
<outputDirectory>${basedir}/target</outputDirectory>
<attributes>
+ <project-version>${env.TRAFODION_VER}</project-version>
+ <build-date>${maven.build.timestamp}</build-date>
<pdf-stylesdir>${basedir}/../shared</pdf-stylesdir>
<pdf-style>trafodion</pdf-style>
<icons>font</icons>
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/about.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/about.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/about.adoc
index 87b0134..c22748a 100644
--- a/docs/provisioning_guide/src/asciidoc/_chapters/about.adoc
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/about.adoc
@@ -71,7 +71,6 @@ Lowercase letters, regardless of font, indicate variable items that you supply.
file-name
```
-<<<
* [ ] Brackets
+
Brackets enclose optional syntax items.
@@ -117,7 +116,6 @@ A vertical line separates alternatives in a horizontal list that is enclosed in
{expression | NULL}
```
-<<<
* … Ellipsis
+
An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times.
@@ -165,7 +163,6 @@ If there is no space between two items, spaces are not permitted. In this exampl
myfile.sh
```
-<<<
* Line Spacing
+
If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line.
@@ -181,7 +178,7 @@ match-value [NOT] LIKE _pattern
[cols="2*",options="header"]
|===
| Product Version | Publication Date
-| Trafodion Release 1.3.0 | To be announced.
+| Trafodion Release 1.3.0 | January 2016.
|===
== Comments Encouraged
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/activate.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/activate.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/activate.adoc
new file mode 100644
index 0000000..c52da33
--- /dev/null
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/activate.adoc
@@ -0,0 +1,28 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* 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.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+[[activate]]
+= Activate
+To be written.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/enable_security.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/enable_security.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/enable_security.adoc
new file mode 100644
index 0000000..d4d1bea
--- /dev/null
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/enable_security.adoc
@@ -0,0 +1,485 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* 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.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+[[enable-security]]
+= Enable Security
+
+If you do not enable security in Trafodion, then a client interface to Trafodion may request a username and password,
+but Trafodion ignores the user name and password entered in the client interface, and the session runs as the database *root* user,
+`DB__ROOT`, without restrictions. If you want to restrict users, restrict access to certain users only, or restrict access to an
+object or operation, then you must enable security, which enforces authentication and authorization. You can enable security
+during installation by answering the Trafodion Installer's prompts or after installation by running the `traf_authentication_setup`
+script, which enables both authentication and authorization. For more information, see
+<<enable-security-authentication-setup-script,Authentication Setup Script>> below.
+
+Trafodion does not manage user names and passwords internally but does support authentication via directory servers that support
+the OpenLDAP protocol, also known as LDAP servers. You can configure the LDAP servers during installation by answering the Trafodion
+Installer's prompts, or you can configure the LDAP servers manually after installation. For more information, please refer to
+<<enable-security-configuring-ldap-servers,Configuring LDAP Servers>> below.
+
+Once authentication and authorization are enabled, Trafodion allows users to be registered in the database and allows privileges
+on objects to be granted to users and roles (which are granted to users). Trafodion also supports component-level (or system-level)
+privileges, such as MANAGE_USERS, which can be granted to users and roles. Refer to <<enable-security-manage-users,Manage Users>> below.
+
+[[enable-security-configuring-ldap-servers]]
+== Configuring LDAP Servers
+To specify the LDAP server(s) to be used for authentication, you need to configure the text file `.traf_authentication_config`,
+located (by default) in `$MY_SQROOT/sql/scripts`. This file is a flat file, organized as a series of attribute/value pairs.
+Details on all the attributes and values accepted in the authentication configuration file and how to configure alternate locations
+can be found in <<enable-security-traf-authentication-config,.traf_authentication_config>> below.
+
+A sample template file is located in `$MY_SQROOT/sql/scripts/traf_authentication_config`.
+
+Attributes and values in the authentication configuration file are separated with a colon immediately following the attribute name.
+In general, white space is ignored but spaces may be relevant in some values. Attribute names are always case insensitive. Multiple
+instances of an attribute are specified by repeating the attribute name and providing the new value. For attributes with only one
+instance, if the attribute is repeated, the last value provided is used.
+
+```
+Attribute1: valueA
+Attribute2: valueB
+Attribute1: valueC
+```
+
+If `Attribute1` has only one instance, `valueC` is used, otherwise, `valueA` and `valueC` are both added to the list of values for `Attribute1`.
+
+Attributes are grouped into sections; this is for future enhancements. Attributes are declared in the `LOCAL` section, unless otherwise specified.
+
+NOTE: Section names, attribute names, and the general layout of the authentication configuration file are subject to change in future versions
+of Trafodion and backward compatibility is not guaranteed.
+
+Specification of your directory server(s) requires at a minimum:
+
+[cols="15%h,55%,30%a",options="header"]
+|===
+| Setting | Description | Example
+| LDAP Host Name(s) | One or more names of hosts that support the OpenLDAP protocol must be specified. Trafodion attempts to connect to all
+provided host names during the authentication process. The set of user names and passwords should be identical on all hosts to avoid unpredictable
+results. The attribute name is `LDAPHostName`. | `LDAPHostName: ldap.company.com`
+| LDAP Port Number | Port number of the LDAP server. Typically this is 389 for servers using no encryption or TLS, and 636 for servers using SSL.
+The attribute name is `LDAPPort`. | `LDAPPort: 389`
+| LDAP Unique Identifier | Attribute(s) used by the directory server that uniquely identifies the user name. You may provide one or more unique
+identifier specifiers. | `UniqueIdentifier: uid=,ou=users,dc=com`
+| Encryption Level | A numeric value indicating the encryption scheme used by your LDAP server. Values are: +
+ +
+• 0: Encryption not used +
+• 1: SSL +
+• 2: TLS | `LDAPSSL: 2` +
+ +
+If your LDAP server uses TLS you must specify a file containing the certificate used to encrypt the password. By default the Trafodion software
+looks for this file in `$MY_SQROOT/cacerts`, but you may specify a fully qualified filename, or set the environment variable `CACERTS_DIR` to another
+directory. To specify the file containing the certificate, you set the value of the attribute `TLS_CACERTFilename`, located in the Defaults section. +
+ +
+*Example* +
+```
+TLS_CACERTFilename: mycert.pem
+TLS_CACertFilename: /usr/etc/cert.pem
+```
+| Search username and password | Some LDAP servers require a known user name and password to search the directory of user names. If your environment
+has that requirement, provide these "search" values. | `LDAPSearchDN: lookup@company.com` +
+`LDAPSearchPwd: Lookup123`
+|===
+
+There are additional optional attributes that can be used to customize Trafodion authentication. As mentioned earlier, they are described in
+<<enable-security-traf-authentication-config,.traf_authentication_config>> below.
+
+You can test the authentication configuration file for syntactic errors using the `ldapconfigcheck` tool. If you have loaded the Trafodion
+environment (`sqenv.sh`), then the tool automatically checks the file at `$MY_SQROOT/sql/scripts/.traf_authentication_config`.
+If not, you can specify the file to be checked.
+
+*Example*
+
+```
+ldapconfigcheck -file myconfigfile
+File myconfigfile is valid.
+```
+
+If an error is found, then the line number with the error is displayed along with the error.
+Please refer to <<enable-security-ldapconfigcheck,ldapconfigcheck>> below for more information.
+
+NOTE: The authentication configuration file needs to be propagated to all nodes, but there is a script that does that for you described later.
+For now, you can test your changes on the local node.
+
+You can test the LDAP connection using the utility `ldapcheck`. To use this utility the Trafodion environment must be loaded (`sqenv.sh`),
+but the Trafodion instance does not need to be running. To test the connection only, you can specify any user name, and a name lookup is performed
+using the attributes in `.traf_authentication_config`.
+
+```
+ldapcheck --username=fakename@company.com
+User fakename@company.com not found
+```
+
+If `ldapcheck` reports either that the user was found or the user was not found, the connection was successful. However, if an error is reported,
+either the configuration file is not setup correctly, or there is a problem either with your LDAP server or the connection to the server. You can
+get additional error detail by including the `--verbose` option. Please refer to <<enable-security-ldapcheck,ldapcheck>> for more information.
+
+If you supply a password, `ldapcheck` attempts to authenticate the specified `username` and `password`. The example below shows the password
+for illustrative purposes, but to avoid typing the password on the command line, leave the password blank (`--password=`) and the utility
+prompts for the password with no echo.
+
+```
+ldapcheck --username=realuser@company.com --password=StrongPassword
+Authentication successful
+```
+
+[[enable-security-generate-trafodion-certificate]]
+== Generate a Trafodion Certificate
+Trafodion clients such as `trafci` encrypt the password before sending it to Trafodion. A self-signed certificate is used to encrypt the password.
+The certificate and key should be generated when the `sqgen` script is invoked. By default, the files `server.key` and `server.crt` are located
+in `$HOME/sqcert`. If those files are not present and since Trafodion clients does not send unencrypted passwords, then you need to manually generate
+those files. To do so, run the script `sqcertgen` located in `$MY_SQROOT/sql/scripts`. The script runs `openssl` to generate the certificate and key.
+
+To run openssl manually, follow the example:
+
+```
+openssl req -x509 -nodes -days 365 -subj '/C=US/ST=California/L=PaloAlto/CN=host.domain.com/O=Some Company/OU=Service Connection'
+- newkey rsa:2048 -keyout server.key -out server.crt
+```
+
+[cols="40%l,60%",options="header"]
+|===
+| Option | Description
+| -x509 | Generate a self-signed certificate.
+| -days <validity of certificate> | Make the certificate valid for the days specified.
+| -newkey rsa:<bytes> | Generate a new private key of type RSA of length 1024 or 2048 bytes.
+| -subj <certificateinfo> | Specify the information that is incorporated in the certificate.
+Each instance in a cluster should have a unique common name(`CN`).
+| -keyout <filename> | Write the newly generated RSA private key to the file specified.
+| -nodes | It is an optional parameter that specifies NOT to encrypt the private key.
+If you encrypt the private key, then you must enter the password every time the private key is used by an application.
+| -out <filename> | Write the self-signed certificate to the specified file.
+|===
+
+Both the public (`server.crt`) and private (`server.key`) files should be placed in the directory `$HOME/sqcert`. If you do not want to use
+the `HOME` directory or if you want to use different names for the private and/or public key files, then Trafodion supports environment variables
+to specific the alternate locations or names.
+
+* Trafodion first checks the environment variables `SQCERT_PRIVKEY` and `SQCERT_PUBKEY`. If they are set, Trafodion uses the fully qualified filename
+value of the environment variable.
++
+You can specify either one filename environment variable or both.
+
+* If at least one filename environment variable is not set, Trafodion checks the value of the environment variable `SQCERT_DIR`. If set,
+then the default filename `server.key` or `server.crt` is appended to the value of the environment variable `SQCERT_DIR`.
+* If the filename environment variable is not set and the directory environment variable is not set,
+then Trafodion uses the default location (`$HOME/sqcert`) and the default filename.
+
+[[enable-security-authentication-setup-script]]
+== Authentication Setup Script
+The final step to enable security is to change the value of the environment variable `TRAFODION_ENABLE_AUTHENTICATION` from `NO` to `YES`
+and turn on authorization. This is achieved by invoking the `traf_authentication_setup` script, which is located in `$MY_SQROOT/sql/scripts`.
+
+*Usage*
+
+```
+Usage: traf_authentication_setup [options]
+
+Options:
+ --file <loc> Optional location of OpenLDAP configuration file
+ --help Prints this message
+ --off Disables authentication and authorization
+ --on Enables authentication and authorization
+ --setup Enables authentication
+ --status Returns status of authentication enablement
+```
+
+[cols="30%l,90%",options="header"]
+|===
+| Option | Description
+| --file | If specified, then `filename` is copied to `$MY_SQROOT/`. Users working in their own private environment can refer to a
+site-specific configuration file from a central location.
+| --on | `traf_authentication_setup` invokes <<enable-security-ldapconfigcheck,ldapconfigcheck>> to verify the configuration file is
+syntactically correct. It also invokes <<enable-security-ldapcheck,ldapcheck>> to verify that a connection can be made to an LDAP server. +
+ +
+If both checks pass, the script sets the environment variable `TRAFODION_ENABLE_AUTHENTICATION` to `YES` in the file `$MY_SQROOT/sqenvcom.sh`,
+and propagates `sqenvcom.sh` and `.traf_authentication_config` to all nodes in the cluster. +
+ +
+The last step is to enable authorization by creating privilege-related metadata tables and set up default permissions with a call to the database.
+The list of privilege-related metadata tables, users, roles, and component privileges are logged in `$MY_SQROOT/logs/authEnable.log`. +
+ +
+Specifying `--on` requires that a valid `.traf_authentication_config` file exists and the Trafodion metadata initialized.
+| --off | If specified, then `traf_authentication_setup` sets the environment variable `TRAFODION_ENABLE_AUTHENTICATION` to `NO` in
+`$MY_SQROOT/sqenvcom.sh` and propagates the file to all the nodes in the cluster. +
+ +
+The last step is to disable authorization by removing any privilege-related metadata and permissions with a call to the database.
+The results of this operation is logged in `$MY_SQROOT/logs/authEnable.log`.
+| --setup | Use this option if the Trafodion metadata has not been initialized. This option enables authentication but does not call the database
+to create privilege-related metadata tables. Later, when Trafodion metadata is initialized, privilege-related metadata tables and default permissions
+are automatically created.
+| --status | Reports the value of the environment variable `TRAFODION_ENABLE_AUTHENTICATI+ON` in `$MY_SQROOT/sqenvcom.sh` on the current node and
+reports the status of security features in the database.
+|===
+
+*Example*
+
+```
+INFO: Start of security (authentication and authorization) script Wed Mar 25 15:12:50 PDT 2xxx.
+
+INFO: *** Trafodion security (authentication and authorization) status ***
+ Authentication is ENABLED
+ Authorization (grant/revoke) is ENABLED
+
+INFO: End of security (authorization and authentication) script Wed Mar 25 15:12:54 PDT 2xxx.
+```
+
+NOTE: Any time the environment file (`sqenvcom.sh`) is changed (and propagated to all nodes), Database Connectivity Services (DCS) must be restarted to
+pick up the new value. If the configuration file is changed, it re-reads in 30 minutes (by default), but you can have changes take effect
+immediately by restarting DCS.
+
+To restart DCS, run the scripts `stop-dcs.sh` and `start-dcs.sh`, located in `$MY_SQROOT/dcs-<x>.<y>.<z>/bin`.
+
+[[enable-security-manage-users]]
+== Manage Users
+Users are registered in the Trafodion database and are used to enforce authorization. If security is disabled, any user can register any user at any time.
+However, once security is enabled, user administration is considered a secure operation, and registration of users is restricted to `DB__ROOT` or any user
+granted the `MANAGE_USERS` component privilege. To initially register a user, connect to Trafodion with the external user mapped to `DB__ROOT`
+(also known as the Trafodion ID).
+
+When security is enabled, the `DB__ROOT` user is registered as the `TRAFODION` external user name. It is recommended that the `DB__ROOT` user be mapped
+to the external user name that is used to connect for root operations. To do this, start a `sqlci` session and perform the `ALTER USER` command, for example:
+
+```
+ALTER USER DB__ROOT SET EXTERNAL NAME trafodion_rootuser_in_ldap;
+```
+
+To learn more about how to register users, grant object and component privileges, and manage users and roles, please see the
+http://trafodion.apache.org/docs/sql_reference/index.html[Trafodion SQL Reference Manual].
+
+
+[[enable-security-traf-authentication-config]]
+== .traf_authentication_config
+The `.traf_authentication_config` file is user to enable the Trafodion security features.
+
+=== File Location
+By default, the Trafodion authentication configuration file is located in `$MY_SQROOT/sql/scripts/.traf_authentication_config`.
+If you want to store the configuration file in a different location and/or use a different filename, then Trafodion supports environment
+variables to specify the alternate location/name.
+
+Trafodion firsts checks the environment variable `TRAFAUTH_CONFIGFILE`. If set, the value is used as the fully-qualified Trafodion
+authentication configuration file.
+
+If the environment variable is not set, then Trafodion next checks the variable `TRAFAUTH_CONFIGDIR`. If set, the value is prepended to
+`.traf_authentication_config` and used as the Trafodion authentication file.
+
+If neither is set, Trafodion defaults to `$MY_SQROOT/sql/scripts/.traf_authentication_config`.
+
+=== Template
+
+```
+# To use authentication in Trafodion, this file must be configured
+# as described below and placed in $MY_SQROOT/sql/scripts and be named
+# .traf_authentication_config. You must also enable authentication by
+# running the script traf_authentication_setup in $MY_SQROOT/sql/scripts.
+#
+# NOTE: the format of this configuration file is expected to change in the
+# next release of Trafodion. Backward compatibility is not guaranteed.
+#
+SECTION: Defaults
+ DefaultSectionName: local
+ RefreshTime: 1800
+ TLS_CACERTFilename:
+SECTION: local
+
+# If one or more of the LDAPHostName values is a load balancing host, list
+# the name(s) here, one name: value pair for each host.
+ LoadBalanceHostName:
+
+# One or more identically configured hosts must be specified here,
+# one name: value pair for each host.
+ LDAPHostName:
+
+# Default is port 389, change if using 636 or any other port
+ LDAPPort:389
+
+# Must specify one or more unique identifiers, one name: value pair for each
+ UniqueIdentifier:
+
+# If the configured LDAP server requires a username and password to
+# to perform name lookup, provide those here.
+ LDAPSearchDN:
+ LDAPSearchPwd:
+
+# If configured LDAP server requires TLS(1) or SSL (2), update this value
+ LDAPSSL:0
+
+# Default timeout values in seconds
+ LDAPNetworkTimeout: 30
+ LDAPTimeout: 30
+ LDAPTimeLimit: 30
+
+# Default values for retry logic algorithm
+ RetryCount: 5
+ RetryDelay: 2
+ PreserveConnection: No
+ ExcludeBadHosts: Yes
+ MaxExcludeListSize: 3
+```
+
+[[enable-security-configuration-attributes]]
+=== Configuration Attributes
+
+[cols="20%,20%,20%l,40%",options="header"]
+|===
+| Attribute Name | Purpose | Example Value | Notes
+| `LDAPHostName` | Host name of the local LDAP server. | ldap.master.com | If more than one `LDAPHostName` entry is provided,
+then Trafodion attempts to connect with each LDAP server before returning an authentication error.
+Also see the description related to `RetryCount` and `RetryDelay` entries.
+
+| `LDAPPort` | Port number of the local LDAP server. | 345 | Must be numeric value. Related to `LDAPSSL` entry.
+Standard port numbers for OpenLDAP are as follows: +
+ +
+• Non-secure: 389 +
+• SSL: 636 +
+• TLS: 389
+
+| `LDAPSearchDN` | If a search user is needed, the search user distinguished name is specified here. | cn=aaabbb, dc=demo, dc=net |
+If anonymous search is allowed on the local server, then this attribute does not need to be specified or can be specified with no value (blank).
+To date, anonymous search is the normal approach used.
+
+| `LDAPSearchPWD` | Password for the `LDAPSearchDN` value. See that entry for details. | welcome | None.
+
+| `LDAPSSL` | A numeric value specifying whether the local LDAP server interface is unencrypted or TLS or SSL.
+Legal values are 0 for unencrypted, 1 for SSL, and 2 for TLS. For SSL/TLS, see the section below on Encryption Support. | 0 | None.
+
+| `UniqueIdentifier` | The directory attribute that contains the user's unique identifier. | uid=,ou=Users,dc=demo,dc=net |
+To account for the multiple forms of `DN` supported by a given LDAP server, specify the `UniqueIdentifier` parameter multiple times
+with different values. During a search, each `UniqueIdentifier` is tried in the order it is listed in the configuration file.
+
+| `LDAPNetworkTimeout` | Specifies the timeout (in seconds) after which the next `LDAPHostName` entry is tried, in case of no response for a connection request.
+This parameter is similar to `NETWORK_TIMEOUT` in `ldap_conf(5)`. Default value is 30 seconds. | 20 |
+The value must be a positive number or -1. Setting this to -1 results in an infinite timeout.
+
+| `LDAPTimelimit` | Specifies the time to wait when performing a search on the LDAP server for the user name. The number must be a positive integer.
+This parameter is similar to `TIMELIMIT` in `ldap_conf(5)`. Default value is 30 seconds. | 15 |
+The server may still apply a lower server-side limit on the duration of a search operation.
+
+| `LDAPTimeout` | Specifies a timeout (in seconds) after which calls to synchronous LDAP APIs aborts if no response is received.
+This parameter is similar to `TIMEOUT` in `ldap_conf(5)`. Default value is 30 seconds. | 15 |
+The value must be a positive number or -1. Setting this to -1 results in an infinite timeout.
+
+| `RetryCount` | Number of attempts to establish a successful LDAP connection. Default is 5 retries before returning an error. | 10 |
+When a failed operation is retried, it is attempted with each configured LDAP server, until the operation is successful or the number of configured retries is exceeded.
+
+| `RetryDelay` | Specifies the number of seconds to delay between retries. Default value is 2 seconds. See description of `RetryCount`. | 1 | None.
+
+| `PreserveConnection` | Specifies whether the connection to LDAP server is maintained (YES) or closed (NO) once the operation finishes. Default value is NO. | YES | None.
+
+| `RefreshTime` | Specifies the number of seconds that must have elapsed before the configuration file is reread. Default is 1800 (30 minutes). | 3600 |
+If set to zero, the configuration file is never read. The connectivity servers must be restarted for changes to take effect if this value is zero.
+This attribute is not specific to either configuration and must be defined in the DEFAULTS section.
+
+| `TLS_CACERTFilename` | Specifies the location of the certificate file for the LDAP server(s). Filename can either be fully qualified or relative to `$CACERTS_DIR`. | cert.pem |
+This attribute applies to both configurations. If a configuration does not require a certificate, then this attribute is ignored.
+This attribute must be defined in the DEFAULTS section.
+
+| `DefaultSectionName` | Specifies the configuration type that is assigned to a user by the `REGISTER USER` command if no authentication type is specified.
+In the initial Trafodion release, only one configuration is supported. | LOCAL | This attribute must be defined in the `DEFAULTS` section.
+If the `DefaultSectionName` attribute is specified, then a section by that name (or equivalent) must be defined in `.traf_ldapconfig`.
+Legal values are `LOCAL` and `ENTERPRISE`. This syntax is likely to change.
+|===
+
+
+[[enable-security-ldapcheck]]
+== ldapcheck
+
+=== Usage
+
+```
+ldapcheck [<option>]...
+<option> ::= --help|-h display usage information
+ --username=<LDAP-username>
+ --password[=<password>]
+ --primary Use first configuration
+ --local Use first configuration
+ --enterprise Use first configuration
+ --secondary Use second configuration
+ --remote Use second configuration
+ --cluster Use second configuration
+ --verbose Display non-zero retry counts
+ and LDAP errors
+```
+
+=== Considerations
+
+* Aliases for primary include enterprise and local. Aliases for secondary include cluster and remote. If no configuration is specified, primary is assumed.
+* The equals sign is required when supplying a value to username or password.
+* To be prompted for a password value with no echo, specify the password argument but omit the equals sign and value.
+* Passwords that contain special characters may need to be escaped if the password is specified on the command line or within a script file.
+* If the password keyword is not specified, only the username is checked. The tool can therefore be used to test the LDAP configuration and connection
+to the configured LDAP server(s) without knowing a valid username or password.
+
+[[enable-security-ldapconfigcheck]]
+== ldapconfigcheck
+This page describes the `ldapconfigcheck` tool, which validates the syntactic correctness of a Trafodion authentication configuration file. Trafodion does not need to be running to run the tool.
+
+=== Considerations
+If the configuration filename is not specified, then the tool looks for a file using environment variables. Those environment variables and the search order are:
+
+1. `TRAFAUTH_CONFIGFILE`
++
+A fully qualified name is expected.
+
+2. `TRAFAUTH_CONFIGDIR`
++
+Filename `.traf_authentication_config/` is appended to the specified directory
+
+3. `MY_SQROOT`
++
+`/sql/scripts/.traf_authentication_config` is appended to the value of `MY_SQROOT`.
+
+=== Errors
+One of the following is output when the tool is run. Only the first error encountered is reported.
+
+[cols="15%l,85%",options="header"]
+|===
+| Code | Text
+| 0 | File `filename` is valid.
+| 1 | File `filename` not found.
+| 2 | File: `filename` +
+ +
+Invalid attribute name on line *line-number*.
+| 3 | File: `filename` +
+ +
+Missing required value on line *line-number*.
+| 4 | File: `filename` +
+ +
+Value out of range on line *line-number*.
+| 5 | File: `filename` +
+ +
+Open of traf_authentication_config file failed.
+| 6 | File: `filename` +
+ +
+Read of traf_authentication_config file failed.
+| 7 | No file provided. Either specify a file parameter or verify environment variables.
+| 8 | TLS was requested in at least one section, but `TLS_CACERTFilename` was not provided.
+| 9 | Missing host name in at least one section. +
+ +
+Each LDAP connection configuration section must provide at least one host name.
+| 10 | Missing unique identifier in at least one section. +
+ +
+Each LDAP connection configuration section must provide at least one unique identifier.
+| 11 | At least one LDAP connection configuration section must be specified.
+| 12 | Internal error parsing `.traf_authentication_config`.
+|===
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/install.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/install.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/install.adoc
new file mode 100644
index 0000000..839384b
--- /dev/null
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/install.adoc
@@ -0,0 +1,148 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* 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.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+[[install]]
+= Install
+
+You download the Trafodion binaries from the Trafodion http://trafodion.apache.org/download.html[Download] page.
+Download the following packages:
+
+* Trafodion Installer (if planning to use the Trafodion Installer)
+* Trafodion Server
+
+NOTE: You can download and install the Trafodion Clients once you've installed and activated Trafodion. Refer to the
+http://trafodion.apache.org/docs/client_install/index.html[Trafodion Client Install Guide] for instructions.
+
+*Example*
+
+```
+$ mkdir $HOME/trafodion-download
+$ cd $HOME/trafodion-download
+$ Download the Trafodion Installer binarier
+$ wget http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-installer-1.3.0-incubating-bin.tar.gz
+--2016-02-14 04:19:40-- http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-installer-1.3.0-incubating-bin.tar.gz
+Resolving traf-builds.esgyn.com... 52.27.79.56
+Connecting to traf-builds.esgyn.com|52.27.79.56|:80... connected.
+HTTP request sent, awaiting response... 200 OK
+Length: 68813 (67K) [application/x-gzip]
+Saving to: "apache-trafodion-installer-1.3.0-incubating-bin.tar.gz"
+
+100%[=====================================================================================================================>] 68,813 124K/s in 0.5s
+
+2016-02-14 04:19:42 (124 KB/s) - "apache-trafodion-installer-1.3.0-incubating-bin.tar.gz" saved [68813/68813]
+
+$ # Download the Trafodion Server binaries
+$ wget http://traf-builds.esgyn.com/downloads/trafodion/publish/release/1.3.0/apache-trafodion-1.3.0-incubating-bin.tar.gz
+Resolving traf-builds.esgyn.com... 52.27.79.56
+Connecting to traf-builds.esgyn.com|52.27.79.56|:80... connected.
+HTTP request sent, awaiting response... 200 OK
+Length: 214508243 (205M) [application/x-gzip]
+Saving to: "apache-trafodion-1.3.0-incubating-bin.tar.gz"
+
+100%[=====================================================================================================================>] 214,508,243 3.90M/s in 55s
+
+2016-02-14 04:22:14 (3.72 MB/s) - "apache-trafodion-1.3.0-incubating-bin.tar.gz" saved [214508243/214508243]
+
+$ ls -l
+total 209552
+-rw-rw-r-- 1 centos centos 214508243 Jan 12 20:10 apache-trafodion-1.3.0-incubating-bin.tar.gz
+-rw-rw-r-- 1 centos centos 68813 Jan 12 20:10 apache-trafodion-installer-1.3.0-incubating-bin.tar.gz
+$
+```
+
+[[install-trafodion-installer]]
+== Trafodion Installer
+
+The Trafodion Installer automates most of the tasks requires to install Trafodion. First, unpack the installation tar file.
+
+*Example*
+
+```
+$ mkdir $HOME/trafodion-installer
+$ cd $HOME/trafodion-downloads
+$ tar -zxf apache-trafodion-installer-1.3.0-incubating-bin.tar.gz -C $HOME/trafodion-installer
+$ ls $HOME/trafodion-installer/installer
+bashrc_default tools traf_config_check trafodion_apache_hadoop_install traf_package_setup
+build-version-1.3.0.txt traf_add_user traf_config_setup trafodion_config_default traf_setup
+dcs_installer traf_apache_hadoop_config_setup traf_create_systemdefaults trafodion_install traf_sqconfig
+rest_installer traf_authentication_conf_default traf_getHadoopNodes trafodion_license traf_start
+setup_known_hosts.exp traf_cloudera_mods98 traf_hortonworks_mods98 trafodion_uninstaller
+$
+```
+
+The Trafodion Installer supports two different modes:
+
+1. *Guided Setup*: Prompts for information as it works through the installation process. This mode is recommended for new users.
+2. *Expert Setup*: Required information is provided in a pre-formatted bash-script configuration file, which is provided
+via a command argument when running the Trafodion Installer thereby surpressing all prompts.
++
+A template of the configuration file is available here within the installer directory: `trafodion_config_default`.
+Make a copy of the file in your directory and populate the needed information.
++
+Expert Setup is recommended for the expert user and/or for unattended installs.
+Refer to <<install-trafodion-expert-setup,Trafodion Installer: Expert Setup>> for information about how to
+populate this file.
+
+
+[[install-trafodion-installer-usage]]
+=== Trafodion Installer: Usage
+
+The following shows help for the Trafodion Installer.
+
+```
+./trafodion_install --help
+
+This script will install Trafodion. It will create a configuration
+file (if one has not been created), setup of the environment needed
+for Trafodion, configure HBase with Hbase-trx and co-processors needed,
+and install a specified Trafodion build.
+
+Options:
+ --help Print this message and exit
+ --accept_license If provided, the user agrees to accept all the
+ provisions in the Trafodion license. This allows
+ for automation by skipping the display and prompt of
+ the Trafodion license.
+ --config_file If provided, all install prompts will be
+ taken from this file and not prompted for.
+```
+
+[[install-trafodion-installer-guided-setup]]
+=== Trafodion Installer: Guided Setup
+
+You perform this step using the Trafodion Provisioning ID.
+
+The Guided Setup prompts you for the information you collected in the
+<<prepare-gather-configuration-information, Gather Configuration Information>> step in the <<prepare,Prepare>> activity.
+
+The following example shows how to install Trafodion a two-node Cloudera Hadoop cluster using Guided Setup.
+
+```
+```
+
+
+[[install-recipe-based-provisioning]]
+== Recipe-Based Provisioning
+To be written.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/install_prepare.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/install_prepare.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/install_prepare.adoc
deleted file mode 100644
index ea6bcad..0000000
--- a/docs/provisioning_guide/src/asciidoc/_chapters/install_prepare.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-////
-/**
-* @@@ START COPYRIGHT @@@
-*
-* 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.
-*
-* @@@ END COPYRIGHT @@@
- */
-////
-
-=== Special instructions:
-
-sudo yum install rpm-build
-sudo yum install apr-devel
-sudo yum install apr-util-devel
-sudo yum install doxygen
-sudo yum install gcc
-sudo yum install gcc-c++
-sudo rpm -ivv log4cxx-0.10.0-13.fc18.src.rpm
-sudo rpmbuild -ba /root/rpmbuild/SPECS/log4cxx.spec
-sudo rpm -U /root/rpmbuild/RPMS/x86_64/log4cxx<tab>
-NOTE: The rpm that was created now must be copied and installed (either rpm -U or yum install) on every node of the cluster.
-sudo rpm -qa | grep log4cxx
-
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/introduction.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/introduction.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/introduction.adoc
new file mode 100644
index 0000000..e48e329
--- /dev/null
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/introduction.adoc
@@ -0,0 +1,126 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* 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.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+[[introduction]]
+= Introduction
+
+Trafodion is a Hadoop add-on service that provides transactional SQL on top of HBase. Typically, you
+use Trafodion as the database for applications that require Online Transaction Processing (OLTP),
+Operational Data Store (ODS), and/or strong reporting capabilities. You access Trafodion using
+standard JDBC and ODBC APIs.
+
+You may choose whether to add Trafodion to an existing Hadoop environment or to create a standalone
+Hadoop environment specifically for Hadoop.
+
+[[introduction-security-considerations]]
+== Security Considerations
+
+The following users need be considered for Trafodion:
+
+* *Provisioning User*: A Linux-level user that performs the Trafodion provisioning tasks. This user ID
+requires `sudo` access and passwordless ssh among the nodes where Trafodion is installed. In addition,
+this user ID requires access to Hadoop distribution, HDFS, and HBase administrative users to change
+respective environment's configuration settings per Trafodion requirements. Refer to
+<<requirements-trafodion-provisioning-user,Trafodion Provisioning User>> for more information
+about the requirements and usage associated with this user ID.
+
+* *Runtime User*: A linux-level user under which the Trafodion software runs. This user ID must be registered
+as a user in the Hadoop Distributed File System (HDFS) to store and access objects in HDFS, HBase, and Hive.
+In addition, this user ID requires passwordless access among the nodes where Trafodion is installed.
+Refer to <<requirements-trafodion-runtime-user,Trafodion Runtime User>> for more information about this user ID.
+
+* *Trafodion Database Users*: Trafodion users are managed by the Trafodion security features (grant, revoke, etc.),
+which can be integrated with LDAP if so desired. These users are referred to as *database users* and
+do not have direct access to the operating system. Refer to
+http://trafodion.apache.org/docs/sql_reference/index.html#register_user_statement[Register User],
+http://trafodion.apache.org/docs/sql_reference/index.html#grant_statement[Grant], and other SQL statements
+in the http://trafodion.apache.org/docs/sql_reference/index.html[Trafodion SQL Reference Manual] for
+more information about managing Trafodion Database Users.
+ +
+ +
+Optionally, you can enable Trafodion Security. If you do not enable security in Trafodion, then a client interface
+to Trafodion may request a username and password, but Trafodion ignores the user name and password entered in the
+client interface, and the session runs as the database *root* user, `DB__ROOT*, without restrictions. If you want
+to restrict users, restrict access to certain users only, or restrict access to an object or operation, then you must
+enable security, which enforces authentication and authorization. Refer to
+<<enable-seurity,Enable Security>> for more information about this option.
+
+[[introduction-provisioning-options]]
+== Provisioning Options
+
+Trafodion ships with an installer that takes care of many of the installation and upgrade tasks associated with the Trafodion
+software and its requirements. Currently, the Trafodion Installer is able to install Trafodion on select Cloudera and
+Hortonworks Hadoop distributions only. Trafodion Installer limitations are noted as they apply in the different
+chapters below. For example, the Trafodion Installer is less capable on SUSE than it is on RedHat/CentOS;
+you have to install the prerequisite software packages outside the Trafodion Installer. Refer to <<trafodion_installer, Trafodion Installer>> for more information.
+
+The Trafodion Installer automates many of the tasks required to install/upgrade Trafodion, spanning from downloading and
+installing required software packages and making required changes to your Hadoop environment via creating
+the Trafodion runtime user ID to installing and starting Trafodion. It is, therefore, highly recommend that
+you use the Trafodion Installer for initial installation and upgrades of Trafodion.
+
+If, for any reason, you choose not to use the Trafodion Installer, then the different chapters provide
+step-by-step recipes for the tasks required to install/upgrade Trafodion. These steps are referred to as
+*Recipe-Based Provisioning* in this guide. It is assumed that you are well-versed in Linux and Hadoop
+administrative tasks if using Recipe-Based Provisioning.
+
+[[introduction-provisioning-activities]]
+== Provisioning Activities
+
+Trafodion provisioning is divided into the following main activities:
+
+* *<<requirements,Requirements>>*: Activities and documentation required to install the Trafodion software.
+These activities include tasks such as understanding hardware and operating system requirements,
+Hadoop requirements, what software packages that need to be downloaded, configuration settings that need to be changed,
+user IDs requirements, and so on.
+* *<<prepare,Prepare>>*: Activities to prepare the operating system and the Hadoop ecosystem to run
+Trafodion. These activities include tasks such as installing required software packages, configure
+the Trafodion Installation User, gather information about the Hadoop environment, modify configuration
+for different Hadoop services, and so forth.
+* *<<install,Install>>*: Activities related to installing the Trafodion software. These activities
+include tasks such as unpacking the Trafodion tar files, creating the Trafodion Runtime User,
+creating Trafodion HDFS directories, installing the Trafodion software, and so forth.
+* *<<upgrade,Upgrade>>*: Activities related to the upgrading the Trafodion software. These activities
+include tasks such as shutting down Trafodion, installing a new version of the Trafodion software,
+and so on. The upgrade tasks vary depending on the differences between the current and new release of
+Trafodion. For example, an upgrade may or may not include an upgrade of the Trafodion metadata.
+* *<<activate,Activate>>*: Activities related to starting the Trafodion software. These actives
+include basic management tasks such as starting and checking the status of the Trafodion components,
+performing basic smoke tests, and so forth.
+
+[[provisioning-master-node]]
+== Provisioning Master Node
+All provisioning tasks are performed from a single node in the cluster, which must be part
+of the Hadoop environment you're adding Trafodion to. This node is referred to as the
+"*Provisioning Master Node*" in this guide.
+
+The Trafodion Provisioning User must have access to all other nodes from the Provisioning
+Master Node in order to perform provisioning tasks on the cluster.
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/b763c5fa/docs/provisioning_guide/src/asciidoc/_chapters/prepare.adoc
----------------------------------------------------------------------
diff --git a/docs/provisioning_guide/src/asciidoc/_chapters/prepare.adoc b/docs/provisioning_guide/src/asciidoc/_chapters/prepare.adoc
new file mode 100644
index 0000000..66ea9d5
--- /dev/null
+++ b/docs/provisioning_guide/src/asciidoc/_chapters/prepare.adoc
@@ -0,0 +1,301 @@
+////
+/**
+* @@@ START COPYRIGHT @@@
+*
+* 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.
+*
+* @@@ END COPYRIGHT @@@
+ */
+////
+
+[[prepare]]
+= Prepare
+You need to prepare your Hadoop environment before installing Trafodion.
+
+1. <<prepare-install-optional-workstation-software,Install Optional Workstation Software>>
+2. <<configure-installation-user-id,Configure Installation User ID>>
+3. <<prepare-disable-requiretty,Disable requiretty>>
+4. <<prepare-verify-os-requirements-and-recommendations,Verify OS Requirements and Recommendations>>
+5. <<prepare-configure-ldap-identity-store,Configure LDAP Identity Store>>
+6. <<prepare-gather-configuration-information,Gather Configuration Information>>
+7. <<prepare-install-required-software-packages,Install Required Software Packages>>
+8. <<prepare-perform-recipe-based-provisioning-tasks,Perform Recipe-Based Provisioning Tasks>>
+
+[[prepare-install-optional-workstation-software]]
+== Install Optional Workstation Software
+
+If you are using a Windows workstation, then the following optional software helps installation process.
+We recommended that you pre-install the software before continuing with the Trafodion installation:
+
+* putty and puttygen (download from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html[PuTTY web site])
+* VNC client (download from http://www.realvnc.com[RealVNC web site])
+* Firefox or Chrome browser
+* SFTP client to transfer files from your workstation to the Linux server: WinSCP or FileZilla
+
+[[configure-installation-user-id]]
+== Configure Installation User ID
+
+Trafodion installation requires a user ID with these attributes:
+
+* `sudo` access per the requirements documented in <<requirements-linux-installation-user,Linux Installation User>>.
+* passwordless ssh to all nodes on the cluster where Trafodion will be installed.
+
+NOTE: You may need to request permission from your cluster-management team to obtain this type of access.
+
+The following example shows how to set up your user ID to have "passwordless ssh" abilities.
+
+Do the following on the Provision Master Node:
+
+```
+echo -e 'y\n' | ssh-keygen -t rsa -N "" -f $HOME/.ssh/id_rsa
+cat $HOME/.ssh/id_rsa.pub >> $HOME/.ssh/authorized_keys
+echo localhost $(cat /etc/ssh/ssh_host_rsa_key.pub) >> $HOME/.ssh/known_hosts
+echo "NoHostAuthenticationForLocalhost=yes" >> $HOME/.ssh/config
+chmod 600 $HOME/.ssh/config
+```
+
+After running these commands, do the following:
+
+* Copy the content of the `$HOME/.ssh/id_rsa.pub` file (public key) and append it to the
+`$HOME/.ssh/authorized_keys` file on the other nodes in your cluster.
+* Copy the `$HOME/.ssh/id_rsa` file (private key) from the current node to the `$HOME/.ssh` directory on the other nodes in the cluster.
+* Secure `$HOME/.ssh/id_rsa` on all nodes as private to yourself (`chmod 700`).
+* `ssh` to the other nodes in the cluster. Answer `y` to the prompt asking you whether to continue the connection.
+This adds the node to the `$HOME/.ssh/known_hosts` file completing the passwordless ssh setup.
+
+
+[[prepare-disable-requiretty]]
+== Disable requiretty
+You need to disable `requiretty` in `/etc/sudoers` on all nodes in the cluster
+to ensure that `sudo` commands can be run from inside the installation scripts.
+
+Comment out the `Defaults requiretty` setting in the `/etc/sudoers` file to
+ensure that the `requiretty` option is NOT being used.
+
+[[prepare-verify-os-requirements-and-recommendations]]
+== Verify OS Requirements and Recommendations
+
+Please ensure that the <<requirements-os-requirements-and-recommendations,OS Requirements and Recommendations>>
+are met for each node in the cluster where you intend to install Trafodion.
+
+[[prepare-configure-ldap-identity-store]]
+== Configure LDAP Identity Store
+
+If you plan to enable security in Trafodion, then you need to have an LDAP identity store available to perform authentication.
+The Trafodion installer prompts you to set up an authentication configuration file that points to an LDAP server (or servers),
+which enables security (that is, authentication and authorization) in the Trafodion database.
+
+If you wish to manually set up the authentication configuration file and enable security, then refer to the section on
+<<enable-security,Enable Security>>.
+
+[[prepare-gather-configuration-information]]
+== Gather Configuration Information
+
+You need to gather/decide information about your environment to aid installation Trafodion, both for the Trafodion Installer
+and for recipe-based installation. (In alphabetical order to make it easier to find information later on in the provisioning process.)
+
+[cols="15%l,30%,15%l,40%",options="header"]
+|===
+| ID^1^ | Information | Default | Notes
+| ADMIN | Administrator user name for Apache Ambari or Cloudera Manager. | admin | A user that can change configuration and restart services via the
+distribution manager's REST API.
+| BACKUP_DCS_NODES | List of nodes where to start the backup DCS Master components. | None | Blank separated FQDN list. Not needed if $ENABLE_HA = N.
+| CLOUD_CONFIG | Whether you're installing Trafodion on a cloud environment. | N | N = bare-metal or VM installation.
+| CLOUD_TYPE | What type of cloud environment you're installing Trafodion on. | None | { AWS \| OpenStack \| Other }. Not applicable for bare-metal or VM installation.
+| DCS_BUILD | Tar file containing the DCS component. | None | Not needed if using a Trafodion package installation tar file.
+| DCS_PRIMARY_MASTER_NODE | The node where the primary DCS should run. | None | The DCS Master handles JDBC and ODBC connection requests.
+| DCS_SERVER_FARM | Number of concurrent client sessions per node. | 8 | This number specifies the concurrent sessions per node to be supported. Each session could require up to 1GB of physical memory. The number can be changed post-installation. For more information,
+refer to the http://trafodion.apache.org/docs/client_install/index.html[Trafodion Client Installation Guide].
+| ENABLE_HA | Whether to run DCS in high-availability (HA) mode. | N | You need the floating IP address, the interface, and the backup nodes for DCS Master if enabling this feature.
+| FLOATING_IP | IP address if running DCS in HA mode. | None | Not needed if $ENABLE_HA = N. An FQDN name or IP address.
+| HBASE_GROUP | Linux group name for the HBASE administative user. | hbase | Required in order to provide access to select HDFS directories to this user ID.
+| HBASE_USER | Linux user name for the HBASE administative user. | hbase | Required in order to provide access to select HDFS directories to this user ID.
+| HDFS_USER | Linux user name for the HDFS administative user. | hdfs | The Trafodion Installer uses `sudo su` to make HDFS
+configuration changes under this user.
+| HOME_DIR | Root directory under which the `trafodion` home directory should be created. | \home | *Example* +
+ +
+If the home directory of the `trafodion` user is
+`/opt/home/trafodion`, then specify the root directory as `/opt/home`.
+| INIT_TRAFODION | Whether to start Trafodion after install/upgrade. | N | Does not apply to Recipe-Based Provisioning.
+| INTERFACE | Interface type used for $FLOATING_IP. | None | Not needed if $ENABLE_HA = N.
+| JAVA_HOME | Location of Java 1.7.0_65 or higher (JDK). | $JAVA_HOME setting | Fully qualified path of the JDK. For example:
+`/usr/java/jdk1.7.0_67-cloudera`
+| LDAP_CERT^2^ | Full path to TLS certificate. | None | Required of $LDAP_LEVEL = 1 or 2.
+| LDAP_HOSTS^2^ | List of nodes where LDAP Identity Store servers are running. | None | Blank separated. FQDN format.
+| LDAP_ID^2^ | List of LDAP unique identifiers. | None | Blank separated.
+| LDAP_LEVEL^2^ | LDAP Encryption Level. | 0 | 0: Encryption not used, 1: SSL, 2: TLS
+| LDAP_PASSWORD^2^ | Password for LDAP_USER. | None | If LDAP_USER is required only.
+| LDAP_PORT^2^ | Port used to communicate with LDAP Identity Store. | None | Examples: 389 for no encryption or TLS, 636 for SSL.
+| LDAP_SECURITY^2^ | Whether to enable simple LDAP authentification. | N | If Y, then you need to provide LDAP_HOSTS.
+| LDAP_USER^2^ | LDAP Search user name. | None | If required. If so, must provide LDAP_PASSWORD, too.
+| MANAGEMENT_ENABLED | Whether your installation uses separate management nodes. | N | Y if using separate management nodes for Apache Ambari or Cloudera Manager.
+| MANAGEMENT_NODES | The FQDN names of management nodes, if any. | None | Provide a blank-separated list of node names.
+| NODE_LIST | The FQDN names of the nodes where Trafodion will be installed. | None | Provide a blank-separated list of node names. The Trafodion
+Provisioning ID must have passwordless and `sudo` access to these nodes.
+| PASSWORD | Administrator password for Apache Ambari or Cloudera Manager. | admin | A user that can change configuration and restart services via the
+distribution manager's REST API.
+| REST_BUILD | Tar file containing the REST component. | None | Not needed if using a Trafodion package installation tar file.
+| SQ_ROOT | Directory where Trafodion is installed. | $HOME_DIR/trafodion | Trafodion is installed in this directory on all nodes in `$NODE_LIST`.
+| TRAF_PACKAGE | The location of the Trafodion installation package tar file or core installation tar file. | None | The package file contains the Trafodion server,
+DCS, and REST software while the core installation file contains the Trafodion server software only. If you're using a core installation file, then you need to
+record the location of the DCS and REST installation tar files, too. Normally, you perform Trafodion provisioning using a Trafodion package installation tar file.
+| TRAF_USER_PASSWORD | The password used for the `trafodion:trafodion` user ID. | traf123 | Must be 6-8 characters long.
+| URL | FQDN and port for the Distribution Manager's REST API. | None | Include `http://` or `https://` as applicable. Specify in the form:
+`<IP-address>:<port>` or `<node name>:<port>` Example: `https://susevm-1.yourcompany.local:8080`
+|===
+
+1. The ID matches the environmental variables used in the Trafodion Installation configuration file. Refer to <<install-trafodion-installer,Trafodion Installer>>
+for more information.
+2. Refer to <<enable-security,Enable Security>> for more information about these security settings.
+
+
+[[prepare-install-required-software-packages]]
+== Install Required Software Packages
+
+[[prepare-download-and-install-packages]]
+=== Download and Install Packages
+
+The step is required if you're:
+
+* Installing Trafodion on SUSE.
+* Using Recipe-Based Provisioning.
+* Can't download the required software packages using the Internet.
+
+If none of these situations exist, then we highly recommend that you use the Trafodion Installer.
+
+You perform this step as a user with `root` or `sudo` access.
+
+Install the packages listed in <<requirements-software-packages,Software Packages>> above on all nodes in the cluster. Note the special
+handling for `log4c++`. See <<prepare-build-and-install-log4cplusplus, Build and Install log4c++>> below for more information.
+
+[[prepare-build-and-install-log4cplusplus]]
+=== Build and Install log4c++
+
+You perform this step as a user with `root` or `sudo` access.
+
+This step is required regardless of the <<introduction-provisioning-options,Provisioning Options>> used.
+
+1. Perform the following steps on the Provisioning Master Node.
++
+```
+# Download required packages
+sudo yum install rpm-build
+sudo yum install apr-devel
+sudo yum install apr-util-devel
+sudo yum install doxygen
+sudo yum install gcc
+sudo yum install gcc-c++
+
+# Install the log4c++ source package
+sudo rpm -ivv log4cxx-0.10.0-13.fc18.src.rpm
+
+# Build the log4c++ RPM package
+sudo rpmbuild -ba /root/rpmbuild/SPECS/log4cxx.spec
+
+# Install the log4++ package
+sudo rpm -U /root/rpmbuild/RPMS/x86_64/log4cxx<tab>
+```
+
+2. Copy and Install the log4c++ RPM on All Nodes
++
+Use either `rpm -U` or `yum install`.
++
+*Example*
++
+```
+yum install BLAH
+```
+
+3. Verify RPM Installation on Every Node
++
+Use the following command to verify that `log4c++` has been installed on every node in the cluster.
++
+```
+sudo rpm -qa | grep log4cxx
+```
+
+[[prepare-perform-recipe-based-provisioning-tasks]]
+== Perform Recipe-Based Provisioning Tasks
+
+NOTE: This step should be skipped if you plan to use the Trafodion Installer
+
+[[prepare-modify-os-settings]]
+=== Modify OS Settings
+
+Ensure that the `/etc/security/limits.d/trafodion.conf` on each node contains the limits settings required by Trafodion.
+Refer to <<requirements-operating-system-changes,Operating System Changes>> for the required settings.
+
+[[prepare-modify-zookeeper-configuration]]
+=== Modify ZooKeeper Configuration
+
+Do the following:
+
+1. Modify the ZooKeeper configuration as follows:
++
+[cols="40%l,60%l",options="header"]
+|===
+| Attribute | Setting
+| maxClientCnxns | 0
+|===
+
+2. Restart ZooKeeper to activate the new configuration setting.
+
+[[prepare-modify-hdfs-configuration]]
+=== Modify HDFS Configuration
+
+Do the following:
+
+1. Modify the HDFS configuration as follows:
++
+[cols="40%l,60%l",options="header"]
+|===
+| Attribute | Setting
+| dfs.namenode.acls.enabled | true
+|===
+
+2. Restart HDFS to activate the new configuration setting.
+
+[[prepare-modify-hbase-configuration]]
+=== Modify HBase Configuration
+
+Do the following:
+
+1. Modify the HBase configuration as follows:
++
+[cols="40%l,60%l",options="header"]
+|===
+| Attribute | Setting
+| hbase.master.distributed.log.splitting | false
+| hbase.coprocessor.region.classes | org.apache.hadoop.hbase.coprocessor.transactional.TrxRegionObserver,org.apache.hadoop.hbase.coprocessor.transactional.TrxRegionEndpoint,
+org.apache.hadoop.hbase.coprocessor.AggregateImplementation
+| hbase.hregion.impl | org.apache.hadoop.hbase.regionserver.transactional.TransactionalRegion
+| hbase.regionserver.region.split.policy | org.apache.hadoop.hbase.regionserver.ConstantSizeRegionSplitPolicy
+| hbase.snapshot.enabled | true
+| hbase.bulkload.staging.dir | hbase-staging
+| hbase.regionserver.region.transactional.tlog | true
+| hbase.snapshot.master.timeoutMillis | 600000
+| hbase.snapshot.region.timeout | 600000
+| hbase.client.scanner.timeout.period | 600000
+| hbase.regionserver.lease.period | 600000
+| hbase.namenode.java.heapsize^a^ | 1073741824
+| hbase.secondary.namenode.java.heapsize^a^ | 1073741824
+|===
++
+a) Applies to Cloudera distributions only.
+
+2. Restart HBase to activate the new configuration setting.