blob: c0c1aae0af0bc3468cddd58691cfe096392a900e [file] [log] [blame] [view]
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# QUICKSTART GUIDE
## 1. Overview
You must build *and install* qpid-interop-test before you can run the tests.
By default, qpid-interop-test will install to `/usr/local` (and will thus also
require root privileges), but you can set any non-privileged directory as the
install prefix using the `CMAKE_INSTALL_PREFIX` environment variable, for
example `$HOME/install`.
The following tools are needed to build qpid-interop-test:
* git
* gcc-c++
* Python 2.7.x
* Python 3.x
* cmake
* Java JDK
* Maven
* JSON cpp
The following Qpid components must be installed *before* you build and install
qpid-interop-test:
* Qpid Proton C++ development
* Qpid Python
* Python2 Qpid Proton
* Python3 Qpid Proton
The following are not required, but if installed and present, will be tested:
* Rhea (a JavaScript client, also requires npm and nodejs)
* AMQP.Net Lite (requires mono)
In addition, if you wish to run the tests against a broker on the build machine,
it will be necessary to have a running broker. One of the following may be
installed and started against which to run the interop tests as a local broker:
* Artemis Java broker
* ActiveMQ Java broker
* Qpid C++ broker
* Qpid Dispatch router (which may be used as a single node, or as part of a
routed configuration)
Any AMQP 1.0 broker should work. Tests can also be run against a
remote broker provided the broker IP address is known.
These pre-requisites can be installed using the standard system package manager
(yum, dnf, apt-get etc.) OR built from source and installed.
These are the install steps:
1. Install prerequisites, from packages or source
2. Install or download / build AMQP brokers to test against
3. Build qpid-interop-test
4. Run the tests
## 2. Install prerequisites
### 2.1 RHEL6
Currently **RHEL6 is not supported** because it uses Python 2.6.x, and the test code uses
features of Python 2.7.x. This may be supported in a future release.
### 2.2 RHEL7
From a clean install:
````
yum install cmake maven java-1.8.0-openjdk-devel perl-XML-XPath
````
Some packages will need to be downloaded from [EPEL](https://fedoraproject.org/wiki/EPEL).
To set up the EPEL repo in yum:
````
wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install epel-release-latest-7.noarch.rpm
````
then install the following packages:
````
yum -y install jsoncpp-devel nodejs-rhea qpid-proton-cpp-devel python-qpid-proton qpid-proton-cpp-devel python2-qpid-proton
````
### 2.3 Fedora 28
All packages are available directly from the Fedora repositories:
````
dnf -y install gcc-c++ cmake maven java-1.8.0-openjdk-devel perl-XML-XPath jsoncpp-devel nodejs-rhea qpid-proton-cpp-devel python-qpid-proton qpid-proton-cpp-devel python2-qpid-proton python3-qpid-proton
````
### 2.4 CentOS7 Docker image
Docker images come with only the bare essentials, so there is more to install than a standard bare-metal install:
````
yum -y install vim unzip wget git gcc-c++ make cmake maven swig java-1.8.0-openjdk-devel perl-XML-XPath python-devel procps-ng
````
Some packages will need to be downloaded from [EPEL](https://fedoraproject.org/wiki/EPEL).
To set up the EPEL repo in yum:
````
wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install epel-release-latest-7.noarch.rpm
````
then install the following packages:
````
yum -y install mono-devel python34-devel jsoncpp-devel nodejs-rhea qpid-proton-cpp-devel python-qpid-proton qpid-proton-cpp-devel python2-qpid-proton
````
Note that at the time of release, there is no python3-qpid-proton package available for CentOS7, but this should be available soon. Tests should be run with
the --exclude-shim ProtonPython3 flag to avoid errors.
### 2.5 Fedora 28 Docker image
````
dnf -y install vim unzip wget procps-ng git gcc-c++ make cmake maven swig java-1.8.0-openjdk-devel perl-XML-XPath python-devel mono-devel python3-devel jsoncpp-devel nodejs-rhea python-qpid-proton qpid-proton-cpp-devel python2-qpid-proton python3-qpid-proton
````
## 2. Obtaining a broker
Qpid-interop-test requires a running broker to be available. This
may be on localhost as a local install or build, or on another machine, in which case its
IP addresss must be known. Some local broker install options are:
### 2.1 ActiveMQ 5
Download from [Apache](http://activemq.apache.org/download.html).
Make the following changes to the `activemq.xml` config file: For XML element
`broker.transportConnectors.transportConnector@name="amqp"` add the attribute
`wireFormat.allowNonSaslConnections=true`. ie:
````
<transportConnector name="amqp" uri="amqp://0.0.0.0:5672?maximumConnections=1000&amp;wireFormat.maxFrameSize=1048576000&amp;wireFormat.allowNonSaslConnections=true"/>
````
### 2.2 Artemis
Download from [Apache](https://activemq.apache.org/artemis/download.html).
### 2.3 Qpid cpp broker
yum -y install qpid-cpp-server # CentOS7/RHEL
or
dnf -y install qpid-cpp-server # Fedora 28
and set the configuration file in /etc/qpid/qpidd.conf as follows:
````
auth=no
queue-patterns=qit
````
The broker may be started via service, but if running in a Docker container, this may not work. In this case, start the broker directly:
/sbin/qpidd -d
and can be stopped with
/sbin/qpidd -q
### 2.4 Qpid Dispatch Router
yum install qpid-dispatch-router
and add the following to the config file in /etc/qpid-dispatch/qdrouterd.conf:
````
listener {
host: ::1
port: amqp
authenticatePeer: no
saslMechanisms: ANONYMOUS
}
````
The broker may be started via service, but if running in a Docker container, this may not work. In this case, start the broker directly:
/sbin/qdrouterd -d
and can be stopped with
pkill qdrouterd # Needs procps-ng package installed in Docker containers
## 3. Install qpid-interop-test
Qpid-interop-test may be installed locally (preferred for local builds) or to the system
(which requires root privileges). For a local install, use the `-DCMAKE_INSTALL_PREFIX`
option to the `cmake` command. If it is omitted, then qpid-interop-test will be installed
into the default system directories. The source may be unpacked, or (if you need to use the
latest and greatest), cloned from git:
git clone https://git-wip-us.apache.org/repos/asf/qpid-interop-test.git
or
git clone https://github.com/apache/qpid-interop-test.git
Assuming the source tree is located in directory qpid-interop-test:
````
cd qpid-interop-test
git tag -l # See list of tags
git checkout tags/<tagname> # tagname is the release, for example 0.2.0-rc3
mkdir build
cd build
````
For a local install:
````
cmake -DCMAKE_INSTALL_PREFIX=<abs-path-to-local-install-dir> ..
make install
````
For a system install (root privileges are required):
````
cmake ..
make
sudo make install
````
## 4. Run the tests
### 4.1 Set the environment
The config.sh script is in the qpid-interop-test build directory:
````
source build/config.sh
````
### 4.2 Start the test broker
If the broker is at a remote location rather than localhost, the IP address must be known. In tests using
the Qpid Dispatch Router, then the entire broker network must be running before the tests are run. The IP
addresses of the sender (the broker to which messages are being sent) and receiver (the broker from which
messages will be received) must be known.
### 4.3 Run chosen tests
The available tests are:
| Module | Description | Clients |
| ------ | ----------- | ------- |
| amqp_complex_types_test | Tests complex AMQP 1.0 types | C++ Python2 Python3 |
| amqp_large_content_test | Tests implementation of large messages up to 10MB | C++ Python2 Python3 AMQP.NetLite |
| amqp_types_test | Tests the implementation of AMQP 1.0 types | C++ Python2 Python3 Rhea AMQP.NetLite |
| jms_hdrs_props_test | Tests JMS headers and properties | C++ JMS Python2 Python3 |
| jms_messages_test | Tests all JMS message types (except ObjectMessage) | C++ JMS Python2 Python3 |
Each test has command-line options which can be used to limit or modify the test, use the `--help` option to see
these options.
The preferred method to run the tests is using the Python module option as follows:
````
python -m qpid_interop_test.amqp_types_test
python -m qpid_interop_test.jms_messages_test
...
````
If the broker is remote, use the following to point to the broker(s):
````
python -m qpid_interop_test.amqp_types_test --sender <broker-ip-addr> --receiver <broker-ip-addr>
python -m qpid_interop_test.jms_messages_test --sender <broker-ip-addr> --receiver <broker-ip-addr>
...
````
In tests using the Qpid dispatch router, a multi-node configuration may be set up such that messages
are sent to a different broker to that from which they will be received. For example, to send to
broker A and receive from broker B:
````
python -m qpid_interop_test.amqp_types_test --sender <broker-ip-addr-A> --receiver <broker-ip-addr-B>
python -m qpid_interop_test.jms_messages_test --sender <broker-ip-addr-A> --receiver <broker-ip-addr-B>
...
````
**CentOS7 Note:**
CentOS7 does not have the `python3-qpid-proton` package available at the time of the 0.2.0 release. To avoid
errors in the test on CentOS7 (which does not yet auto-detect but assumes the availability of this package), use the
`--exclude-shim ProtonPython3` command-line parameter to disable this shim. See
[QPIDIT-126](https://issues.apache.org/jira/browse/QPIDIT-126) for progress and further details on this issue.
## 5. Optional Components
### 5.1 AMQP.Net Lite Client
A detailed description of how to install and run the AMQP.Net Lite client on Fedora may be found at Apache
JIRA [QPIDIT-105](https://issues.apache.org/jira/browse/QPIDIT-105), and can easily be adapted to other
Linux operating systems. The following packages need to be installed:
* Mono
* Pre-compiled AMQP.Net Lite library (available from https://www.nuget.org/api/v2/package/AMQPNetLite/)
See the above JIRA for detailed instructions. Here is a summary:
Download/install the Amqp.Net Lite dlls. They are initially zipped, unzip them into a well-known location.
Make sure you can find the path to the required .dll file for the version you are using, for example:
```
/abs/path/to/amqp.netlite/lib/net45
```
When building qpid-interop-test (section 3 above), add the following environment variable to the cmake parameters:
`-DAMQPNETLITE_LIB_DIR=<abs/path/to/amqp.netlite/lib/net45>`. When cmake completes, look for the following:
```
-- BUILD_AMQPNETLITE = ON
```
which shows that the dll was found and the .netlite tests will be enabled. If you see the following,
then the required dll was not found:
```
-- BUILD_AMQPNETLITE = OFF
```
The messages immediately preceding this will give a clue as to why it was not found, one of `AMQPNETLITE_LIB_DIR`
not defined or `Amqp.Net.dll` was not found in the path.
### 5.2 Rhea JavaScript Client
The following packages need to be installed:
* nodejs
* npm
The Rhea source may be cloned from github:
git clone https://github.com/amqp/rhea.git
If the `rhea` directory is discovered when qpid-interop-test runs `cmake`, then the Rhea client tests
will be enabled. If the directory is not found, it may be set through the `RHEA_DIR` variable
when running `cmake`.