JBoss.orgCommunity Documentation

Teiid - Scalable Information Integration

Teiid Administrator's Guide


Legal Notice

1. Installation Guide
1.1. Installation
1.2. Directory Structure Explained
1.2.1. /deploy/teiid/teiid-jboss-beans.xml
1.2.2. /deploy/teiid/connectors
1.2.3. /conf/props
1.2.4. /conf/jboss-teiid-log4j.xml
1.2.5. admin-console.war
1.2.6. /deployers/teiid.deployer
1.2.7. lib
1.2.8. teiid-examples
1.2.9. teiid-docs
2. Deploying VDBs in Teiid 7
2.1. Deploying a VDB
2.1.1. Direct File Deployment
2.1.2. Admin Console Deployment (Web)
2.1.3. AdminShell Deployment
2.1.4. Admin API Deployment
2.2. Deploying VDB Dependencies
2.2.1. Creating An Oracle Data Source
2.2.2. Creating A File Data Source
2.3. VDB Versioning
2.3.1. Deployment Scenarios
2.4. Migrating VDBs from 6.x
3. Teiid Security
3.1. Authentication
3.2. Authorization
3.3. Encryption
3.4. LoginModules
3.4.1. Built-in LoginModules
3.5. Configuring SSL
4. Logging
4.1. General Logging
4.1.1. Logging Contexts
4.2. Command Logging
4.3. Audit Logging
5. Teiid Admin Console
5.1. What can be monitored and/or configured?
5.1.1. Configuration
5.1.2. Metrics
5.1.3. Control (Operations)
5.1.4. Deploying the VDB
6. AdminShell
6.1. Introduction
6.1.1. Download
6.2. Getting Started
6.2.1. Essential Rules
6.2.2. Help
6.2.3. Basic Commands
6.3. Executing a script file
6.4. Log File and Recorded Script file
6.5. Default Connection Properties
6.6. Handling Multiple Connections
A. AdminShell Frequently Asked Questions
B. Other Scripting Environments
C. System Properties

Starting with the 7.0 release Teiid needs to be installed into an existing JBoss AS installation, which is entirely different from previous versions.


Teiid does not support the "embedded" mode in 7.1 version. ("embedded" will be coming in a future release).

Steps to install Teiid

  1. Download the JBoss AS 5.1.0 application server. Install the server by unzipping into a known location. Ex: /apps/jboss-5.1.0

  2. Download Teiid 7.1. Unzip the downloaded artifact inside any "profile" in the JBoss AS installation. Teiid 7.1 uses a JBoss AS service called the "profile service" that is only installed in "default" and "all" profiles, so installing into one of these profiles is required. The default profile is the typical installation location, for example "<jboss-install>/server/default". The Teiid runtime directory structure matches JBoss profiles directly - it is just an overlay.

  3. Start the JBoss AS server by executing "<jboss-install>/bin/run.sh" if you installed in the "default" profile. Otherwise use "<jboss-install>/bin/run.sh -c <profilename>"

  4. That it!. JBoss AS and Teiid are now installed and running. See below instructions to customize various settings.

  5. Once VDBs have been deployed, users can now connect their JDBC applications to Teiid. If you need help on connecting your application to the Teiid using JDBC check out the "Client Developer's Guide".

A VDBis the primary means to define a Virtual Database in Teiid. A user can create a VDB using Teiid Designer or follow the instructions in the Reference Guide to create a "Dynamic VDB" without Teiid Designer.

Apart from deploying the VDB, the user is also responsible for providing all the necessary dependent libraries, configuration for creating the data sources that are needed by the Schemas (models) defined in "META-INF/vdb.xml" file inside your VDB. This section shows you a sample VDB configuration needed.

For example, if you are trying to integrate Oracle and File sources in your VDB, then you are responsible for providing the JDBC driver for the Oracle source, and any necessary documents and configuration that are needed by the File Translator.

Once the VDB and its dependencies are deployed, then client applications can connect using the JDBC API. If there are any errors in the deployment, a connection attempt will not be successful and a message will be logged. You can use the admin-console tool or check the log files for errors and correct them before proceeding.

  1. Copy the Oracle JDBC JAR file into "<jboss-install>/server/<profile>/lib" directory

  2. Create a "data source" to the Oracle instance in the JBoss container. This typically done by creating "xxx-ds.xml" file and copying this file to the "<jboss-install>/server/%lt;profile>/deploy" directory. The following shows a "-ds.xml" file template for Oracle. You can also use admin-console to create this data source.

    <?xml version="1.0" encoding="UTF-8"?>
        <!-- uncomment to enable interleaving <interleaving/> -->
        <xa-datasource-property name="URL">jdbc:oracle:oci8:@tc</xa-datasource-property>
        <xa-datasource-property name="User">scott</xa-datasource-property>
        <xa-datasource-property name="Password">tiger</xa-datasource-property>
        <!-- Uses the pingDatabase method to check a connection is still valid before handing it out from the pool -->
        <!-- Checks the Oracle error codes and messages for fatal errors -->
        <!-- Oracles XA datasource cannot reuse a connection outside a transaction once enlisted in a global transaction and vice-versa -->
          <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->

There are templates for all the data sources in the "<jboss-install>/docs/examples/jca" directory.

VDB Versioning is a feature that allows multiple versions of a VDB to be deployed at the same time with additional support to determine which version will be used. When a user connects to Teiid the desired VDB version can be set as a connection property (See the Client Developers Guide). If a specific version is set, then only that VDB may be connected to. If no version is set, then the deployed VDBs are searched for the appropriate version. This feature helps support more fluid migration scenarios.

Setting the version can either be done in the vdb.xml, which is useful for dynamic vdbs, or through a naming convention of the deployment file - vdbname.version.vdb, e.g. marketdata.2.vdb. The deployer is responsible for choosing an appropriate version number. If the version number is same as an existing VDB existing connections to the previous VDB will remain valid and any new connections will be made to the new VDB - note that the new VDB may be able to use cache entries of the previous VDB.

Once deployed a VDB has an updatable property called connection type, which is used to determine what connections can be made to the VDB. The connection type can be one of:

The connection type may be changed either through the AdminConsole or the AdminAPI.

VDBs from prior release contain an older configuration file version that is no longer supported. You can use the migration utility (bin/migrate.sh or bin/migrate.bat) supplied with the AdminShell download to update these VDBs for use with Teiid 7. Note - XML and File based sources from previous releases have changed, and require manual changes to the VDB.

The Teiid system provides a range of built-in and extensible security features to enable the secure access of data.

LoginModules are an essential part of the JAAS security framework and provide Teiid customizable user authentication and the ability to reuse existing LoginModules defined for JBossAS. See JBossAS Security for general information on configuring security in JBossAS.

Teiid can be configured with multiple named application policies that group together relevant LoginModules. Each of these application policy (or domains) names can be used to fully qualify user names to authenticate only against that domain.  The format for a qualified name is username@domainname.

If a user name is not fully qualified, then the installed domains will be consulted in order until a domain successfully or unsuccessfully authenticates the user.

If no domain can authenticate the user, the logon attempt will fail. Details of the failed attempt including invalid users, which domains were consulted, etc. will be in the server log with appropriate levels of severity.


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.

The Teiid's configuration file <jboss-install>/server/<profile>/deploy/teiid/teiid-jboss-beans.xml, contains the properties to configure SSL.


  1. sslEnabled - true|false, SSL usage either turned ON or OFF

  2. sslProtocol- Type of SSL protocol to be used. Default is SSLv3

  3. keystoreType - Keystore type created by the keytool. Default "JKS" is used.

  4. authenticationMode - anonymous|1-way|2-way, Type of SSL mode, see above about different SSL modes available.

  5. keymanagementAlgorithm - Type of key algorithm used. Default is based upon the VM, e.g. "SunX509"

  6. 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

  7. keystorePassword - password for the keystore.

  8. 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.

  9. truststorePassword - password for the truststore.

The Teiid system provides a wealth of information via logging. To control logging level, contexts, and log locations, you should be familiar with log4j and the container's jboss-log4j.xml configuration file. Teiid also provides a <profile>/conf/jboss-teiid-log4j.xml containing much of information from chapter.

All the logs produced by Teiid are prefixed by "org.teiid". This makes it extremely easy to control of of Teiid logging from a single context. Note however that changes to the log configuration file require a restart to take affect

While all of Teiid's logs are prefixed with "org.teiid", there are more specific contexts depending on the functional area of the system. Note that logs originating from third-party code, including integrated org.jboss components, will be logged through their respective contexts and not through org.teiid. See the table below for information on contexts relevant to Teiid. See the container's jboss-log4j.xml for a more complete listing of logging contexts used in the container.




Third-party transaction manager. This will include information about all transactions, not just those for Teiid.


Root context for all Teiid logs. Note: there are potentially other contexts used under org.teiid than are shown in this table.


Query processing logs. See also org.teiid.PLANNER for query planning logs.


Query planning logs.


Session/Authentication events - see also AUDIT logging


Events related to the socket transport.


Events related to work management and system start/stop.


Connector logs.


Buffer and storage management logs.


Detail log of all transaction operations.


See command logging


See audit logging


Admin API logs.

The Teiid Admin Console is a web based administrative and monitoring tool for Teiid. Teiid's Admin Console is built using the Embedded JOPR library and adds a additional plugin into the Embeeded JOPR program already available in the JBoss AS.

Here are the steps to follow to install Teiid

The AdminShell tooling provides scripting based programming environments that enable user to access, monitor and control a Teiid Server. Both the command line and graphical console tools are built on functionality provide by the Groovy ( http://groovy.codehaus.org/ ) project. The AdminShell tools can be used in ad-hoc scripting mode or to run pre-defined scripts.

AdminShell features:

  1. fully functional programming environment with resource flow control and exception management. See Groovy docs for the full power of the language.

  2. quick administrative tool. The user can connect to a running Teiid Server and invoke any of the AdminAPI methods, such as "deployVDB" or "stopConnectionFactory", to control the Teiid System. Since this can be script driven, these tasks can be automated and re-run at a later time.

  3. simplified data access tool. The user can connect to a VDB, issue any SQL commands, and view the results of the query via Groovy Sql extensions.

  4. migration tool. This can be used to develop scripts like moving the Virtual Databases (VDB), Connection Factories, and Configuration from one development environment to another. This will enable users to test and automate their migration scripts before production deployments.

  5. testing tool. The JUnit ( http://junit.org ) test framework is built in, see Groovy Unit Tests. User can write regression tests for checking system health, or data integrity that can be used to validate a system functionality automatically instead of manual verification by QA personnel.

To learn the basics of Groovy take a look at their documents and tutorials on their website.

Basic knowledge of the Java programming language and types is required in order to effectively design and develop scripts using the AdminShell. To learn Java language find learning resources at http://java.sun.com.

You can learn about the Teiid AdminAPI either using “adminHelp()” function or by using the JavaDocs.

AdminShell is a specialized version of Groovy which works in several different modes: interactive shell, graphical console, or script run mode. In interactive shell mode (launched via adminshell), the user can invoke connect to a live Teiid system and issue any ad-hoc commands to control the system. The interactive buffer can be used to develop a script and the interactive session input and output can be captured into a log file, more on this later in the document.

In graphical mode (lanched via adminshell-console), the user can develop and run scripts using a text editor that supports syntax highlighting.

In the script run mode, the user can execute/play back previously developed scripts. This mode especially useful to automate any testing or to perform any repeated configurations/migrations changes to a Teiid system.

To use AdminShell successfully, there are some basic syntactical rules to keep in mind.

To execute the commands and arbitrary script in interactive mode you enter them first and press enter to execute, then enter the next line, so on.

To exit the tool in the interactive mode, first disconnect if you are connected to the Teiid system by executing “disconnect();” then type "exit". In the script mode, when execution of the script finishes the tool will exit automatically, however you still have to disconnect from Teiid system in the script.

Note: If SSL is turned on the Teiid server, you would need to adjust the connection URL and the client SSL settings as necessary (typically this will only be needed for 2-way SSL).

Using AdminShell, a user can actively manage more than one connection to a single or multiple Teiid systems. For example, two separate connections can be maintained, one to the development server and one to the integration server at the same time. This is possible because AdminShell supports a feature called named connections.

Every time a connection is made, the connection has an explicit or an implicitly assigned name.   If another connect command is executed then a new connection is made with a unique name and execution will be switched to use the new connection.   The previous connection will be held as it is in its current state, and will not be closed.

You can use the following command to find out the current connection's name

name = getConnectionName();    

Knowing the names of the connection that user is working with is important to switch the active connection to a previous connection. To switch the active connection, use the following command and supply the name of the connection to be used


If user supplies the same name as the active connection as they are currently participating in, then this operation will simply return with out any modifications. There is no limitation the number of simultaneous connections.

The following shows an example of using and switching between two connections.

// creates a connection 

//capture the connection name
conn1 = getConnectionName();


// creates a second connection 

conn2 = getConnectionName();


// switch the connection to "conn1"

// close the connection in the "conn1"
A.1. Why won't the adminhelp command work in the Console tool?
A.2. Are there any pre-built scripts available?
A.3. I have written a very useful script to do XYZ, I would like this to be part of the distribution?
A.4. What is different between "connectAsAdmin()" and "connect()"?
A.5. Is IDE support available for writing the scripts?
A.6. Is debugging support available?


Why won't the adminhelp command work in the Console tool?

The Console environment does not understand Shell commands (load, help, adminhelp, etc.), since they are not directly supported by Groovy. In the Console you should use the equivalent functional form / Groovy, e.g. instead of adminhelp, adminHelp()


Are there any pre-built scripts available?

Currently no, but we will provide samples in subsequent releases.


I have written a very useful script to do XYZ, I would like this to be part of the distribution?

Yes, we would love to hear from users. Please submit the script through the Teiid JIRA, and if this script popular, we will include the script in the scripts library in the following releases.


What is different between "connectAsAdmin()" and "connect()"?

The connectAsAdmin methods create a contextual connection to the AdminAPI of the Teiid Server. The connect methods return an extension of the Groovy Sql object to be used for Sql calls to the Teiid Server.


Is IDE support available for writing the scripts?

The Admin Console tool is a light-weight IDE. Full IDE support is available for Groovy, but requires manual manipulation of the class path and script imports. See using AdminShell methods in other environments.


Is debugging support available?

The interactive shell and console do have built-in support for inspection of the current state. Performing line based debugging is beyond the scope of this document.

The AdminShell methods (named contextual connections, AdminAPI wrapper, and help system) have no direct dependencies on Groovy and can be used in other scripting languages.

To use the AdminShell methods in another language, simply import the static methods and Admin classes into your script. You will also need to ensure that the <adminshell dist>/lib/teiid-7.1-client.jar and <adminshell dist>/lib/teiid-adminshell-7.1.jar are in your class path. The snippet below show import statements that would work in Java, BeanShell, Groovy, etc.

import static org.teiid.adminshell.AdminShell.*;
import org.teiid.adminapi.*;

Note that the provided shell and console executables automatically have the proper class path set and inject the proper imports into running scripts. If you wish to use scripts in a non-Teiid Groovy environment, you will need to manually add these imports and add the admin/client jars to the class path.

Some of Teiid's low-level behavior can be configured via system properties, rather than through configuration files. A typical place to set system properties for JBoss AS launches is in the <jboss-install>/bin/run.conf. A property setting has the format -Dproperty=value