4:47 p.m.
Author: shawkins
Date: 2010-06-28 10:47:10 -0400 (Mon, 28 Jun 2010)
New Revision: 2309
Added:
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml
branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml
Modified:
branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml
branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml
Log:
adding doc content and correcting javadoc
Modified: branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java
===================================================================
--- branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java 2010-06-28
14:43:04 UTC (rev 2308)
+++ branches/7.0.x/client/src/main/java/org/teiid/jdbc/TeiidStatement.java 2010-06-28
14:47:10 UTC (rev 2309)
@@ -64,7 +64,7 @@
/**
* Obtain the query planner debug log from the last command
* executed on this Statement, if it was requested with
- * OPTION DEBUG. If no debug output was requested, this
+ * SHOWPLAN DEBUG. If no debug output was requested, this
* method will return null.
* @return Debug log or null if no log exists
*/
Added:
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml
===================================================================
---
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml
(rev 0)
+++
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml 2010-06-28
14:47:10 UTC (rev 2309)
@@ -0,0 +1,28 @@
+<!--
+TODO: incorporate a performance chapter.
+
+The information about document materialization belongs in the reference though. And is
not completely correct
+w.r.t. the use of document projection.
+
+ <para>Your application can use a statement object to execute queries that
return XML documents.
+ The query must specify a valid document in VDB, or should have used SQL XML
functions
+ to create a XMl document.</para>
+ <sect3>
+ <title>XML Streaming</title>
+ <para>XML documents are streamed from Teiid Server to the Teiid JDBC
API.
+ Normally, the document never materializes in the server memory, avoiding
potential
+ out-of-memory issues and improving the first response time for large
documents.
+ When using style sheets, or XQuery, the whole document
+ must be materialized on the server. Therefore memory issues may occur for
large documents.
+ A result document can be obtained from the JDBC resultset using
<code>getSQLXML</code> method.
+ </para>
+ <para>The document is broken into pieces when being created and
streamed.
+ The maximum size of each piece in the stream can be configured with the
+ <code>"lobChunkSizeInKB"</code> system property on the
Server. The default value is 100 KB.
+ At any given time, this is the maximum amount of memory that can be held by a
particular
+ XML query against the system. In heavily loaded or memory-constrained
scenarios,
+ this value can decrease the amount of memory used. As a side effect,
streaming will occur in smaller pieces, reducing initial document response time while
+ increasing full response time (as this is less efficient).</para>
+ </sect3>
+
+ -->
\ No newline at end of file
Property changes on:
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/performance.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Modified:
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml
===================================================================
---
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml 2010-06-28
14:43:04 UTC (rev 2308)
+++
branches/7.0.x/documentation/admin-guide/src/main/docbook/en-US/content/security.xml 2010-06-28
14:47:10 UTC (rev 2309)
@@ -3,7 +3,7 @@
<chapter id="custom_security">
<title>Teiid Security</title>
<para>The Teiid system provides a range of built-in and extensible security
features to enable the
- secure access of data. </para>
+ secure access of data.</para>
<sect1>
<title>Authentication</title>
<para>JDBC clients may use simple passwords to authenticate a user.</para>
@@ -11,6 +11,13 @@
identity of the user can be discerned by the password credential alone. In
any case it is up to the configured security domain to determine whether a user can
be
authenticated.</para>
+
+ <note><para>By default, access to Teiid is NOT secure. The default login
modules are only
+ backed by file based authentication, which has a well known user
+ name and password.
+ The same is true for making connections to the Admin Console application.
+ We DO NOT recommend leaving the default security profile as defined when you
+ are exposing sensitive data.</para></note>
</sect1>
<sect1>
<title>Authorization</title>
@@ -59,6 +66,14 @@
Details of the failed attempt including invalid users, which
domains were consulted, etc. will be in the server log with appropriate
levels of severity.</para>
+ <note>
+ <para>The security-domain defined for the JDBC connection and Admin
connections are separate.
+ The default name of JDBC connection's security-domain is
"teiid-security". The default name for Admin connection
+ is "jmx-console". For the Admin connection's security domain,
the user is allowed
+ to change which LoginModule that "jmx-console" pointing to, however
should not change the name of the domain, as this name is
+ shared between the "admin-console" application.</para>
+ </note>
+
<sect2>
<title>Built-in LoginModules</title>
<para>JBossAS provides several LoginModules for common authentication needs,
such as authenticating from text files or LDAP.</para>
@@ -71,12 +86,52 @@
If you want use a your own Custom Login module, check out the Developer's
Guide for instructions.
</para>
</sect2>
+
</sect1>
- <note>
- <para>The security-domain defined for the JDBC connection and Admin
connections are separate.
- The default name of JDBC connection's security-domain is
"teiid-security". The default name for Admin connection
- is "jmx-console". For the Admin connection's security domain,
the user is allowed
- to change which LoginModule that "jmx-console" pointing to, however
should not change the name of the domain, as this name is
- shared between the "admin-console" application.</para>
- </note>
+
+ <sect1 id="connfigure_server">
+ <title>Configuring SSL</title>
+ <para>The Teiid's configuration file
+
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>,
+ contains the properties to configure SSL.</para>
+ <itemizedlist>
+ <para>There are two separate connection profiles:</para>
+ <listitem><para>JDBC Connection - The
<code>JdbcSslConfiguration</code> bean configuration defines
this.</para></listitem>
+ <listitem><para>Admin Connection - The
<code>AdminSslConfiguration</code> bean configuration defines
this.</para></listitem>
+ </itemizedlist>
+ <example><title>Example Configuration</title>
+ <programlisting><![CDATA[<bean name="JdbcSslConfiguration"
class="org.teiid.transport.SSLConfiguration">
+ <property name="sslEnabled">false</property>
+ <property name="keystoreFilename">cert.keystore</property>
+ <property name="keystorePassword">passwd</property>
+ <property name="keystoreType">JKS</property>
+ <property name="sslProtocol">SSLv3</property>
+ <property name="keymanagementAlgorithm">false</property>
+ <property name="truststoreFilename">cert.truststore</property>
+ <property name="truststorePassword">passwd</property>
+ <!-- 1-way, 2-way, anonymous -->
+ <property name="authenticationMode">1-way</property>
+ <property name="clientEncryptionEnabled">true</property>
+</bean>]]></programlisting>
+</example>
+ <orderedlist>
+ <title>Properties</title>
+ <listitem><para>sslEnabled - true|false, SSL usage either turned
ON or OFF </para></listitem>
+ <listitem><para>sslProtocol- Type of SSL protocol to be used.
Default is SSLv3</para></listitem>
+ <listitem><para>keystoreType - Keystore type created by the
keytool. Default "JKS" is used.</para></listitem>
+ <listitem><para>authenticationMode - anonymous|1-way|2-way, Type
of SSL mode, see
+ above about different <link linkend="ssl_modes">SSL
modes</link> available.</para></listitem>
+ <listitem><para>keymanagementAlgorithm - Type of key algorithm
used. Default
+ is based upon the VM, e.g. "SunX509"</para></listitem>
+ <listitem><para>keystoreFilename - The file name of the keystore,
which contains the
+ private key of the Server. This must be available in the classpath of Teiid
Server</para></listitem>
+ <listitem><para>keystorePassword - password for the
keystore.</para></listitem>
+ <listitem><para>truststoreFilename - if
"authenticationMode" is chosen
+ as "2-way", then this property must be provided. This is the
truststore that contains the
+ public key for the client. Depending upon how you created the keystore and
truststores,
+ this may be same file as defined under "keystoreFilename"
property.</para></listitem>
+ <listitem><para>truststorePassword - password for the truststore.
</para></listitem>
+ </orderedlist>
+
+ </sect1>
</chapter>
\ No newline at end of file
Modified: branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml
===================================================================
--- branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml 2010-06-28
14:43:04 UTC (rev 2308)
+++ branches/7.0.x/documentation/reference/src/main/docbook/en-US/Reference.xml 2010-06-28
14:47:10 UTC (rev 2309)
@@ -53,6 +53,7 @@
<xi:include href="content/scalar_functions.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/procedures.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/transaction_support.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="content/entitlements.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/system_schema.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/translators.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="content/federated_planning.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
Added:
branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml
===================================================================
---
branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml
(rev 0)
+++
branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml 2010-06-28
14:47:10 UTC (rev 2309)
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
+%CustomDTD;
+]>
+<chapter id="entitlements">
+ <title>Data Roles</title>
+ <para>Data roles, also called entitlements, are sets of permissions that are
defined
+ per VDB that dictate data access (create, read, update, delete). The use of data
roles is controlled system wide with the property in
+
<code><jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml</code>
file
+ in bean configuration section of <code>RuntimeEngineDeployer</code> with
property <code>useEntitlements</code>.</para>
+
+ <para>Once data roles are enabled, the access permissions defined in a VDB will
be enforced by the Teiid Server.</para>
+
+ <sect1>
+ <title>Permissions</title>
+ <orderedlist>
+ <para>To process a <code>SELECT</code> statement or a stored
procedure execution, the user account requires the following access rights:</para>
+ <listitem> <para><code>READ</code> - on the Table(s)
being accessed or the procedure being called.</para></listitem>
+ <listitem> <para><code>READ</code> - on every column
referenced.</para></listitem>
+ </orderedlist>
+
+ <orderedlist>
+ <para>To process an <code>INSERT</code> statement, the user
account requires the following access rights:</para>
+ <listitem> <para><code>CREATE</code> - on the Table
being inserted into.</para></listitem>
+ <listitem> <para><code>CREATE</code> - on every column
being inserted on that Table.</para></listitem>
+ </orderedlist>
+
+ <orderedlist>
+ <para>To process an <code>UPDATE</code> statement, the user
account requires the following access rights:</para>
+ <listitem> <para><code>UPDATE</code> - on the Table
being updated.</para></listitem>
+ <listitem> <para><code>UPDATE</code> - on every column
being updated on that Table.</para></listitem>
+ <listitem> <para><code>READ</code> - on every column
referenced in the criteria.</para></listitem>
+ </orderedlist>
+
+ <orderedlist>
+ <para>To process a <code>DELETE</code> statement, the user
account requires the following access rights:</para>
+ <listitem> <para><code>DELETE</code> - on the Table
being deleted.</para></listitem>
+ <listitem> <para><code>READ</code> - on every column
referenced in the criteria.</para></listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1>
+ <title>XML Definition</title>
+ <para>Data roles are defined inside the <code>vdb.xml</code> file
(inside the .vdb Zip archive under META-INF/vdb.xml) if you used Designer.
+ This example will show a sample "vdb.xml" file with few simple data
rules.</para>
+
+ <para>For example, if a VDB defines a table "TableA" in schema
"modelName" with columns (column1, column2) - note that the column types do not
matter. And we wish to define three roles "RoleA", "RoleB",
"RoleC" with following permissions:
+ <orderedlist>
+ <listitem><para>RoleA has privileges to read, write access to TableA, but
can not delete.</para></listitem>
+ <listitem><para>RoleB has no privileges that allow access to
TableA</para></listitem>
+ <listitem><para>RoleC has privileges that only allow read access to
TableA.column1</para></listitem>
+ </orderedlist>
+ </para>
+ <example><title>vdb.xml defining RoleA, RoleB, and RoleC</title>
+ <programlisting><![CDATA[<?xml version="1.0"
encoding="UTF-8"?>
+<vdb name="sample" version="1">
+
+ <model name="modelName">
+ <source name="source-name" translator-name="oracle"
connection-jndi-name="java:myDS" />
+ </model>
+
+ <data-policy name="RoleA">
+ <description>Allow all, except Delete</description>
+
+ <permission>
+ <resource-name>modelName.TableA</resource-name>
+ <allow-create />
+ <allow-read />
+ <allow-update />
+ </permission>
+
+ <permission>
+ <resource-name>modelName.TableA.colum1</resource-name>
+ <allow-create />
+ <allow-read />
+ <allow-update />
+ </permission>
+
+ <permission>
+ <resource-name>modelName.TableA.column2</resource-name>
+ <allow-create />
+ <allow-read />
+ <allow-update />
+ </permission>
+
+ <mapped-role-name>role1</mapped-role-name>
+
+ </data-policy>
+
+ <data-policy name="RoleC">
+ <description>Allow read only</description>
+
+ <permission>
+ <resource-name>modelName.TableA</resource-name>
+ <allow-read />
+ </permission>
+
+ <permission>
+ <resource-name>modelName.TableA.colum1</resource-name>
+ <allow-read />
+ </permission>
+
+ <mapped-role-name>role2</mapped-role-name>
+ </data-policy>
+</vdb>]]></programlisting>
+</example>
+ <para>The above XML defined two data roles, "RoleA" which allows
everything except delete on the table, "RoleC" that
+ allows only read operation on the table. Since Teiid uses deny by default, there is no
explict data-policy entry needed for "RoleB". The "mapped-role-name"
defines the "role" to whom these policies are applicable. Each data-policy
+ must define a "role" to be enforced by the Teiid Server.</para>
+
+ <para>For assigning the roles to your users, in the JBoss AS,
+ check out the instructions for the selected Login Module. Check "Admin
Guide" for configuring Login Modules.</para>
+
+ <para>"vdb.xml" file is checked against the schema file
<code>vdb-deployer.xsd</code>, check the documents sections of the Teiid kit
+ to find a copy of the schema file.</para>
+
+ <note><para>Currently there is no GUI tooling support in the Designer or
any other management tool to create this data roles
+ permissions xml, however this is in our roadmap for future releases to
provide.</para></note>
+ </sect1>
+
+</chapter>
\ No newline at end of file
Property changes on:
branches/7.0.x/documentation/reference/src/main/docbook/en-US/content/entitlements.xml
___________________________________________________________________
Name: svn:mime-type
+ text/plain