Tamino requires some settings of system variables to be adjusted.
You can do this using the "smh" tool. The "smh" tool
requires a working X11 display server; ensure that the
DISPLAY
environment variable points to a suitable
machine.
Execute the following command as the root user:
/usr/sbin/smh
A window appears. Select the option
, then select the option . A new window appears, displaying several kernel parameters and their values. Scroll down until you see the entry you intend to change.Select the entry, then choose
to change its value to the required value, which you can take from the table below:Variable Name Required Value max_thread_proc 256 maxdsiz 0X0C000000 msgmap 512 msgmax 8192 msgmnb 64000 msgmni 512 msgseg 8192 msgssz 8 msgtql 512 semaem 16384 semmap 512 semmni 512 semmsl 512 semmns 1024 semmnu 1024 semume 36 semvmx 32767 shmmax 512000000 shmmni 100
Tip:
If you use many XML work threads or work with a large number of
clients, you should consider setting the max_thread_proc
parameter to an even higher value in order to avoid possible emergency
stops.
Caution:
Do not change the maxdsiz_64
parameter
regardless of whether you are running a 64 bit or a 32 bit
environment!
After installing Tamino, ensure that the shared memory limit is at
least 512 megabytes. To check the current value, examine the value of the Linux
kernel parameter shmmax
as follows:
cat /proc/sys/kernel/shmmax
To set shmmax
to a value of 512 megabytes (which
should be sufficient for medium-size databases), enter the following
command:
echo "512000000" > /proc/sys/kernel/shmmax
We recommended setting the variable shmmax
to the value of the size of the physical memory in bytes. You can find out how
much memory there is in your machine with
cat /proc/meminfo
For very large databases, it might be necessary to increase the value
of the parameter shmmax
.
Note that this change is not persistent, so after a reboot the parameter will have the old (default) value. In order to change this, add the following line to the /etc/sysctl.conf script:
kernel.shmmax = 512000000
To ensure that /etc/sysctl.conf is parsed after a reboot, enter the following command:
/sbin/chkconfig boot.sysctl on
This document contains information about accessing Tamino. The simplest means of accessing
a Tamino database is via HTTP in webserverless mode. For this purpose it suffices to set the
database parameter communication mode
to HTTP
and the parameter HTTP port
to an unused port of your choice.
Also, client applications can access a Tamino database using HTTP via a web server.
To specify that a particular database may only be accessed through a particular web server, define the web server as described below and assign it to a particular database via the Web Servers object in the tree-view frame.
The following topics are covered:
Usually, client applications access Tamino using HTTP via a web server. Each web server that is required to provide access to Tamino must be configured accordingly.
Note:
Tamino version 4.1 or later can also be used without a web
server. This is done by some Tamino APIs and tools, for example.
If you use a web server, it does not need to be located physically on the machine on which Tamino is installed; it can be located anywhere in the network where Tamino is installed. For example, it is possible to have Tamino running on a Windows machine and the web server running on a UNIX machine in the same network or vice versa.
A single web server can be configured to access Tamino servers on several machines.
The Tamino interface is a DSO (dynamic shared object: Apache terminology for DLL/shared library), so your Apache must have DSO support. DSO support is included in the default configuration of Apache. Apart from this, there are no special requirements for Tamino. For Apache configuration, tuning etc., it makes no difference whether the requested resources are in a file system or in a Tamino database.
The Tamino interface is provided in binary form; these binary files work for current standard Apache distributions. However, under certain circumstances, it may be desirable or necessary to compile and link the Tamino interface. Possible reasons are:
Your Apache is built with compile/link options that are incompatible with the provided binary files.
You prefer to use open source software.
The Tamino installation provides the Apache interface in the directory X_Port\Apache. This directory contains the source code, the necessary header files and link libraries, and an example makefile that can be adapted to the current platform. If the platform supports both 32-bit and 64-bit versions, the appropriate link libraries can be found in corresponding subdirectories.
Apache must be configured as described below.
Note:
We strongly recommend that you make a backup copy of the Apache
configuration file httpd.conf before proceeding.
Copy the file Apache22ModuleIno.dll (Windows) or Apache22ModuleIno.so (UNIX, Linux) to your Apache modules directory. For Windows additionally copy the libraries icudtsag538.dll, icuucsag538.dll, sagovo5.dll, sagrgs5.dll, sagsmp2.dll and sagxts5.dll from <INSTALL_ROOT>\Tamino\v103\bin to your Apache modules directory.
Add the following to the Apache httpd.conf file:
LoadModule ino_module modules/Apache22ModuleIno.dll <Location /tamino> SetHandler ino InoRegfile "<INSTALL_ROOT>/Tamino/cfg/regfile" </Location>
This results in an attempt to establish a connection between Tamino
and the web server using XTS. When an XTS directory server is not used and
instead a flat-file XTS directory is activated using the XTSDIR setting,
the XTSDIR environment variable must be defined for the Apache web server
process (default setting: XTSDIR = <INSTALL_ROOT>\Tamino\v103).
If this fails, e.g. because the server property
communication method
has been set to
"TCP/IP", the local configuration information is
searched for the XML port of the database. In this case a native TCP/IP
connection is established, if the database is local.
Note:
If you use Apache 2.4.x, the name of
this file is Apache24ModuleIno.
If the Apache web server and the Tamino server are not on the same machine, then in order to enable the Apache web server to access Tamino databases via native TCP/IP, add the following section to the httpd.conf file for each database:
<Location /tamino/mydb> SetHandler ino InoHost xyz.abc.de InoTcpipPort 4711 </Location>
Replace mydb by the name of the database, replace xyz.abc.de by the name of the host where the database server is running, and replace 4711 by the number of the database's XML port, which you can find via Tamino Manager (in the Properties dialog of the database).
Note that it is not possible to use Apache *.htaccess files ("distributed configuration files") in conjunction with Tamino to specify authorization information. These files are typically located in the same directory as the files to be read, but there is no such directory in the case of Tamino. This problem can easily be circumvented by specifying exactly what would otherwise be the content of your *.htaccess file in a <Location> directive in your httpd.conf file, for example:
<Location /tamino> # Put here exactly the contents of your *.htaccess file </Location>
On UNIX (including Linux) systems, Tamino's Apache interface is linked against the Apache portability runtime (APR) library (libapr.so). The name of this library can be customized in Apache. If libapr.so has a different name in your Apache (e.g. a versioned name like libapr-0.so), please create a file system link between the real name and libapr.so, or use the source distribution (see above).
This section describes installation and configuration aspects of Tamino and Microsoft Internet Information Services (IIS). The following topics are covered here:
To install modiis.dll as a filter in IIS
Ensure that IIS is installed and ISAPI Filters and ISAPI Extensions are activated. In order to make the IIS Manager available, follow the steps below depending on the specific platform.
Go to "Start > Control Panel > Programs and Features" and click "Turn Windows features on or off".
Go to "Internet Information Services > World Wide Web Services > Application Development Features" and mark "ISAPI Extensions" and "ISAPI Filters".
Go to "Internet Information Services > Web Management Tools" and mark "IIS Management Console". Click "OK".
Go to "Start > Control Panel > Programs and Features" and click "Turn Windows features on or off". The Server Manager is started.
Mark "Roles" and click "Add Roles" in the action pane.
Mark "Web Server (IIS)", click "Next" and, on the introduction page, click "Next" again. That opens the list of role services for IIS.
Mark "ISAPI Extensions" and "ISAPI Filters" under "Application Development" and "IIS Management Console" under "Management Tools".
Click "Next" and then click "Install" to install the selected role services.
The "World Wide Web Publishing Service" should now be started. Expect the IIS Manager to be available under "Start > Control Panel > Administrative Tools > Internet Information Services (IIS) Manager".
Go to "Start > Control Panel > Administrative Tools" and start "Internet Information Services (IIS) Manager".
Ensure that a virtual directory inoScripts exists for the desired site. If it does not exist create it by right-clicking on the desired site and activate the "Add Virtual Directory" menu item.
Copy the file modiis.dll from the directory \X_Port\IIS folder of your installed Tamino environment to the directory to which the IIS virtual directory inoScripts points to.
For Tamino versions 9.12 and higher modiis.dll is no longer self-contained (statically linked with all required libraries). Therefore it is required to copy six additional libraries from "<INSTALL_ROOT>/Tamino/v103/bin" to the inoScripts directory, namely icudtsag538.dll, icuucsag538.dll, sagovo5.dll, sagrgs5.dll sagsmp2.dll, and sagxts5.dll.
Add modiis.dll as an ISAPI filter: Click on the desired site in the IIS manager. Double-click "ISAPI Filters" and activate the "Add" item in the action pane.
Enter "Tamino" as Filter Name and the modiis.dll of the scripts directory (C:\Inetpub\inoScripts) as executable.
Set the "execute" permission for the ISAPI filter:
Click on the desired site in the IIS manager.
Double-click "Handler Mappings".
Select "ISAPI-dll" and activate the "Edit Feature Permissions" item in the action pane.
Check the Execute box and click "OK".
"ISAPI-dll" is now enabled.
Allow the modiis.dll ISAPI Extension to run on the web server:
Click on the top-level local machine name in the IIS manager.
Double-click "ISAPI and CGI Restrictions" and activate the "Add" item in the action pane.
Enter the modiis.dll of the scripts directory (C:\Inetpub\inoScripts) as ISAPI or CGI path, "Tamino" as Description.
Check the Allow extension path to execute box and click "OK".
Restarting the IIS web server enables it to access Tamino databasess using an XTS directory server.
If XTS communication is to be used in absence of an XTS directory server, but instead using a flat-file XTS directory activated using the XTSDIR setting, then in order to enable an IIS web server to access Tamino databases via XTS, locate the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Tamino\IIS Mapping\Prefix
Under this key you may have a list of keys for the individual path
prefixes you want to map (for each Tamino database you want to
access, enter a key
tamino/dbname
, where
dbname is to be replaced by the name of your
database). This sub key has the following subordinate string values:
"Location" and its value is the actual path prefix;
"XTSDIR" and its value is the path to the flat-file XTS directory (see TaminoInstallation Guide).
Example of database mydb (in regedit format):
[HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Tamino\IIS Mapping] [HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Tamino\IIS Mapping\Prefix] [HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\Tamino\IIS Mapping\Prefix\tamino/mydb] "location"="tamino/mydb" "XTSDIR"="C:\SoftwareAG\Tamino\v103"
Note that the forward slash between the strings "tamino" and "mydb" is correct and necessary, because tamino/mydb is part of a URL.
After changing the registry, the World Wide WEB Publishing Service must be restarted (item Services in the Windows control panel).
HTTP Error 403 (read access forbidden) may occur due to incorrect configuration of IIS. You can verify this situation and correct the configuration as follows:
To verify and correct the configuration for using Tamino with IIS
Verification: To test this, enter a Tamino-URL in the browser, e.g. http://MYHOST/tamino/myDB?_diagnose=ping. If HTTP error 403 occurs and you are using the Microsoft Internet Information Server (IIS) web server, you should proceed as follows:
Open the Microsoft Management Console (MMC) in order to configure the IIS;
With your host name, open "Default Web Site";
Click the right mouse button on "inoScripts";
Change the properties of this folder;
Make sure that under "Virtual Directory" the "Permissions" are set to "Execute".
Note:
This value may be set to "Scripts" e.g. by the
"Microsoft Lockdown" utility.
A standalone Tomcat server cannot be used to communicate to X-Machine via HTTP. Programs running under Tomcat can use the webserverless interface instead.
This section discusses how to activate the authentication mechanisms of the various web servers that Tamino supports.
The following example is an extract of a suitable Apache configuration file httpd.conf to set the authentication mechanism for all databases:
# ------------------------------------------------------------------- # Enable Apache Web Server Authentication for Tamino Security # Note: The AuthUserFile is created with pgm ../apache/bin/htpasswd.exe # Enter command 'htpasswd -h' for pgm usage description # Restart Apache Web Server after modification # If authorization fails: # - Check Apache error.log file # - Enter browser command http://localhost/tamino/secdb?_diagnose=echo <Location /tamino> AllowOverride AuthConfig AuthName "Tamino" AuthType Basic AuthUserFile "bin/userids" <== file created with htpasswd.exe require valid-user </Location>
It is also possible to set the authentication mechanism for individual databases. To do so, add the database name to the location:
<Location /tamino/mydb>
Activate the checkbox
in the "Authentication Methods" dialog box.Warning: Do not activate the checkbox "Basic Authentication (password is sent in clear text)", because this option can cause severe problems. |
To get to the "Authentication Methods" dialog box, choose the
tab in the "modiis.dll Properties" window of the IIS, then choose in the "Anonymous access and authentication control" section.To enable clients to locate Tamino databases by name, even in a distributed environment, Tamino uses the XTS (eXtended Transport Service) directory service.
XTS provides a uniform mechanism for Software AG products to communicate with each other across diverse platforms using multiple protocols and different types of hardware.
XTS offers two methods of maintaining the directory:
A standalone service, included in the distribution as an installable package
Can be used if all participants are on the local machine. The flat file implementation is used under the condition that an environment variable XTSDIR is defined and contains a valid path pointing to a directory where the flat file is created and maintained by XTS.
Starting with Tamino v8.0 the default mechanism for XTS was changed from the Software AG directory server to the flat file implementation.
That means that for each client accessing a Tamino database the XTSDIR environment variable must be defined and contain the same value as the database server uses (the XTSDIR setting of the Tamino 10.3 databases can be found in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Software AG\System Management Hub\Products\Tamino\v103\Environment).
The script useXTSDIR.[cmd|sh] on <INSTALL_ROOT>/Tamino/v103/bin can be used to set the XTSDIR default value (parameter: enable) or to remove the XTSDIR entry in the registry (parameter: disable).
"Client" in this case means the instance addressing the database server via XTS. For example, if Tamino is accessed via an Apache web server then the XTSDIR environment variable must be defined for the Apache web server process.
However, for replication, due to the fact that the databases reside on different nodes, it is necessary to use the Software AG directory server.
Switching between the two XTS directory methods | Installing Tamino XML Server > Complete the Installation |
Setting up the Software AG directory server | Setting Up Tamino > Before You Start Using Tamino > Other Issues |
To use XTS with the Software AG directory server, Tamino must be able to resolve SAGXTSDShost and SAGXTSDSport to IP addresses (if SAGXTSDSport cannot be resolved, a default value is used). This can either be done by a DNS server (or by entering the two well-known names in your local hosts file).
The entries in the hosts file are as follows:
<IP address of the master node> SAGXTSDShost x.y.0.0 SAGXTSDSport
where master node is the node where the directory of the Extended Transport Service is running.
The port number is calculated as 256 * x + y. Thus, for example, if the port number should be set to 12731, then SAGXTSDSport must be defined as 49.187.0.0 (12731/256 = 49, remainder 187).
This information is provided in case you want to custom configure the
SAGXTSDSport
.
Note:
Tamino registers with XTS using host names, not IP addresses.
For a remote client to resolve the host name into an IP address, the host name
either has to be present in DNS or an entry for that host name must be entered
in the client's local etc/hosts file.
If the system is configured to run in parallel boot mode, set the
parameter RUN PARALLEL="no"
in the file
/etc/sysconfig/boot.
For viewing the online documentation, a browser capable of supporting Java, JavaScript, and Cascading Style Sheets (CSS) is recommended. The documentation has been successfully tested with these products:
Microsoft Internet Explorer version 8.x.
Microsoft Internet Explorer version 7.x.
Mozilla Firefox version 3.x.
These browsers are freely available for download.
The documentation has been successfully tested with the following browser plug-ins:
JVM 1.7
Caution:
Using Sun Java 6 update 10 may lead to problems.
We recommend going to the Java website to acquire a free Java browser plug-in.
For viewing the PDF documentation:
A PDF reader such as the Adobe Reader must be installed.
The Adobe Reader is freely available for download.
Software AG documentation uses active content (JavaScript and Java applets). With Service Pack 2 (SP2) for Windows XP, Microsoft introduced a range of powerful new security features. One effect of these security features is that warning messages appear whenever you try to display HTML pages that use active content, for example Software AG documentation, in the Internet Explorer. A typical warning message that appears in the Internet Explorer information bar is:
Warning: To help protect your security, Internet Explorer has restricted this webpage from running scripts or ActiveX controls that could access your computer. Click here for options... |
To continue using the documentation, you can do one of the following:
Use a different web browser. This problem only affects Microsoft's Internet Explorer.
Note:
Software AG does not endorse or recommend any web browser.
Change the Internet Explorer options to allow active content to run in files on your computer.
To unblock active content
In the Microsoft Internet Explorer:
Choose
> .Choose the tab Advanced.
Scroll down to the section Security.
Check (tick) the box Allow active content to run in files on My Computer.
Choose
.Restart the Internet Explorer.
The warning messages should now no longer appear.
Click on the information bar and choose the option
. You will have to do this for each affected page.You have now completed the installation of Tamino and set up the environment, and are ready to start using Tamino. The next steps are described in the section Getting Started.