 |
Qorus Integration Engine® Enterprise Edition 6.1.0_prod
|
|
Qorus Integration Engine® Enterprise Edition 6.1.0_prod
|
This documentation covers the manual installation and configuration of Qorus.
For installation in Docker and Podman, see
For installation on Kubernetes or OpenShift, see:
For installation with RPMs on RHEL 7 and 8, the file /etc/yum.repos.d/qorus-5.0-stable can be created with the following contents:
[qorus-stable] name=Qorus Stable Repository baseurl=https://repos.qoretechnologies.com/qorus-5.0-stable/CentOS_$releasever/ gpgkey=https://repos.qoretechnologies.com/qorus-5.0-stable/CentOS_$releasever/repodata/repomd.xml.key gpgcheck=1 enabled=1
Qorus Integration Engine® is a self-contained application that is relatively easy to install. The most complex part of the installation is the preparation of the database (covered in Database Configuration Overview).
Qorus Installation Engine® can be installed on a wide variety of UNIX/Linux systems as well as other operating systems when using Docker or Podman containers (see the preceding section for more information and links about installing Qorus in containers).
Minimum System Requirements:
The above minimum requirements are for a small installation with limited capabilities. Large installations of Qorus Integration Engine® require significantly more RAM and disk space. For example, a very large Qorus Integration Engine® installation might have 1TB of RAM spread over many containers, 10 GB of disk space for logs, and 500 GB of disk space for the database.
For Java support, Qorus requires OpenJDK 11, with the JDK installation where javac is available in the PATH.
This is because Qorus interface code using Java is always delivered as source and is compiled when loaded into the system. This ensures that Qorus can provide full source code transparency while also taking advantage of efficient Java byte code execution (as well as JIT).
Jar and class files used by Qorus interfaces can be delivered in compiled form and do not have to be delived in source code form.
Qorus Integration Engine® 6.1.0_prod has a distributed architecture and requires a large number of descriptors for network communication and process entries for processes and threads.
Ensure that the following kernel parameter is set to at least the following value (larger numbers are also OK):
fs.file-max = 5242880For Red Hat Enterprise Linux, CentOS, Oracle Linux, and other Red Hat-based distributions, create or edit an appropriate file in /etc/sysctl.d with a line as above, and then run
/sbin/sysctl -p
as root.
For other Linuxes, create or edit /etc/sysctl.conf with a line as above, and then run
/sbin/sysctl -p
as root; if this file does not exist, see your distribution's documentation about how to set kernel parameters.
The recommended value for the kernel's maximum PID value is as follows (larger numbers are also OK):
kernel.pid_max = 131072If this value is too low, it can be changed as per the above instructions.
cat /proc/sys/fs/file-maxand the current number of descriptors in use can be checked by typing:
cat /proc/sys/fs/file-nrthis command returns three numbers: allocated file descriptors, free allocated file descriptors, and maximum file descriptors
cat /proc/sys/kernel/pid_max
The user running Qorus Integration Engine® 6.1.0_prod must have minimum hard and soft limits for the number of descriptors available (nofile) and the number of processes and threads (nproc).
The minimum recommended soft limit values for each parameter are as follows:
nofile: 8192nproc: 8192For Red Hat Enterprise Linux, CentOS, Oracle Linux, and other Red Hat-based distributions, create or edit an appropriate file in /etc/security/limits.d as in the following examples:
* soft nproc 8192 root soft nproc unlimited
* soft nofile 8192 * hard nofile 16384
Substitute "*" in the lines above with the application user name to set these limits for the Qorus user only.
nproc applies to processes and threads together, and each Qorus Integration Engine® 6.1.0_prod process is multithreaded, therefore the nproc number must be significantly higher than the maximum number of Qorus processes running at any one time.nofile) and the number of processes and threads (nproc) for your user, type: ulimit -Hn -Hu
For recent Linux distributions using systemd (including RedHat Enterprise Linux 8+ among others), the control group TasksMax setting for the Qorus user must be set to a high enough number to allow for Qorus to run properly.
This is particularly important on systems where Qorus is the primary application and will use the majority of the system's resources.
The recommended number is 65535.
To set this, execute the following command as root:
systemctl set-property user-1000.slice TasksMax=65535
Substitute 1000 for the uid of the Qorus user; to find the uid; execute:
id qorus|cut -f2 -d=|cut -f1 -d\(
Substitute qorus with the username of the qorus user.
Qorus Integration Engine® 6.1.0_prod requires a database for persistent storage. The database server must be installed and configured separately to Qorus Integration Engine® installation; this manual does not explain how to install and configure the database server in detail, but rather explains how to install and configure the Qorus system schema in an already-running database server.
Qorus Integration Engine® can use an Oracle, MySQL/MariaDB, or PostgreSQL database to store its system schema containing all user object (workflow, service, class definitions, etc) metadata and workflow state information. Instructions on how to install the database schema (once the database server software itself has been installed and configured) for Qorus on each supported database type are given in Database and Schema Preparation.
See the following sections for detailed requirements: Oracle Requirements, MySQL/MariaDB Requirements, PostgreSQL Requirements.
Oracle Server Requirements
The Oracle database server must be 11.2 or higher. Please note that Oracle Express Edition, available as a free of charge download from Oracle, and freely licensed for commercial use, is also supported for the database server.
Oracle Client Libraries
Oracle 11.2 or newer client shared libraries are required for Oracle functionality. Qorus Integration Engine®’s oracle module is dynamically linked with the Oracle client libraries, therefore earlier unsupported versions will not work.
Oracle Instant Client (available as a free of charge for download from Oracle), Oracle client libraries from a 11.2 or newer server installation, or Oracle client libraries from an Oracle Express Edition installation can be used.
If Oracle Instant Client libraries are to be used, the following Oracle Instant Client package is required at a minimum:
instantclient-basic MariaDB Server Requirements
The minimum supported version for the MySQL/MariaDB server is 5.1. You cannot install Qorus 6.1.0_prod on earlier MySQL/MariaDB versions.
MariaDB Client Libraries
Support for MySQL/MariaDB is statically linked using MariaDB client libraries to the mysql module provided with Qorus Integration Engine®. MariaDB client support is provided under an open source license; no additional licenses are required.
PostgreSQL Server Requirements
The minimum supported version for the PostgreSQL server is 9.0.0. You cannot install Qorus 6.1.0_prod on earlier PostgreSQL versions.
PostgreSQL Client Libraries
PostgreSQL client libraries are required to communicate with PostgreSQL servers; normally the same or newer version than the server should be used.
SAP / Sybase Adaptive Server Enterprise is not currently supported for the Qorus Integration Engine® system schema. You cannot install the Qorus Integration Engine® system schema on a SAP ASE database; you can only communicate with SAP ASE databases from Qorus user code.
SAP ASE Open Client 15 client libraries are required to communicate with SAP ASE servers using the "sybase" driver. Qorus Integration Engine®’s sybase module is dynamically linked with the SAP ASE Open Client 15 client libraries, therefore no previous version will work.
It is recommended to setup the system.arch service and the qorus-archiver job to keep the live DB schema as small as possible as well as activating and configuring the qorus-log-rotator job to rotate and archive log files.
To set up basic configuration with a 90-day data retention period and DB purging of older data as well as daily log rotation; bz2 archiving in the arch subdirectory, and 90-day log file retention, run the first_time_install.sh script in $OMQ_DIR/bin.
From a Docker host this can be run as follows:
docker exec qorus bash --login -c first_time_install.sh
From Kubernetes this can be run as follows:
kubectl exec deploy/qorus-core -- bash -l -c first_time_install.sh
first_time_install.sh script can be run after upgrading a Qorus installation to ensure that DB archiving and log rotation are enabledfirst_time_install.sh script runs schema-tool -m to do the setup workRegardless of the installation type (LSB or tar), a database must be prepared to hold the Qorus system schema before the Qorus server can be started.
Qorus Integration Engine® requires at least the omq database schemas to operate, and also it's recommended to create the omquser schema as given in the following table.
Qorus Integration Engine® System Schemas (Datasources)
| Schema | Type | Description |
omq | Required | System schema, system and user metadata, workflow data will be installed here |
omquser | Recommended | User-modifiable schema containing custom user objects; for initial installs, this schema will be empty |
The system and user schemas can be created in different databases; they can even be of different database types.
Each schema will be accessed through a datasource (see Datasource Connections), which represents a connection to a schema on a particular database server, using a particular username and password, as well as other optional information.
The omq datasource must point to an Oracle, MySQL/MariaDB/Percona, or PostgreSQL database, but the omquser datasource has no restrictions on the database driver.
Note that the database server does not necessarily have to be located on the same system as the Qorus Integration Engine® server, however, for performance reasons, a fast network connection is required between the two systems at the minimum.
Note that no changes can be made by the user to the Qorus system schema or Qorus may no longer function. The optional user schema may be used in any way desired.
The following sections will describe how to set up the system and user schemas for Oracle, PostgreSQL, and MySQL/MariaDB/Percona databases.
Qorus database/tablespace sizing is highly dependent on the application architecture, the amount of workflow order instance data stored, the type and volume of data stored workflows and jobs, and the archiving frequency.
qorus-archiver job to keep the live DB schema as small as possible.The following is a rough formula for determining the tablespace sizing for an initial install, assuming a conservatively large workflow order instance data size and data to index ratio:
omq_data tablespace size = max. workflow order instances * 25 KB
max. job history records * 10 KBomq_index tablespace size = omq_data tablespace size / 3The minumum recommended tablespace sizes for a test or evaluation instance are:
omq_data: 256 MB
omq_index: 128 MB
The space used by system tables is different for each table depending on its function. See Data Model
This is a list if tables which may require special care by DBAs in very large installations with the most important tables listed first.
The most critical table is the table holding workflow order data with columns staticdata and dynamicdata stored as large character objects (CLOB, TEXT depending on the DB server for the system schema):
ORDER_INSTANCE The following tables grow quickly in some circumstances as well:
WORKFLOW_INSTANCE JOB_INSTANCE ERROR_INSTANCE SENSITIVE_ORDER_DATA (LOB)ORDER_INSTANCE_KEYS SENSITIVE_ORDER_DATA_KEYS Depending on the processing volume, the system may benefit from a custom storage setup for particular tables and data; while monitoring the system database, to optimize application performance, DBAs can consider establishing the following:
Consider a real life example of a system where there are many workflows used with large staticdata, dynamicdata, and sensitivedata:
ORDER_INSTANCE table size: 9 GBdynamicdata LOB storage: 481 GBstaticdata LOB storage: 201 GBThis step describes how to set up Oracle database schemas and tablespaces for use with Qorus Integration Engine® on an Oracle 11.2 database server or later. The creation of an Oracle instance is outside the scope of this documentation. Use the dbca tool or see your Oracle documentation for more information. However, Qore Technologies highly recommends that any Qorus Integration Engine® database instance destined for production use should be in a clustered configuration to ensure the highest possible reliability.
The Qorus system datasources to be defined in the next step that will point to the schemas described here are omq (for the Qorus system schema) and optionally omquser (for the optional user schema). The omq system schema is necessary for the operation of the system.
The priviledges described here apply to the system schema user (omq). Example scripts for creating tablespaces and schema users follow in Example Tablespace and User Creation Scripts.
| Name | Mandatory | Qorus Module | Description |
CREATE SESSION | Yes | Core | allows the user to connect to the database |
CREATE PROCEDURE | Yes | Core | allows the user to create procedures |
CREATE SEQUENCE | Yes | Core | allows the user to create sequences |
CREATE TABLE | Yes | Core | allows the user to create tables |
CREATE TRIGGER | Yes | Core | allows the user to create triggers |
CREATE TYPE | Yes | Core | allows the user to create types |
CREATE VIEW | Yes | Core | allows the user to create views |
EXECUTE DBMS_STATS | No | schema-tool: Schema Manipulation Helper Tool, Deleting Old Data From the Database | This package is used for gathering statistics, but it can also be performed manually by a DBA |
EXECUTE DBMS_OUTPUT | No | Debug | Used in the debugging code of the system info service |
EXECUTE DBMS_APPLICATION_INFO | No | Deleting Old Data From the Database | Used for logging while archiving |
SELECT V$BUFFER_POOL_STATISTICS | No | schema-tool: Schema Manipulation Helper Tool | schema-tool: Schema Manipulation Helper Tool uses it for index tree analysis, but it can also be handled by manually by a DBA |
omq and omquser will be used to refer to these schemas. In the next step, the datasources omq and omquser will be set up to point to these schemas as well.Each schema requires two tablespaces, one for data and one for indexes. Tablespace names are flexible and do not necessarily have to be as described in the table below; tablespace names can be overridden with the –-data-ts and –index-ts options to the oload and schema-tool programs and by default in the options file with the qorus-client.omq-data-tablespace and qorus-client.omq-index-tablespace options. However, for the rest of this document, the names will appear as given below.
| Schema | Tablespace | Type | Description |
omq | omq_data | Required | All system data is stored in the tablespace; this should be the default tablespace for the omq user/schema, and the user must have permissions to write to this tablespace (ie UNLIMITED TABLESPACE or a quota on this tablespace) |
omq | omq_index | Required | All system index are stored here. |
omquser | omquser_data | Optional | All data in the user schema is stored in this tablespace; this should be the default tablespace for the omquser user/schema, and the user must have permissions to write to this tablespace (ie UNLIMITED TABLESPACE or a quota on this tablespace) |
omquser | omquser_index | Optional | All user indexes are stored here. |
qorus-client.omq-data-tablespace and qorus-client.omq-index-tablespace options so that automatic schema management will work properlySee Database Sizing General Information as an initial reference
The optional omquser schema will be solely populated with user objects therefore the storage characteristics are installation-dependent and therefore no sizing information can be given here. The Qorus development team and Oracle DBAs should confer and agree on sizing during the design and development process of workflows and services.
To create the two required Oracle schemas and the tablespaces, SQL similar to that found in the $OMQ_DIR/templates/omq-db.sql and $OMQ_DIR/templates/omquser-db.sql can be used. Note that the directory paths and file names should match your installation, and of course the tablespace sizes should match your planning. These files are only given as examples and should not be used without modification for your environment and ideally should be verified by a DBA prior to execution.
Oracle cluster configuration is outside the scope of this document (see your Oracle documentation instead), but a clustered database is recommended for production instances.
Once the schemas and tablespaces have been created, verify the connectivity using $ORACLE_HOME/bin/sqlplus.
tnsnames.ora file for the Qorus system schema. The Qorus server must make all connections to the same physical database server as the Oracle cluster synchronization delay will cause problems with synchronized transaction management within the Qorus server.These files are provided as examples only, paths and passwords at least should be modified to correspond to your Oracle installation. This example file can be found in $OMQ_DIR/templates/oracle-omq-db.sql
create tablespace omq_data
datafile '/opt/oradata/XBOX_MASTER/datafile/omq_data01.dbf' size 512M reuse
autoextend on next 256M
default storage (initial 1M next 1M minextents 1 maxextents 1000
pctincrease 0);
create tablespace omq_index
datafile '/opt/oradata/XBOX_MASTER/datafile/omq_index01.dbf' size 256M reuse
autoextend on next 128M
default storage (initial 1M next 1M minextents 1 maxextents 1000
pctincrease 0);
create user omq identified by omq default tablespace omq_data temporary tablespace temp;
grant create session, create procedure, create sequence, create table, create trigger, create type, create view,
unlimited tablespace to omq;This example file can be found in $OMQ_DIR/templates/oracle-omquser-db.sql
create tablespace omquser_data
datafile '/opt/oradata/XBOX_MASTER/datafile/omquser_data01.dbf' size 128M reuse
autoextend on next 64M
default storage (initial 1M next 1M minextents 1 maxextents 1000
pctincrease 0);
create tablespace omquser_index
datafile '/opt/oradata/XBOX_MASTER/datafile/omquser_index01.dbf' size 64M reuse
autoextend on next 32M
default storage (initial 500k next 500k minextents 1 maxextents 1000
pctincrease 0);
create user omquser identified by omquser default tablespace omquser_data temporary tablespace temp;
grant create session, create procedure, create sequence, create table, create trigger, create type, create view,
create synonym, unlimited tablespace to omquser;"grant unlimited tablespace" in real deployments; assign specific tablespace permissions according to the users' needsThis step describes how to set up PostgreSQL database schemas for use with Qorus Integration Engine® on PostgreSQL server 9.0.0 or later.
PostgreSQL installation and connectivity configuration (postgresql.conf, pg_hba.conf, etc configuration) is outside the scope of this documentation (however some basic information and examples are provided in the following section). See your PostgreSQL documentation for detailed instructions on how to install the PostgreSQL database server.
If the Qorus server and PostgreSQL servers are not located on the same machine, PostgreSQL must be configured to accept connections on a network interface so Qorus can communicate with the server.
Once PostgreSQL has been installed and configured on the target system, Qorus databases, tablespaces, and users can be created.
It is recommended to use UTF-8 character encoding in all PostgreSQL databases where international characters may be used with Qorus.
Each schema requires two tablespaces, one for data and one for indexes.
See Database Sizing General Information
Tablespace names are flexible and do not necessarily have to be as described in the table below; tablespace names can be overridden with the –-data-ts and –index-ts options to the oload and schema-tool programs and by default in the options file with the qorus-client.omq-data-tablespace and qorus-client.omq-index-tablespace options. However, for the rest of this document, the names will appear as given below.
qorus-client.omq-data-tablespace and qorus-client.omq-index-tablespace options so that automatic schema management will work properlyRequired PostgreSQL Tablespaces
| Schema | Tablespace | Type | Description |
omq | omq_data | Mandatory | All system data is stored in the tablespace |
omq | omq_index | Mandatory | All system index are stored here |
omquser | omquser_data | Optional | All data in the user schema is stored in this tablespace |
omquser | omquser_index | Optional | All user indexes are stored here |
Example Database, Tablespace and User Creation Scripts
These files are provided as examples only; paths and passwords at least should be changed for security reasons. This example file can be found in $OMQ_DIR/templates/pgsql-omq-db.sql
create database omq encoding = 'utf8'; \connect omq; create tablespace omq_data location '/opt/postgresql90/db/omq_data'; create tablespace omq_index location '/opt/postgresql90/db/omq_index'; create user omq password 'omq'; grant create, connect, temp on database omq to omq; grant create on tablespace omq_data to omq; grant create on tablespace omq_index to omq; grant select on all tables in schema pg_catalog to omq;
This example file can be found in $OMQ_DIR/templates/pgsql-omquser-db.sql
create database omquser encoding = 'utf8'; \connect omquser; create tablespace omquser_data location '/opt/postgresql90/db/omquser_data'; create tablespace omquser_index location '/opt/postgresql90/db/omquser_index'; create user omquser password 'omquser'; grant create, connect, temp on database omquser to omquser; grant create on tablespace omquser_data to omquser; grant create on tablespace omquser_index to omquser; grant select on all tables in schema pg_catalog to omquser;
These files can be installed with the psql command as follows (use the appropriate user and password for your installation, the following are only examples):
prompt$ psql –Upostgres < $OMQ_DIR/templates/pgsql-omq-db.sql prompt$ psql –Upostgres < $OMQ_DIR/templates/pgsql-omquser-db.sql
Basic PostgreSQL Connectivity Configuration
Example pg_hba.conf File
The following file allows connections to all databases and all users without a password for local users, and requires a username and password from all network users. Do not use this file if local security is a concern:
# CAUTION: Configuring the system for local "trust" authentication allows # any local user to connect as any PostgreSQL user, including the database # superuser. If you do not trust all your local users, use another # authentication method. # TYPE DATABASE USER CIDR-ADDRESS METHOD # "local" is for Unix domain socket connections only local all all trust # IPv4 local connections: host all all 127.0.0.1/32 trust # IPv6 local connections: host all all ::1/128 trust # require a password from network users host all all 0.0.0.0/0 md5 host all all ::/0 md5
If you need to connect to your PostgreSQL databases from other machines on the network, set the following in your postgresql.conf file to configure the server to listen on all network interfaces:
listen_addresses = '*'
For more information on these files, or on PostgreSQL security or configuration, see your PostgreSQL documentation.
Because MariaDB and Percona are a drop-in replacements for MySQL, references to MariaDB below are also valid for MySQL (which is an Oracle property; Qore Technologies is not affiliated with Oracle) and Percona. Any differences between MySQL, MariaDB, and Percona will be highlighted below.
This step describes how to set up MariaDB database schemas for use with Qorus Integration Engine® on MariaDB server 5.1 or later. MariaDB installation is outside the scope of this documentation. See your MariaDB documentation for detailed instructions on how to install the MariaDB database server. Once MariaDB has been installed on the target system, Qorus databases and users can be created.
It is recommended to use UTF-8 character encoding in all MariaDB databases where international characters may be used with Qorus.
A case-sensitive collation must be used when creating the Qorus schema; the collation can be set as using the "collation" connection option as follows:
mysql:user/password@db(utf8)%hostname{collation=utf8_bin} character set when creating tables) and the collation must be given explicitly in the qorus.systemdb option in the System Options File in order to ensure that tables are created correctly and that client connections will use the same encoding and collation, otherwise Qorus will not run properlyQorus imposes no restrictions on the database or user names used for either the system or user schemas when using MariaDB as a database server.
Example Database and User Creation Scripts
These files are provided as examples only, at least the passwords should be changed for security reasons. This example file can be found in $OMQ_DIR/templates/mysql-omq-db.sql
create user 'omq'@'%' identified by 'omq'; grant super on *.* to 'omq'@'%'; create user 'omq'@'localhost' identified by 'omq'; grant super on *.* to 'omq'@'localhost'; create database omq character set 'utf8'; grant all on omq.* to 'omq'@'%'; grant all on omq.* to 'omq'@'localhost';
This example file can be found in $OMQ_DIR/templates/mysql-omquser-db.sql
create user 'omquser'@'%' identified by 'omquser'; grant super on *.* to 'omquser'@'%'; create user 'omquser'@'localhost' identified by 'omquser'; grant super on *.* to 'omquser'@'localhost'; create database omquser character set 'utf8'; grant all on omquser.* to 'omquser'@'%'; grant all on omquser.* to 'omquser'@'localhost';
These files can be installed with the mysql command as follows (use the appropriate user and password, the following are only examples):
prompt$ mysql –uroot < $OMQ_DIR/templates/mysql-omq-db.sql prompt$ mysql –uroot < $OMQ_DIR/templates/mysql-omquser-db.sql
A first-time installation of Qorus Integration Engine® from a tar.gz package involves preparing the file system and installing the system files. Either preceding or following this, the system database schema must be prepared and populated. This last topic is covered in Database and Schema Preparation.
From a high-level, the installation goes as follows:
Then the system database schema will be prepared and populated as follows:
Before starting the system installation, ensure that you have the appropriate file from the following list containing binary support for your platform for Qorus Integration Engine®. Examples of compatible Linux distributions are: Fedora, Red Hat Enterprise Linux, OpenSUSE, Novell SUSE Linux Enterprise Server.
The release file, when unpacked, will create the files described in the following table in the subdirectory:
qorus-6.1.0_prod/ Qorus Integration Engine® TAR.GZ Release Manifest
| File | Description |
install.sh | Installation script |
qorus-6.1.0_prod-Linux2.6-x86_64-binary.tar.gz | x86_64 Linux (kernel 2.6+) binaries |
qorus-6.1.0_prod-noarch.tar.gz | Common files |
releases/qorus-6.1.0_prod.qrf | System service load file |
Note that depending on the release package, only one of the above binary packages may be present in the release file.
On UNIX/Linux systems, it is highly recommended that a new user be created for this installation. The name for the user used in this documentation is qorus.
Qorus can use many file descriptors, depending on the size of the installation.
See Linux Kernel Settings for information on Linux settings required for the proper operation of Qorus Integration Engine®
Step 1: Prepare Database User and Empty System Schema
Prepare the system schema as described in Database and Schema Preparation.
Make sure and test the connection and have the connection parameters ready for use in Step 3: Install Qorus Application and Populate System Schema.
Step 2: Setup User and File System
The Qorus application itself takes less than 20 MB of disk space.
Space must be planned for log directories that can fill up fast with busy systems, and for user code (workflow, service definitions, other Qorus user configuration files).
50 MB is recommended for the Qorus Integration Engine® application directory, and a minimum of 500 MB for the log directory, larger sizes can be necessary for larger installations, depending on the frequency of log rotation and the amount of logging done by the workflows and services running.
The log directory can appear anywhere on the file system and does not have to be a subdirectory of the Qorus application directory, although the default log directory location is $OMQ_DIR/log.
On UNIX/Linux system, a dedicated user is not required for the system, but it is highly recommended. The username can be any valid user name, for the purposes of this document, the username qorus will be assumed. The application directory could be the Qorus user’s home directory or any other directory (for example: the mount point of a mounted filesystem) on the system. In the examples in this document, the Qorus user qorus will have an application directory located in /opt/qorus.
The following environment variables have to be set for the system to function properly.
Qorus System Environment Variables
| Variable | Description |
OMQ_DIR | The main application directory |
PATH | $OMQ_DIR/bin must appear in the path |
PYTHONPATH | $OMQ_DIR/python:$OMQ_DIR/user/python:$OMQ_DIR/user/python/lib/pythonver/site-packages |
QORE_CONNECTION_PROVIDERS | Must be set to "QorusConnectionProvider" in your system environment to take advantage of the QorusConnectionProvider module as a connection provider to command-line programs so that Qorus user connection or remote connection identifiers can be used instead of URL strings in Qore programs like rest and sfrest, etc |
QORE_DATA_PROVIDERS | Must be set to "QorusDataProviders" in your system environment to use Qorus data providers with the qdp program for command-line introspection and manipulation of data providers |
QORE_DATASOURCE_PROVIDERS | Must be set to "QorusDatasourceProvider" in your system environment to take advantage of the QorusDatasourceProvider module as a datasource provider to command-line programs so that Qorus datasource names can be used instead of full datasource connection strings in Qore programs like sqlutil, schema, and schema-reverse |
QORE_FILE_LOCATION_HANDLERS | Must be set to "QorusResourceFileLocationHandle" to use the resource:// scheme with Qorus service resources (for example with qdp) |
QORE_LIBRARY | Must be set to the absolute path to the native Qore library on the system for Java programs to use Qore functionality (ex: $OMQ_DIR/lib/libqore.so) |
QORE_MODULE_DIR | For non-LSB, non-RPM-based installs, must be set to $OMQ_DIR/qlib:$OMQ_DIR/lib/modules:$OMQ_DIR/user/modules for the proper operation of the system so that system user modules can be found; this is needed by the running server and for client programs. Multiple directories can be given separated by colons (':') |
QORUS_RELEASE_DIR | The directory for creating release packages with make-release; defaults to $HOME/releases if not set |
If using the oracle driver for connectivity to Oracle databases, one of the following environment variables should be set depending on the Oracle client library used.
Environment Variables For Oracle Connectivity
| Variable | Description |
ORACLE_HOME | For full Oracle installations, this variable must be set to the Oracle installation’s home directory. This variable is not required for Oracle Instant Client installations. |
TNS_ADMIN | With Oracle Instant Client only: set to the directory where the tnsnames.ora file is located. |
Environment Variables MS SQL Server and SAP / Sybase ASE Connectivity Through FreeTDS (freetds)
| Variable | Description |
FREETDSCONF | On UNIX/Linux: must point to the freetds configuration file (for example: $OMQ_DIR/etc/freetds.conf) |
The following environment variable must be set to use the sybase driver with SAP/Sybase databases.
Qorus Environment Variables For Native SAP / Sybase ASE Connectivity
| Variable | Description |
SYBASE | Must point to the directory containing the interfaces file, where connection information for SAP ASE databases is specified. |
Qorus Environment Variables on All Other UNIX/Linux Platforms
| Variable | Description |
LD_LIBRARY_PATH | Must have $OMQ_DIR/lib as well as optionally Oracle, MariaDB, PostgreSQL, SAP ASE, or other third-party library directories. |
Set up the environment so that it is configured automatically at login time using .profile (for Bourne-type shells), .bash_profile for bash, the Bourne-Again Shell, or .cshrc (for csh-type shells).
Bourne-Compatible Shell Example
Replace the application directories in the following example with the correct directories in your installation.
# set OMQ_DIR to Qorus Integration Engine® application directory OMQ_DIR=/opt/qorus # add Qorus library directory to LD_LIBRARY_PATH LD_LIBRARY_PATH="$OMQ_DIR/lib:$LD_LIBRARY_PATH" # add Qorus bin directories to path PATH="$OMQ_DIR/bin:$PATH" # add Qorus qore language client library module dir to QORE_MODULE_DIR QORE_MODULE_DIR="$OMQ_DIR/qlib:$QORE_MODULE_DIR" # export all the changes made above export OMQ_DIR LD_LIBRARY_PATH PATH QORE_MODULE_DIR
$OMQ_DIR/lib appears first in your LD_LIBRARY_PATH. Be sure to use the version of Qore either shipped with Qorus or recommended for use with this version of Qorus, otherwise problems may result.CSH-Compatible Example
Replace the application directories in the following example with the correct directories in your installation.
# set OMQ_DIR to Qorus Integration Engine® application directory setenv OMQ_DIR /opt/qorus # add Qorus library directory to LD_LIBRARY_PATH setenv LD_LIBRARY_PATH "$OMQ_DIR/lib:$LD_LIBRARY_PATH" # add Qorus and Oracle bin directories to path setenv PATH "$OMQ_DIR/bin:$PATH" # add Qorus qore language client module include dir to QORE_MODULE_DIR setenv QORE_MODULE_DIR "$OMQ_DIR/qlib:$QORE_MODULE_DIR"
Step 3: Install Qorus Application and Populate System Schema
Once the Qorus system database user and empty schema have been prepared, the application user (if applicable) and application and log directories have been created and the environment has been properly set up for the application user, the application files can be installed and the system schema populated as described in this section.
Log in as the Qorus user and make sure the environment is properly configured. For example, execute:
UNIX/Linux Shell
prompt% echo $OMQ_DIR
The application directory should be output to your console. If not, check your environment settings and try again.
$OMQ_DIR must exist and be writable by the Qorus user. Normally the Qorus user will be the owner of this directory, but regardless of ownership, the user running Qorus must have read/write access to the application and log directories.If all the prerequisites documented above are met, change directory to the location of the Qorus installation file, and uncompress the archive as follows:
UNIX/Linux Shell
prompt% gunzip –dc qorus-6.1.0_prod.tar.gz | tar xvf -
This will create a subdirectory called qorus-6.1.0_prod with contents as described in the manifest in the introduction to this manual.
Change the current directory to the new directory extracted in the previous command:
UNIX/Linux Shell
prompt% cd qorus-6.1.0_prod
In order to install the application file system in $OMQ_DIR and populate the system schema, the install script must be run with an option describing the initial connection to the system database. Use the connection parameters for the system schema to substitute in the following command; note that arguments enclosed by square brackets are optional. See the following table for the meaning of the required parameters in angle brackets.
Qorus Integration Engine® Datasource Parameters
| Parameter | Description |
driver | The driver to use for the connection, i.e. oracle, mysql, or pgsql |
user | The username for the connection |
pass | The password corresponding to the username |
db | The database name |
enc | The optional encoding to use for the connection in the format expected by the driver (i.e. AL32UTF8 for UTF-8 with the oracle driver) |
host | The optional hostname to use for the connection |
port | The optional port number to use for the connection |
Note that if the data and index tablespace names for the system schema are not named omq_data and omq_index respectively, then the –data-ts=data_tablespace_name and –index-ts=index_tablespace_name options must be given as well.
Install the files and populate the initial database schema by executing the following command:
Install.sh Arguments ./install.sh [oload args...]
If the environment is properly configured, output will appear as follows:
checks are OK, installing from /Users/david/src/Qorus/releases/qorus-6.1.0_prod installing Qorus architecture-independent files from: qorus-6.1.0_prod-noarch.tar.gz installing release files: done schema status is EMPTY system schema database driver is pgsql pgsql:omq@omq%localhost:5432: creating Qorus 6.1.0_prod schema 6.0.999.21 CCCCCCCCCCCCCCCCCCCCCAACACACACAAAACACACACAAAAACACAAAACACAAACACAAAACACAAACACAAAACACACACACACACAAAACACAAAACACAAAAACACAAAACACACAAAAACACAAAAACACAAAACACAAACACAAAACACACACACACAAAAAAAAAAAAAAAAAACACACAAAACACAAAAAAAAAACACAAAACACACACACAAAAACACAAAAAAAAAACACAAACACAACACAAACAAAAAAAACACAACACAAAAAACACAAAAAACACAAAACAACACAAACACACACAAAAAACACACAAAAAAAACACAACACAAAAAACACAAAAAACACAAAACACAAAAAAAAAAAAAAACACAAAACACAAACAAACAAAAACACAAAAAAACACAAAAACACACACAAAAAAAAAAAAAAAAAACACACACAAACACAACACACACAAACACACACAAAAACACAAAAACACAAACACAAAAACACAAAAACACAAAAACACAAAAACACACACCCCCCCCCCCCCCCCCCCCCCCCC 560 changes made; schema is now at version 6.0.999.21 verifying reference data: IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIVIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII reference data: inserted: 232, verified: 1 running system release load script pgsql:omq@omq%localhost: system schema "omq" is at version 6.0.999.21 executing schema release loader files done executing release files installation complete!
Errors in the user's environment will be flagged in the output of the script and must be repaired by hand after the installation script executed. For example, if the following text appears:
********************************************************** ATTENTION: MANUAL STEPS NECESSARY TO COMPLETE INSTALLATION ********************************************************** *** this script made changes to your environment in order to install *** Qorus Integration Engine®. You must make these changes permanent *** in order to run Qorus Integration Engine®. List of changes: +++ put /opt/qorus/lib first in the LD_LIBRARY_PATH
Follow the instructions given to ensure that the environment is properly configured each time the Qorus user logs in. In this case, the LD_LIBRARY_PATH variable must be updated.
After successfully running install.sh, the Qorus Integration Engine® directory layout is installed as described in tar.
This section describes upgrading a Qorus Integration Engine® installation from tar.gz files.
Upgrading a Qorus Integration Engine® installation to version 6.1.0_prod is supported from any publicly released version of Qorus. Furthermore, it is assumed that the Qorus user’s environment is already properly set up, as it should be for an existing installation.
To upgrade Qorus Integration Engine® to 6.1.0_prod, change directory to the location of the Qorus Integration Engine® 6.1.0_prod installation file, and uncompress the archive as follows:
UNIX/Linux Shell
prompt% gunzip –dc qorus-6.1.0_prod.tar.gz | tar xvf -
This will create a subdirectory called qorus-6.1.0_prod with contents as described in the manifest in the introduction to this manual.
To create the application file system in $OMQ_DIR, execute the following commands:
UNIX/Linux Shell Example
prompt% cd qorus-6.1.0_prod prompt% ./install.sh
If the environment is properly configured, output will appear as follows (exact messages will differ depending on your system, system database server type, users in the options file, starting version for upgrade, etc - this example shows an upgrade from Qorus 3.1.0:
checks are OK, installing from /Users/david/src/Qorus/releases/qorus-6.1.0_prod installing Qorus architecture-independent files from: qorus-6.1.0_prod-noarch.tar.gz installing release files: done schema status is 3.1.0 system schema database driver is pgsql pgsql:omq@omq%localhost:5432: schema is at version 3.1.0 (targeting 6.0.999.21): running schema alignment ............................N........................N.....................N..................................N........................N.........................CACAAAAACAN....................N...........................N...................................................AAA.....M...............................................................................................................................................................................................................................................................N..................A..................................................................................MMM...............................................................................N.............................................CACA......................... 32 changes made; schema is now at version 6.0.999.21 Uverifying reference data: VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVIIIIIIIIVVVVVVVVVVIIIIIIIIIIIIIIIIVVVIIIIIVVVVVIIIIIIIIIIVVVVIIIIIIIVIIIIVVIIIIIIVIIIIIIIII reference data: verified: 101, inserted: 65 running system release load script pgsql:omq@omq%localhost: system schema "omq" is at version 6.0.999.21 executing schema release loader files done executing release files installation complete!
After the successful upgrade, restart the Qorus Integration Engine® server. Then execute ostatus as follows:
UNIX/Linux Shell
prompt% ostatus
which should then output:
Qorus 6.1.0_prod <your-instance-key> sessionid 1
If so, the installation is complete.