Overview of IBM MessageSight
Interactions with the Internet no longer happen solely by individuals who are using a computer. Users connect to the Internet with a variety of devices, such as mobile phones, sensors, and machines, because the ubiquity of TCP/IP over 3G and 4G cellular networks enables these various types of devices to send and receive data.
The Internet is transitioning to the Internet of Things (IoT), where things or machines, connect to machines (M2M), and interact with reduced, if any, human intervention. With the numbers of devices in use increasing, organizations require a scalable, reliable, and cost-effective solution for connecting these devices to their system of records.
The IBM MessageSight messaging appliance helps to deliver the performance, value, and simplicity that organizations need for accommodating this multitude of devices and processing large volumes of events in real time.
MessageSight extends existing messaging networks by adding the following characteristics:
•Fast transaction rates
•Consistent lower latency
•Extensive scaling in the number of concurrent devices that can be connected
•Suitable for deployment in a demilitarized zone (DMZ)
This chapter provides details about the following topics:
3.1 Features of MessageSight
Application owners and consumers require large-scale connectivity and a high-speed communication solution to enable the real-time capture of interactions between the multitude of connected devices and applications.
The explosion in the number of mobile devices, such as smartphones and tablets, is creating many endpoints. Consumers expect real-time communication between their devices and applications. Building these applications relies on a scalable, bidirectional communication infrastructure. Emerging standards, such as HTML5 web sockets, provide the basis for building rich mobile, intranet, and Internet applications.
By enabling the use of messaging protocols, such as Message Queuing Telemetry Transport (MQTT), MessageSight is a highly scalable middleware messaging product that provides the full-duplex web communication that is required for these mobile, intranet, and Internet applications.
|
Note: Message Queuing Telemetry Transport (MQTT) is a messaging protocol designed for wireless networks and devices with which conserving device battery life, reducing network traffic, and delivering reliable messages over unreliable networks are key. MQTT is an open protocol with no-cost MQTT clients available for a wide range of mobile platforms.
For details about the MQTT protocol, see Appendix A, “The Message Queuing Telemetry Transport (MQTT) protocol” on page 233.
|
Figure 3-1 shows the wireless MQTT protocol as it connects to MessageSight, inside an enterprise network.
Figure 3-1 The wireless MQTT protocol connects to MessageSight, inside an enterprise network
MessageSight offers the following features:
•Providing a quick and simplified deployment
The appliance can be configured for a typical environment within about 30 minutes. The web user interface (UI) helps to guide administrators through the initial steps. Configuration is simple, using either the web UI or command-line interface (CLI). Administration is optimized for scale using a policy-based approach.
•Enabling the messaging infrastructure for use in a DMZ
The MessageSight appliance is designed to sit at the edge of the enterprise, from where it can extend an existing messaging infrastructure or be used as a stand-alone appliance.
MessageSight has no user accessible operating system and only accepts signed and encrypted firmware. Only configured services can enable listening ports with no routing throughout the network interfaces. MessageSight consists of encrypted compact flash and storage media. The compact flash is locked down and tied to system use.
•Providing security-rich messaging using a policy-based approach
Messaging policies allow you to filter for specific access. Options are available to add Secure Sockets Layer/Transport Layer Security (SSL/TLS), including Federal Information Processing Standard (FIPS) 140-2.
•Employing open standards and protocols for greater flexibility
MessageSight supports the MQTT V3.1 specification, MQTT over HTML5 websockets, and Java Message Service (JMS 1.1) for inbound and outbound messaging. MessageSight also supports protocol mediation.
•Providing high reliability and performance
High availability configurations are supported when using a pair of MessageSight appliances. In addition, high-message throughput for millions of messages/second over one million concurrent, connected devices can be supported on each MessageSight appliance. This enables a massive fan out streaming of data, processing 13 million non-persistent messages/second. When assured delivery matters, the device can process 400 thousand persistent messages/second.
With MessageSight, message latency is measured in microseconds and remains consistent when scaled out. In this way, connecting many MQTT clients to MessageSight will not affect the internal latency of MessageSight.
•Enabling integration with enterprises
MessageSight supports Java Message Service (JMS), MQTT over HTML5 websockets, and the MQTT protocol. It has built-in connectivity with IBM WebSphere MQ, making it possible to connect to multiple back-end queue managers.
|
Note: MessageSight can be used with all supported WebSphere MQ platforms WebSphere MQ version 7.1 and later.
|
3.1.1 MessageSight is a developer-friendly solution
With MessageSight, the simple yet powerful application programming interfaces (APIs) provided by MQTT clients make application development easy. A simple paradigm of connect/disconnect, subscribe/unsubscribe, and publish promotes loosely coupled and scalable applications.
Because of the efficiency of the MQTT messaging protocol, which is faster and requires less bandwidth and less battery power than traditional HTTP, MessageSight is optimized for wireless clients. The event-oriented paradigm provides for a better customer experience. The developer-friendly application programming interfaces (APIs) and libraries can be used for a variety of mobile OSs, including Google’s Android and Apple’s iOS.
|
Note: Developers can use a version of the MessageSight virtual appliance that is available at no charge from the IBM Mobile and machine-to-machine (M2M) community:
|
3.1.2 Connections to MessageSight
This section presents an overview of the components and connections in a MessageSight solution.
Figure 1-5 on page 13 shows examples of how clients who are connected to MessageSight can interface with WebSphere MQ and other back-end applications.
MessageSight supports client applications using specific protocols. At the time of publishing, IBM provides the following clients for these protocols:
•MQTT over TCP/IP:
– MQTT C client
– MQTT client for Android
– MQTT client for Java
– MQTT client for iOS
•MQTT over websockets
MQTT client for JavaScript
•JMS
MessageSight JMS client
3.2 Messaging patterns of MessageSight
Messaging patterns identify the common message flows that are used in messaging solutions. There are five messaging patterns that are supported by MessageSight:
•Fan out broadcast
•Fan in per device notification
•Fan out per device notification
•Fan out per device request-reply
•Fan in per device request-reply
3.2.1 Fan out broadcast
For this messaging pattern, one publisher device publishes a message to a specific topic string. The messages have many subscriber devices. Figure 3-2 on page 49 depicts the fan out broadcast pattern.
Figure 3-2 Fan out broadcast messaging pattern
One use of this pattern is when broadcasting data related to the location of a connected vehicle. As an example, this is useful for broadcasting an updated vehicle position.
3.2.2 Fan in per device notification
For this messaging pattern, many publisher devices publish messages to a topic string. The messages have one subscriber device. Figure 3-3 presents the fan in per device notification pattern.
Figure 3-3 Fan in per device notification messaging pattern
One use of this pattern is when receiving data from a number of sensors. As an example, this is useful when receiving data from earthquake sensors.
3.2.3 Fan out per device notification
For this messaging pattern, one publisher device publishes messages to many topic strings. Each message has only one subscriber device. Figure 3-4 presents the fan out per device notification pattern.
Figure 3-4 Fan out per device notification messaging pattern
One use of this pattern is when sending control commands to a device. As an example, this is useful when sending a command to an application to activate a feature.
For this messaging pattern, each subscriber must subscribe to a unique topic. By using the unique client ID, group ID, or user ID of the subscribing application in the topic string, you can ensure that each topic is unique. For example, a subscriber application instance that connects with client ID 123 subscribes to RESPONSE/123. A subscriber application instance that connects with client ID 456 subscribes to RESPONSE/456. A subscriber application instance with client ID 789 subscribes to RESPONSE/789.
To ensure that subscribers cannot access topics of other subscribers, you can use the topic string variable substitution that is available in MessageSight messaging policies. By using topic string variable substitution, you can create a messaging policy with a single topic string that includes a user ID, group ID, or client ID variable.
This substitution ensures that applications can subscribe only to the topic string that matches their user ID, group ID, or client ID. For example, a topic string of RESPONSE/${ClientID} is specified in the messaging policy. The application with client ID 123 is allowed to subscribe to RESPONSE/123, but is not allowed to subscribe to RESPONSE/456 or RESPONSE/789 because the client IDs do not match.
3.2.4 Fan out per device request-reply
For this messaging pattern, one publisher device publishes messages to many topic strings. Each topic string has only one subscriber device. Each subscriber device publishes reply messages on a separate topic string. The publisher device subscribes to all the reply topics. Figure 3-5 presents the fan out per device request-reply pattern.
Figure 3-5 Fan out per device request-reply messaging pattern
One use of this pattern is when a control center is interrogating the state of a device. As an example, this is useful when requesting a temperature reading from a sensor.
3.2.5 Fan in per device request-reply
Many publisher devices publish messages to many topic strings. A single subscriber device subscribes to all of the topic strings. The subscriber device publishes reply messages on separate topic strings for each publisher device. Figure 3-6 on page 52 presents the fan in per device request-reply pattern.
Figure 3-6 Fan in per device request-reply messaging pattern
One use of this pattern is when a device is polling a control center for information updates. As an example, this is useful when polling for information about firmware updates.
3.3 Install the MessageSight virtual appliance (for developers)
This section describes how the development community can install the MessageSight virtual appliance at no charge.
This virtual edition is to be used in a development environment only. The benefit of this developer-focused virtual appliance is that it enables rapid application development. It enables developers to get started quickly in coding and testing applications to work with MessageSight. This virtual appliance is suitable for deploying in IBM VMware and Oracle VirtualBox environments.
|
Note: All details regarding the installation of the MessageSight physical appliance installation are in the publication, Responsive Mobile User Experience Using MQTT and IBM MessageSight, SG24-8183.
|
|
Note: Developers can use the version of the MessageSight virtual appliance that is available at no charge from the IBM Mobile and M2M community:
|
After using the Open Virtual Archive (OVA) file of the MessageSight virtual edition, follow these steps for a VMware workstation environment:
1. If not already running, start VMware.
2. Select File → Open from the menu.
3. Import the OVA file by entering a name for the new virtual machine and a storage path.
4. Navigate to the location of the MessageSight OVA image.
5. Select the IBMMessageSightVx.y.ova file and click Open.
|
Note: At the time of publishing, the latest release of the MessageSight virtual appliance is 1.1. Therefore, the OVA file to import is IBMMessageSightV1.1.ova.
|
Wait for the end of the import process. The import process might take several minutes to complete.
6. Define the settings for the newly imported MessageSight virtual image. The minimum requirements to run the MessageSight virtual appliance are listed:
– Memory: 4 GB
– Processors: 2
– Hard disk: 16 GB
– Network settings: In this installation example, we use a network address translation (NAT) network adapter. The NAT is configured to use the dynamic host configuration protocol (DHCP), but you can choose any network adapter type. If you are not using DHCP, see the MessageSight Ethernet interfaces configuration guide available in the MessageSight IBM Knowledge Center:
7. Click the Power on this virtual machine link.
Wait for the virtual machine to start. This might take a couple of minutes.
Figure 3-7 shows the start of the boot process of the MessageSight virtual appliance.
Figure 3-7 The boot process begins on the MessageSight virtual appliance
8. Click in the VMware window.
Figure 3-8 Log in as administrator to connect to the virtual MessageSight appliance
10. Type admin as the password and press Enter.
11. At this step, an Ethernet adapter must be configured. Press Enter to accept the default adapter: eth0, as shown in Figure 3-9 on page 54.
Figure 3-9 Configure network interface eth0
12. Enter yes and press Enter to select DHCP rather than assigning a fixed address.
13. Press Enter to confirm the selection, as shown in Figure 3-10.
Figure 3-10 Use DHCP to configure network interface eth0
14. The interface is configured using DHCP. Record the assigned address. This address is used to communicate with the appliance.
The command ethernet-interface eth0 can be used to display the address assigned to an Ethernet port, as shown in Figure 3-11.
Figure 3-11 Ethernet interface status for network interface eth0
15. To exit the VMware image, press Ctrl + Alt simultaneously.
|
Note: If you make a mistake in configuring the value of eth0, type the following command at a command prompt and make the necessary corrections:
edit ethernet-interface eth0
|
3.4 Overview of the MessageSight web UI
This section presents an overview of the web UI for the physical and virtual MessageSight appliance. Access the UI from a supported web browser. For a list of supported web browsers, visit the MessageSight IBM Knowledge Center:
|
Note: All details regarding the installation of the MessageSight physical appliance installation are in the Redbooks publication, Responsive Mobile User Experience Using MQTT and IBM MessageSight, SG24-8183.
|
The host name or IP address of the MessageSight appliance is required to access the web UI. The HTTPS protocol is used to secure the communication between appliance users and the MessageSight appliance.
|
Note: The default listening port of the MessageSight web UI is 9087. This value is configurable.
|
3.4.1 Connect to the MessageSight appliance
The MessageSight certificate that establishes secure communications with the web browser is a self-signed certificate. Therefore, your browser might warn you that the connection is untrusted. Confirm the security exception to access the MessageSight web UI.
Use the following steps to connect to the MessageSight appliance using the web UI:
1. Open a supported web browser and enter the following URL:
2. Accept the MessageSight self-signed certificate, and the login window shown in Figure 3-12 on page 56 opens.
Figure 3-12 MessageSight login window
3. Enter the login and password to access the MessageSight web UI. The default values are shown:
– Login: admin
– Password: admin
4. View and accept the software licensing agreement that displays at your first connection to the web UI.
The MessageSight web UI First Steps tab displays. Here, you can configure the range for Ethernet client connections, and configure a default gateway, or change the default password for the administrator account, as shown in Figure 3-13 on page 57. To change the default administrator password at a later time, see “Reset an existing password (all user roles)” on page 67.
Figure 3-13 MessageSight web UI First Steps tab
|
Note: Use the Classless Inter-Domain Routing (CIDR) notation to define the IP address range property.
|
5. Click Save and Close to save and close your changes, and click the Home tab to display the MessageSight web UI home page, as shown in Figure 3-14 on page 58.
Figure 3-14 MessageSight Home page
3.4.2 The MessageSight Home page
The MessageSight home page is divided into two sections:
Figure 3-15 Common configuration and customization tasks
This panel guides you through the configuration and test of the following elements:
– Verify your network configuration with the MessageSight Messaging Tester
The Messaging tester is a simple graphical tool that can help to test the connections to a network interface of a MessageSight appliance. The Messaging Tester is a web client based on JavaScript, which uses MQTT over websockets for communications with MessageSight through one of its network interface adapters.
Using the Messaging Tester, you can configure up to five MQTT clients that are executing publications and subscriptions, as shown in Figure 3-16 on page 60.
Figure 3-16 MessageSight Messaging Tester
– Customize appliance settings
Here, you can configure the network, date, and time settings, and perform other system tasks.
– Secure your appliance
Security profiles, groups, and messaging users are configured through the Security Settings. The configuration parameters of the web UI are also accessible through this menu.
– Create users and groups
Two types of users can be defined and a MessageSight appliance: the appliance users (people who need to connect to MessageSight to configure or monitor the appliance) and the messaging users (who access message hubs and endpoints configured on the appliance through MQTT), and JMS clients (a mobile device user, for instance).
– Configure MessageSight to accept connections
This menu is used to configure message hubs, endpoints, messaging and connection policies, and MQ Connectivity.
Figure 3-17 MessageSight appliance web UI dashboard
The appliance dashboard displays the following information:
– Quick Stats: The numbers of accepted and rejected incoming messages, active connections, messages per second, appliance uptime, disk and memory usage, and last firmware update.
– Active connections and Throughput: Shows the average active connections and average messages per second.
The following sections describe the execution of several basic administration tasks using the MessageSight web UI.
3.4.3 Administrator actions using the MessageSight web UI
Several of the more common administrator tasks using the web UI are discussed in this section.
Determine the status of the MessageSight server
The status of a MessageSight server can be determined by using the Status selection list that displays at the top of the MessageSight control panel, as shown in Figure 3-18 on page 62.
Figure 3-18 The MessageSight control panel shows the status of MessageSight servers
In our example, the server is running, and ready for use.
Display the firmware version of a MessageSight appliance
There are two ways to display the firmware version from the web UI. The first method is used by all appliance users. The second method can be used by administrators only.
•First method
All appliance users can use this method. For a description of the user roles available in MessageSight, see “User roles and configuring users” on page 64.
Connect to MessageSight using the web UI, click the Help (?) icon in the menu bar, as shown in Figure 3-19, and select About.
Figure 3-19 Display the firmware version using the About menu
A window displays the firmware version and build number, as shown in Figure 3-20 on page 63.
Figure 3-20 Firmware version and build number
•Second method
Only MessageSight administrators can use this method for displaying the firmware version. For a description of all user roles available in MessageSight, see “User roles and configuring users” on page 64.
Connect to MessageSight using the web UI, and select Appliance → System Control, as shown in Figure 3-21 on page 64.
Figure 3-21 Accessing the MessageSight control panel
The firmware version displays, as shown in Figure 3-22.
Figure 3-22 Firmware version from the MessageSight control panel
User roles and configuring users
MessageSight supports role-based user actions. The user roles are listed:
•System administrator: Users who have access to every task on the appliance.
•Messaging administrator: Users who have access only for viewing or editing messaging-related tasks. For example, a messaging administrator can configure an endpoint but is not able to configure the SSL or TLS certificates.
•Appliance users: Users who have access to the MessageSight messaging-related views.
For further details about the actions that each type of appliance user can perform, see the following URL:
System administrators can access MessageSight using the web UI or CLI. Access to the CLI interface using Secure Shell (SSH) is denied for messaging uses and appliance users, as shown in Figure 3-23.
Figure 3-23 Access is denied to the MessageSight CLI for users other than system administrators
Configure users
To add, edit, or delete appliance users, complete these steps. This process can be performed only by a system administrator:
1. Connect to the MessageSight web UI using the administrator account. The Home page opens.
Figure 3-24 Create appliance users from the web UI Home page
The list of existing appliance users displays, as shown in Figure 3-25 on page 66.
Figure 3-25 List of existing appliance users
Other ways to add, edit, or delete users, including resetting passwords, are shown:
•Add a user:
Click the plus sign (+) icon. In the window that opens, enter a user name and password, and select a group name to associate the user with: SystemAdministrators, Users, or MessagingAdministrators.
•Edit a user password:
Select the user to edit and click the pencil (edit) icon.
•Delete a user:
Select the user to delete and click the delete (red cross) icon.
Add an appliance user
To create a new appliance user ID, follow these steps:
1. Navigate to the Appliance Users page and click the plus sign (+) icon.
2. In the web UI Users section, click the plus sign (+) icon.
3. When the Add User pop-up box displays, provide the User ID, Password, and Description and select the type of user, as shown in Figure 3-26 on page 67.
Figure 3-26 Adding a new user in the web UI
4. Populate the required details, and click Save.
Reset an existing password (all user roles)
To reset a password on an account for any user role, highlight the account and select Other Actions → Reset Password, as shown in Figure 3-27, which is an example of changing the password for the messaging administrator. Note that this procedure can be used to change the initial, default administrator password, as well.
Figure 3-27 Password reset for the messaging administrator ID
Reset an administrator password (alternate method)
Alternatively, the administrator account password can be changed by navigating to the admin user menu that displays at the upper right of the MessageSight web UI, as shown in Figure 3-28.
Figure 3-28 Change the administrator password from the admin user menu
Any user who is logged in to MessageSight through the web UI can change their password using the Change Password link that displays in the user menu for that user.
3.5 Overview of the MessageSight CLI
The MessageSight appliance provides an extensive CLI, which includes a few utilities and diagnostic tools that are not available using the web UI.
|
Note: All details related to the installation of the MessageSight physical appliance are in the Redbooks publication, Responsive Mobile User Experience Using MQTT and IBM MessageSight, SG24-8183.
|
If you have installed a physical appliance, you can access the MessageSight CLI locally using a keyboard, video, and mouse (KVM) console, or over the network using serial over local area network (LAN) or SSH.
If you have installed a virtual MessageSight appliance, you can access that CLI directly from your hypervisor solution, if you have an administrator name and password, or by using SSH, as well.
For this discussion, we access the MessageSight appliance CLI using an SSH client.
3.5.1 Connect to the MessageSight appliance
Complete these steps to access your MessageSight appliance using SSH:
1. Open your SSH client.
2. Connect to MessageSight using the appliance host name or IP address and port 22, which is the connection port reserved for SSH.
3. At connection time, accept the host key presented by the MessageSight server at the first connection attempt because this host key is not cached in the SSH client registry at the moment.
4. Enter your system administrator login and password to connect to the CLI.
When you are connected, the CLI console displays the response shown in Example 3-1 on page 69.
Example 3-1 Accessing the CLI console using SSH
login as: admin
Using keyboard-interactive authentication.
Password:
Last login: Wed Jul 9 03:24:00 UTC 2014 from 192.168.198.1 on pts/0
Welcome to MessageSight
5725-F96
Copyright 2012, 2013 IBM Corp. Licensed Materials - Property of IBM.
IBM and MessageSight are trademarks or registered trademarks of IBM, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies.
Console>
5. Enter the necessary CLI commands to administer, configure, or monitor your MessageSight appliance.
|
Note: Access the MessageSight V1.1 Command Reference guide in the MessageSight IBM Knowledge Center website:
|
3.5.2 Administrator actions using the MessageSight CLI
In this section, we introduce several of the administrator commands for use with the MessageSight CLI.
Determine the machine type and serial number of a physical or virtual MessageSight appliance
To determine the machine type and serial number of your physical appliance, use the show version command, as shown in Example 3-2.
Example 3-2 Determine your machine type and serial number using the CLI
Console>
Console> show version
Installation date: Dec 4, 2013 8:54:50 PM
Platform version: 5.0.0.19
Platform build ID: build22-20131007-1001
Platform build date: 2013-10-07 14:08:05+00:00
Machine type/model: 7915AC1
Serial number: KQ2H7YC
Entitlement: KQ2H7YC
Firmware type: Release
Console>
You might notice a difference for the Machine type/mode output value if you apply the same show version command on a MessageSight virtual appliance. This is shown in Example 3-3 on page 70.
Example 3-3 Machine type and serial number on a MessageSight virtual appliance
Console>
Console> show version
Installation date: Nov 12, 2013 4:34:04 AM
Platform version: 5.0.0.19
Platform build ID: build22-20131007-1001
Platform build date: 2013-10-07 14:08:05+00:00
Machine type/model: VMware Virtual Platform
Serial number: VMware-56 4d 62 8e 75 24 93 50-32 c0 10 e8 eb 83 fc 5a
Entitlement: VMware-56 4d 62 8e 75 24 93 50-32 c0 10 e8 eb 83 fc 5a
Firmware type: Release
Console>
Determine the status of the Ethernet interface
Use the MessageSight CLI to get the status of an Ethernet interface using the status ethernet-interface command, as shown in Example 3-4, where eth0 is the network interface of the appliance for which you want to retrieve a status.
Example 3-4 Determine the status of an Ethernet interface using the CLI
Console>
Console> status ethernet-interface eth0
eth0 OpState:[Up]
generic MTU:1500 carrier:true
flags:UP BROADCAST RUNNING MULTICAST index:5
inet addr:192.168.198.40 flags:PERMANENT mask:255.255.255.0
scope:GLOBAL
inet6 addr: fe80::20c:29ff:fe83:fc5a flags:PERMANENT
mask: ffff:ffff:ffff:ffff:: scope:LINK
ethernet Link:on MAC: 00:0c:29:83:fc:5a autoneg:on duplex:Full
port:TP speed:1000Mbps
statistics collisions:0 multicast:0 rx_bytes:2330429
rx_compressed:0 rx_crc_errors:0 rx_dropped:0 rx_errors:0
rx_fifo_errors:0 rx_frame_errors:0 rx_length_errors:0
rx_missed_errors:0 rx_over_errors:0 rx_packets:22383
tx_aborted_errors:0 tx_bytes:48742 tx_carrier_errors:0
tx_compressed:0 tx_dropped:0 tx_errors:0 tx_fifo_errors:0
tx_heartbeat_errors:0 tx_packets:354 tx_window_errors:0
Console>
Set and get the node name of a MessageSight appliance
Use the MessageSight CLI to set the appliance node name using the nodename set command, as shown in Example 3-5, were imaDev is the appliance node name.
Example 3-5 Set an appliance node name using the CLI
Console>
Console> nodename set imaDev
Console>
To determine the node name of an appliance, use the nodename get command, as shown in Example 3-6 on page 71.
Example 3-6 Determine an appliance node name using the CLI
Console>
Console> nodename get
nodename is imaDev
Console>
Display the firmware version of a MessageSight appliance
Use the MessageSight CLI to determine the firmware version of an appliance using the show imaserver command, as shown in Example 3-7.
Example 3-7 Determine the firmware version of a MessageSight appliance using the CLI
Console> show imaserver
MessageSight version is 1.1 20131112-0402 2013-11-11 23:04
Console>
Gather information for use by the MessageSight support team
Use the MessageSight CLI to gather information about an appliance using the platform must-gather command. This information is useful for the MessageSight support team. The web UI cannot be used to gather this information.
The platform must-gather command is used for troubleshooting, and for collecting the must-gather diagnostic data for reporting a problem to the MessageSight support team when generating a problem management record (PMR). Sending the output from the platform must-gather command helps the MessageSight support team to resolve your problem more quickly.
To collect this output, complete the following steps:
1. Access the MessageSight CLI.
2. Run the platform must-gather command to create a .tgz file containing diagnostic information. If you have a PMR open with IBM, include that number in the file name.
Console> platform must-gather PMR-12345,67R,890-Jul16.tgz
3. Run the file list command. You will see the file that you created, and a separate collect-pd.txt file, as shown in Example 3-8.
Example 3-8 Listing files
Console>
Console> file list
collect-pd.txt 726876 bytes created Jul 9, 2014 4:25:21 AM
PMR-12345,67R,890-Jul16.tgz 12192195 bytes created Jul 9, 2014 4:25:34 AM
Console>
4. Send the output from the platform must-gather command to the MessageSight support team as part of a PMR problem ticket.
Create a secure backup of a MessageSight appliance
Use the MessageSight CLI to create a secure backup of an appliance using the imaserver backup command. The web UI cannot be used for this task.
For more information about the MessageSight backup and restore processes, see the MessageSight IBM Knowledge Center:
To create a secure backup of an appliance, complete the following steps:
1. Check that the server is running by entering the status imaserver command, as shown in Example 3-9.
Example 3-9 Determine the status of a MessageSight appliance
Console>
Console> status imaserver
Status = Running (production)
ServerUpTime = 0 days 9 hours 59 minutes 26 seconds
Console>
If the server is stopped, start the server by entering the following command:
Console> imaserver start
|
Note: Maintenance mode is a MessageSight server state that allows a system administrator to complete several tasks. In maintenance mode, a system administrator can clean the server store, stop and start the server, and change the server state from maintenance to production.
|
Example 3-10 Set the MessageSight appliance to maintenance mode
Console>
Console> imaserver runmode maintenance
The MessageSight server is currently in "production" mode.
When it is restarted, it will be in "maintenance" mode.
Console> imaserver stop
The MessageSight server is stopping.
Check the MessageSight server status using "status imaserver" command.
Console> imaserver start
The MessageSight server is starting.
The MessageSight server is in "maintenance" mode.
Console>
3. Create a secure backup of the appliance by using the imaserver backup command:
Console> imaserver backup “Password=mybackup_password”
|
Note: The mybackup_password command specifies a password for the compressed file that contains the backup data. You must have the password when you attempt to restore the backup.
|
Example 3-11 Set the MessageSight server to production mode
Console>
Console> imaserver runmode production
The MessageSight server is currently in "maintenance" mode.
When it is restarted, it will be in "production" mode.
Console> imaserver stop
The MessageSight server is stopping.
Check the MessageSight server status using "status imaserver" command.
Console> imaserver start
The MessageSight server is starting.
The MessageSight server is in "production" mode.
Console>
|
Note: Information about how to restore a MessageSight appliance is in the MessageSight IBM Knowledge Center:
•Restoring the MessageSight configuration data to the same appliance:
•Restoring the MessageSight configuration data to a different appliance:
|
3.6 Message hubs, endpoints, and policies
Message hubs are an organizational configuration object that collects the following components:
•Endpoints
•Connection policies
•Messaging policies
These components are associated with a specific goal in a single place. You can create a message hub for an application to organize the endpoints and policies that each application uses.
3.6.1 Endpoints
Endpoints accept network requests so that clients can connect to the message hub through MQTT or JMS. You must have a minimum of one endpoint per message hub. You can create one endpoint for each port the message hub listens on.
Endpoints must have one or more connection policies that are applied to them to accept client connections. Endpoints must have at least one messaging policy that is applied to them for a connected client to be able to publish/subscribe.
Endpoints can be used only within the specified message hub. Separate message hubs cannot specify endpoints on the same IP address and ports. Different message hubs can have endpoints with different IP addresses and the same port. This architecture means that endpoints can be monitored to provide a complete picture of traffic and activity across the message hub. For example, endpoints can be used to track connections and monitor metrics, such as the range of IP addresses used to connect to the message hub, the number of incoming messages, and the number of subscriptions that are associated with a particular message hub.
There are two types of policies that can be defined on the message hub:
•Connection policies: A connection policy filters any connection that is based on a rule. For example, a connection policy might be set up to authorize users that are defined within a particular group or groups to connect from a specific location or range of locations.
•Messaging policies: A messaging policy authorizes a client or user to publish or subscribe to a topic, or to send, receive, or browse messages on a queue. You can apply your messaging policy to a topic or to a queue as part of the specification of the message policy.
|
Note: Messaging policies that are created in the web UI can be used only within the specified message hub. Messaging policies that are created in the CLI can be attached to any endpoint in any message hub.
|
3.6.2 Message hubs
A message hub is an organizational object that groups endpoints, connection policies, and messaging policies that are associated with a specific goal. For example, you can create a message hub per application to organize the endpoints and policies that each application uses.
Figure 3-29 presents a simplified view of a message hub with its components and cardinalities between components of a specific message hub.
Figure 3-29 Message hub, endpoints, and policies
3.6.3 Connection policies
A connection policy is used to authorize a client to connect to an endpoint. The connection policy can restrict which clients can connect to the endpoint. You must apply at least one connection policy to an endpoint so that a client can connect to that endpoint. When you create a connection policy, you can use the following filter attributes to restrict who is allowed to connect:
•Client IP address
•Client ID
•User ID
•Group Name
•Protocol
•Certificate common name
A connection policy can be applied to more than one endpoint that is defined in the same message hub. For example, you can use a single connection policy to allow all clients from a particular IP address range to connect. You can then restrict the access of different clients to particular queues and topic strings by using a messaging policy.
3.6.4 Messaging policies
A messaging policy is used to control the topics or queue for which a client can send and receive messages. When you create a messaging policy, you must specify the following components:
• Name
• Destination Type: Topic, Global-shared subscription, or Queue
• Destination: Value of the topic
• Max Messages (only valid for topics)
• Authority: Publish, Subscribe, Send, Browse, Receive, or Control
You must specify at least one of the following filters:
• Client IP address
• Client ID
• User ID
• Group Name
• Certificate Common Name
• Protocol: JMS or MQTT
|
Note: When specifying the Destination, you can use an asterisk (*) to specify all topic strings or queues. You can also use variable substitution in the topic string or queue to ensure that only specific user IDs, group IDs, client IDs, or client certificate common names can access a topic. The variable for the user ID is ${UserID}.
The substitution variables are listed:
•${UserID} for the user ID
•${GroupID} for the group ID
•${ClientID} for the client ID
•${CommonName} for the client certificate common name
For example, if a topic string in a messaging policy is Pickmeup/drivers/${ClientID}, a client with an ID of driver_a can access the topic Pickmeup/drivers/driver_a. A client with an ID of driver_b cannot access the topic Pickmeup/drivers/driver_a, but that client can access Pickmeup/drivers/driver_b.
|
3.6.5 Endpoints
An endpoint enables a client to connect to the MessageSight appliance. As shown in Figure 5-2 on page 105, each endpoint must have at least one connection policy, and at least one messaging policy.
When you create an endpoint, you can specify the following attributes:
• Name
• Enabled: True or False
• IP address
• Port
• Protocol: JMS or MQTT
• Maximum message size
• Security profile
• Connection policies
• Messaging policies
3.6.6 The DemoHub message hub
Every virtual or physical MessageSight appliance automatically integrates a DemoHub message hub. This message hub includes an endpoint (DemoMqttEndpoint) that listens on Port 1883, without any security constraints.
The purpose of this message hub is to let developers rapidly integrate an application after MessageSight is installed. The MessageSight Messaging Tester also uses this message hub to test a network interface. See “3.4, “Overview of the MessageSight web UI” on page 55.
The DemoHub message hub has the following characteristics:
1. Connect to your MessageSight appliance using the web UI.
2. From the top-level menu, select Messaging → Message Hubs to access the Message Hubs configuration page, as shown in Figure 3-30.
Figure 3-30 Accessing the Message Hubs configuration page
3. In the list of configured message hubs, you can see the DemoHub message hub, as shown in Figure 3-31 on page 77.
Figure 3-31 DemoHub message hub
Figure 3-32 Edit DemoHub
Figure 3-33 The DemoHub Endpoints tab
6. Select DemoMqttEndpoint and click the pencil (edit) icon to access its configuration, as shown in Figure 3-34 on page 78.
Figure 3-34 Edit the DemoMqttEndpoint endpoint
A new window opens, showing the configuration properties of the DemoMqttEndpoint endpoint, as shown in Figure 3-35.
Figure 3-35 Properties of the DemoMqttEndpoint endpoint
Notice the listening port of the endpoint (1883) and the connection and messaging policies. This endpoint does not provide any security control and it is configured to support the MQTT protocol only.
7. Click Close to close the opening window.
Figure 3-36 Select the Messaging Policies tab
9. Select the DemoMessagingPolicy messaging policy and click the pencil (edit) icon.
10. A window opens, showing the configuration parameters of the DemoMessagingPolicy messaging policy, as shown in Figure 3-37.
Figure 3-37 Properties of the DemoMessagingPolicy messaging policy
Notice the Destination (*) and the Authority (Publish and Subscribe) properties, which indicate that publication and subscription can be done on any topic. JMS and MQTT protocols have been selected, as well. Therefore, the defined messaging policy allows access when the protocol is JMS or MQTT.
A sentence at the bottom of the window summarizes what the messaging policy allows in term of messaging, as shown in Figure 3-37 on page 79.
3.6.7 Configuring your first message hub using the MessageSight web UI
The creation of a message hub using the web UI is described in 5.2.1, “MessageSight basic configuration” on page 107.
3.6.8 Configuring a message hub using the MessageSight CLI
The process to configure a message hub using the MessageSight CLI is described.
List of commands to configure a message hub
This section describes the CLI commands for use in configuring message hubs, including their components (endpoints, connection policies, and messaging policies).
To configure a message hub and its components using the CLI, it is important to adhere to the following order at creation time:
1. Message hubs
2. Connection policies
3. Messaging policies
4. Endpoints
The commands used to configure a message hub using the CLI are shown in Example 3-12.
Example 3-12 CLI commands used to configure a Message Hub
imaserver create
imaserver delete
imaserver list
imaserver show
imaserver update
|
Note: For details about the commands specific to message hubs, see Message hub commands in the MessageSight IBM Knowledge Center:
|
Create a basic message hub using the CLI
In this section, we describe the creation of a basic message hub using the CLI commands.
The properties of the message hub that we create in this section are the same as those of the DemoHub message hub, which was presented in 3.6.6, “The DemoHub message hub” on page 76, with a few differences. The differences are the names of the hub components:
•The name of the message hub we create using the CLI is PickmeupHub.
•The name of the endpoint of the PickMeUpHub is PickmeupEndpoint.
•The name of the connection policy associated with the PickMeUpEndpoint is PickmeupConnPolicy.
•The name of the messaging policy associated with the PickMeUpEndpoint is PickmeupMsgPolicy.
The sequence of CLI commands for creating the PickMeUp message hub and its components are shown in Example 3-13.
Example 3-13 CLI commands to create the PickMeUp message hub and its components
Console>
Console>imaserver create MessageHub "Name=PickmeupHub" "Description=message hub for the PickmeUp application"
The requested configuration change has completed successfully.
Console>
Console>imaserver create ConnectionPolicy "Name=PickmeupConnPolicy" "Description=connection policy for the PickmeUp app" "Protocol=MQTT"
The requested configuration change has completed successfully.
Console>
Console>imaserver create MessagingPolicy "Name=PickmeupMsgPolicy" "Description=messaging policy of the PickmeUp app" "DestinationType=Topic" "Destination=*" "MaxMessages=5000" "ActionList=Publish,Subscribe" "DisconnectedClientNotification=False" "Protocol=MQTT"
The requested configuration change has completed successfully.
Console>
Console>imaserver create Endpoint "Name=PickmeupEndpoint" "Description=endpoint of Pickmeup message hub" "Port=16000" "Interface=all" "Protocol=MQTT" "ConnectionPolicies=PickmeupConnPolicy" "MessagingPolicies=PickmeupMsgPolicy" "MessageHub=PickmeupHub" "Enabled=True"
The requested configuration change has completed successfully.
Console>
Console>
Console> imaserver list MessageHub
DemoHub
PickmeupHub
Console>
The last command in Example 3-13 is imaserver list MessageHub, which is used to display the list of message hubs that are configured on a MessageSight appliance. As you can see, PickmeupHub is part of the list.
Connect the MessageSight web UI to confirm that the PickMeUp message hub has been created, as shown in Figure 3-38.
Figure 3-38 List of message hubs
|
Note: To delete a message hub and its components, use the imaserver delete command.
Delete message hubs, and the message hub components, in the following order:
1. Endpoints
2. Messaging policies
3. Connection policies
4. Message hubs
|
Retrieve configuration information
The imaserver show command is used to retrieve the configuration properties of a message hub, a messaging policy, a connection policy, or an endpoint.
In Example 3-14, the imaserver show command displays the configuration information of the PickmeupEndpoint endpoint.
Example 3-14 CLI command to show endpoint information
Console>
Console> imaserver show Endpoint "Name=PickmeupEndpoint"
Name = PickmeupEndpoint
Enabled = True
Port = 16000
Protocol = MQTT
Interface = all
SecurityProfile =
ConnectionPolicies = PickmeupConnPolicy
MessagingPolicies = PickmeupMsgPolicy
MaxMessageSize = 1024KB
MessageHub = PickmeupHub
Description = endpoint of Pickmeup message hub
Console>
3.6.9 Use the MessageSight SSH to deploy message hub configuration
In this section, we present a solution to deploy the configuration of a message hub on a MessageSight appliance using the MessageSight SSH service.
The bash script is shown in Example 3-15. The idea is to make the creation of message hubs easier using a deployment script. This deployment script can be created, based on an XML or JavaScript Object Notation (JSON) parameter file that can be implemented by a messaging administrator.
Example 3-15 Bash script example for deploying a MessageHub configuration
#!/usr/bin/bash
#
# This script automates an SSH session with a MessageSight appliance.
# In this session, it creates a MessageHub including a Connection policy + a Messaging policy + an Endpoint.
#
ARGS=2
if [ $# -ne "$ARGS" ]; then
echo "Usage: ima-createHub.sh USER IMA_HOSTNAME"
exit 1
fi
ima_user=$1
ima_hostname=$2
commands_file="ima_commands.txt"
commands_execution_output="ima_commands_execution_output.txt"
# remove old files to make sure we create new files, instead
# of appending to old ones
rm -f $commands_file
rm -f $commands_execution_output
#echo ima_hostname=$ima_hostname
# create list of commands, in a file. These commands
# will be sent to the MessageSight ssh service
echo imaserver create MessageHub "Name=MyMessageHub" "Description=message hub created using CLI commands" >> $commands_file
echo imaserver create ConnectionPolicy "Name=MyConnPolicy" "Description=connection policy of MyMessageHub" "Protocol=MQTT" >> $commands_file
echo imaserver create MessagingPolicy "Name=MyMsgPolicy" "Description=messaging policy of MyMessageHub" "DestinationType=Topic" "Destination=myorg/sample" "MaxMessages=5000" "ActionList=Publish,Subscribe" "DisconnectedClientNotification=False" "Protocol=MQTT" >> $commands_file
echo imaserver create Endpoint "Name=MyEndpoint" "Description=endpoint of MyMessageHub" "Port=16003" "Interface=all" "Protocol=MQTT" "ConnectionPolicies=MyConnPolicy" "MessagingPolicies=MyMsgPolicy" "MessageHub=MyMessageHub" "Enabled=True" >> $commands_file
#echo imaserver list MessageHub >> $commands_file
echo exit >> $commands_file
chmod 400 $commands_file
# redirect the output of the ssh session to a file, so we
# can grep it and see how many commands were successfully executed by MessageSight
ssh -l $ima_user $ima_hostname < $commands_file 2> $commands_execution_output
any_failure=`grep -E 'required|not valid|Invalid|invalid' $commands_execution_output`
# remove the commands file after using it
#rm -f $commands_file
echo "*** MessageSight Configuration Status ***"
if [ "$any_failure" ] ; then
echo "Failure occurred creating MessageSight configuration"
exit 1
else
echo "MessageSight configuration created successfully"
exit 0
fi
The complete deployment process is shown in Figure 3-39 on page 84.
Figure 3-39 Using the MessageSight SSH service to deploy a message hub configuration
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.