docs/books/user-guide/getting-started.adoc - qpid-dispatch - Git at Google

 ////
 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
 ////

 [id='getting-started']
 = Getting Started

 Before configuring {RouterName}, you should understand how to start the router, how it is configured by default, and how to use it in a simple peer-to-peer configuration.

 [id='starting-the-router']
 == Starting the Router

 .Procedure

 // Step 1 for starting the router.
 include::{FragmentDir}/fragment-starting-router-step.adoc[]
 +
 [NOTE]
 ====
 You can specify a different configuration file with which to start the router. For more information, see xref:methods-for-changing-router-configuration[_Changing a Router's Configuration_].
 ====
 +
 The router starts, using the default configuration file stored at `/etc/qpid-dispatch/qdrouterd.conf`.

 . View the log to verify the router status:
 +
 [options="nowrap"]
 ----
 $ qdstat --log
 ----
 +
 This example shows that the router was correctly installed, is running, and is ready to route traffic between clients:
 +
 [options="nowrap"]
 ----
 $ qdstat --log
 Fri May 20 09:38:03 2017 SERVER (info) Container Name: Router.A // <1>
 Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone mode // <2>
 Fri May 20 09:38:03 2017 ROUTER_CORE (info) Router Core thread running. 0/Router.A
 Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription M/$management
 Fri May 20 09:38:03 2017 AGENT (info) Activating management agent on $_management_internal // <3>
 Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$management
 Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$_management_internal
 Fri May 20 09:38:03 2017 DISPLAYNAME (info) Activating DisplayNameService on $displayname
 Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$displayname
 Fri May 20 09:38:03 2017 CONN_MGR (info) Configured Listener: 0.0.0.0:amqp proto=any role=normal // <4>
 Fri May 20 09:38:03 2017 POLICY (info) Policy configured maximumConnections: 0, policyFolder: '', access rules enabled: 'false'
 Fri May 20 09:38:03 2017 POLICY (info) Policy fallback defaultApplication is disabled
 Fri May 20 09:38:03 2017 SERVER (info) Operational, 4 Threads Running // <5>
 ----
 <1> The name of this router instance.
 <2> By default, the router starts in _standalone_ mode, which means that it cannot connect to other routers or be used in a router network.
 <3> The management agent. It provides the `$management` address, through which management tools such as `qdmanage` and `qdstat` can perform create, read, update, and delete (CRUD) operations on the router. As an AMQP endpoint, the management agent supports all operations defined by the link:https://www.oasis-open.org/committees/download.php/54441/AMQP%20Management%20v1.0%20WD09[AMQP management specification (Draft 9)].
 <4> A listener is started on all available network interfaces and listens for connections on the standard AMQP port (5672, which is not encrypted).
 <5> Threads for handling message traffic and all other internal operations.

 == Routing Messages in a Peer-to-Peer Configuration

 // XXX Calling this peer-to-peer poses some problems.  It's also
 // technically client-server in this instance, and most people think
 // those two things are exclusive.

 This example demonstrates how the router can connect clients by receiving and sending messages between them. It uses the router's default configuration file and does not require a broker.

 .Peer-to-peer Communication
 image::01-peer-to-peer.png[Peer-to-peer Communication, align="center"]

 As the diagram indicates, the configuration consists of an {RouterName} component with two clients connected to it: a sender and a receiver. The receiver wants to receive messages on a specific address, and the sender sends
 messages to that address.

 A broker is not used in this example, so there is no _"store and forward"_ mechanism in the middle. Instead, the messages flow from sender to receiver only if the receiver is online, and the sender can confirm that the messages have arrived at their destination.

 This example uses a {ClientAmqpPythonName} client to start a receiver client, and then send five messages from the sender client.

 .Prerequisites

 {ClientAmqpPythonName} must be installed before you can complete the peer-to-peer routing example. For more information, see {ClientAmqpPythonUrl}.

 .Procedure

 . xref:starting-the-receiver-client[Start the receiver client].
 . xref:sending-messages[Send messages].

 [id='starting-the-receiver-client']
 === Starting the Receiver Client

 In this example, the receiver client is started first. This means that the messages will be sent as soon as the sender client is started.

 [NOTE]
 ====
 In practice, the order in which you start senders and receivers does not matter. In both cases, messages will be sent as soon as the receiver comes online.
 ====

 .Procedure

 * To start the receiver by using the Python receiver client, navigate to the Python examples directory and run the `simple_recv.py` example:
 +
 --
 [options="nowrap",subs="+quotes"]
 ----
 $ cd __INSTALL_DIR__/examples/python/
 $ python simple_recv.py -a 127.0.0.1:5672/examples -m 5
 ----

 This command starts the receiver and listens on the default address (`127.0.0.1:5672/examples`). The receiver is also set to receive a maximum of five messages.
 --

 [id='sending-messages']
 === Sending Messages

 After starting the receiver client, you can send messages from the sender. These messages will travel through the router to the receiver.

 .Procedure

 * In a new terminal window, navigate to the Python examples directory and run the `simple_send.py` example:
 +
 --
 [options="nowrap",subs="+quotes"]
 ----
 $ cd __INSTALL_DIR__/examples/python/
 $ python simple_send.py -a 127.0.0.1:5672/examples -m 5
 ----

 This command sends five auto-generated messages to the default address (`127.0.0.1:5672/examples`) and then confirms that they were delivered and acknowledged by the receiver:

 [options="nowrap"]
 ----
 all messages confirmed
 ----

 The receiver client receives the messages and displays their content:

 [options="nowrap"]
 ----
 {u'sequence': 1L}
 {u'sequence': 2L}
 {u'sequence': 3L}
 {u'sequence': 4L}
 {u'sequence': 5L}
 ----
 --
	////
	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
	////

	[id='getting-started']
	= Getting Started

	Before configuring {RouterName}, you should understand how to start the router, how it is configured by default, and how to use it in a simple peer-to-peer configuration.

	[id='starting-the-router']
	== Starting the Router

	.Procedure

	// Step 1 for starting the router.
	include::{FragmentDir}/fragment-starting-router-step.adoc[]
	+
	[NOTE]
	====
	You can specify a different configuration file with which to start the router. For more information, see xref:methods-for-changing-router-configuration[_Changing a Router's Configuration_].
	====
	+
	The router starts, using the default configuration file stored at `/etc/qpid-dispatch/qdrouterd.conf`.

	. View the log to verify the router status:
	+
	[options="nowrap"]
	----
	$ qdstat --log
	----
	+
	This example shows that the router was correctly installed, is running, and is ready to route traffic between clients:
	+
	[options="nowrap"]
	----
	$ qdstat --log
	Fri May 20 09:38:03 2017 SERVER (info) Container Name: Router.A // <1>
	Fri May 20 09:38:03 2017 ROUTER (info) Router started in Standalone mode // <2>
	Fri May 20 09:38:03 2017 ROUTER_CORE (info) Router Core thread running. 0/Router.A
	Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription M/$management
	Fri May 20 09:38:03 2017 AGENT (info) Activating management agent on $_management_internal // <3>
	Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$management
	Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$_management_internal
	Fri May 20 09:38:03 2017 DISPLAYNAME (info) Activating DisplayNameService on $displayname
	Fri May 20 09:38:03 2017 ROUTER_CORE (info) In-process subscription L/$displayname
	Fri May 20 09:38:03 2017 CONN_MGR (info) Configured Listener: 0.0.0.0:amqp proto=any role=normal // <4>
	Fri May 20 09:38:03 2017 POLICY (info) Policy configured maximumConnections: 0, policyFolder: '', access rules enabled: 'false'
	Fri May 20 09:38:03 2017 POLICY (info) Policy fallback defaultApplication is disabled
	Fri May 20 09:38:03 2017 SERVER (info) Operational, 4 Threads Running // <5>
	----
	<1> The name of this router instance.
	<2> By default, the router starts in _standalone_ mode, which means that it cannot connect to other routers or be used in a router network.
	<3> The management agent. It provides the `$management` address, through which management tools such as `qdmanage` and `qdstat` can perform create, read, update, and delete (CRUD) operations on the router. As an AMQP endpoint, the management agent supports all operations defined by the link:https://www.oasis-open.org/committees/download.php/54441/AMQP%20Management%20v1.0%20WD09[AMQP management specification (Draft 9)].
	<4> A listener is started on all available network interfaces and listens for connections on the standard AMQP port (5672, which is not encrypted).
	<5> Threads for handling message traffic and all other internal operations.

	== Routing Messages in a Peer-to-Peer Configuration

	// XXX Calling this peer-to-peer poses some problems. It's also
	// technically client-server in this instance, and most people think
	// those two things are exclusive.

	This example demonstrates how the router can connect clients by receiving and sending messages between them. It uses the router's default configuration file and does not require a broker.

	.Peer-to-peer Communication
	image::01-peer-to-peer.png[Peer-to-peer Communication, align="center"]

	As the diagram indicates, the configuration consists of an {RouterName} component with two clients connected to it: a sender and a receiver. The receiver wants to receive messages on a specific address, and the sender sends
	messages to that address.

	A broker is not used in this example, so there is no _"store and forward"_ mechanism in the middle. Instead, the messages flow from sender to receiver only if the receiver is online, and the sender can confirm that the messages have arrived at their destination.

	This example uses a {ClientAmqpPythonName} client to start a receiver client, and then send five messages from the sender client.

	.Prerequisites

	{ClientAmqpPythonName} must be installed before you can complete the peer-to-peer routing example. For more information, see {ClientAmqpPythonUrl}.

	.Procedure

	. xref:starting-the-receiver-client[Start the receiver client].
	. xref:sending-messages[Send messages].

	[id='starting-the-receiver-client']
	=== Starting the Receiver Client

	In this example, the receiver client is started first. This means that the messages will be sent as soon as the sender client is started.

	[NOTE]
	====
	In practice, the order in which you start senders and receivers does not matter. In both cases, messages will be sent as soon as the receiver comes online.
	====

	.Procedure

	* To start the receiver by using the Python receiver client, navigate to the Python examples directory and run the `simple_recv.py` example:
	+
	--
	[options="nowrap",subs="+quotes"]
	----
	$ cd __INSTALL_DIR__/examples/python/
	$ python simple_recv.py -a 127.0.0.1:5672/examples -m 5
	----

	This command starts the receiver and listens on the default address (`127.0.0.1:5672/examples`). The receiver is also set to receive a maximum of five messages.
	--

	[id='sending-messages']
	=== Sending Messages

	After starting the receiver client, you can send messages from the sender. These messages will travel through the router to the receiver.

	.Procedure

	* In a new terminal window, navigate to the Python examples directory and run the `simple_send.py` example:
	+
	--
	[options="nowrap",subs="+quotes"]
	----
	$ cd __INSTALL_DIR__/examples/python/
	$ python simple_send.py -a 127.0.0.1:5672/examples -m 5
	----

	This command sends five auto-generated messages to the default address (`127.0.0.1:5672/examples`) and then confirms that they were delivered and acknowledged by the receiver:

	[options="nowrap"]
	----
	all messages confirmed
	----

	The receiver client receives the messages and displays their content:

	[options="nowrap"]
	----
	{u'sequence': 1L}
	{u'sequence': 2L}
	{u'sequence': 3L}
	{u'sequence': 4L}
	{u'sequence': 5L}
	----
	--