Bug 999793 - Installation directions for MRG-M 3
Installation directions for MRG-M 3
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise MRG
Classification: Red Hat
Component: Messaging_Installation_and_Configuration_Guide (Show other bugs)
Development
Unspecified Unspecified
unspecified Severity unspecified
: 3.0
: ---
Assigned To: Jared MORGAN
Frantisek Reznicek
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-08-22 03:03 EDT by Joshua Wulf
Modified: 2015-08-09 21:23 EDT (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2015-01-22 10:28:14 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Joshua Wulf 2013-08-22 03:03:22 EDT
Update RHN Channel information for new release.
Comment 1 Petr Matousek 2014-08-13 06:35:57 EDT
Also section "1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6" is currently missing content, this needs to be corrected as well.

Expected content example:
yum groupinstall "MRG Messaging" "Messaging Client Support"
yum install qpid-cpp-server-ha

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_MRG/3/html-single/Messaging_Installation_and_Configuration_Guide/index.html#Install_MRG-M_3_Messaging_Server_on_Red_Hat_Enterprise_Linux_6
Comment 3 Petr Matousek 2014-08-18 04:29:13 EDT
Note: it's probably not necessary to list the 'yum install qpid-cpp-server-ha' command here. The installation of the HA components is described later in the "9.1.10. Install HA Cluster Components" chapter.
Comment 6 Petr Matousek 2014-09-04 10:53:17 EDT
I believe that the following description is more appropriate:
(please replace the current content with the following content, feel free to rephrase the wording)

... subscribe your system to the following channel: 
  Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server)

Install the "MRG Messaging" group using the yum command (as root):

yum groupinstall "MRG Messaging"

If only messaging client support is desired, install the "Messaging Client Support" group using the yum command (as root): 

yum groupinstall "Messaging Client Support"

If High Availability support is desired, subscribe to the following channel:
  Release Channels for Red Hat Enterprise Linux 6 / RHEL Server High Availability

and install the High Availability support using the following yum command (as root):

yum install qpid-cpp-server-ha
Comment 8 Jared MORGAN 2014-09-07 20:14:57 EDT
(In reply to Petr Matousek from comment #6)
> I believe that the following description is more appropriate:
> (please replace the current content with the following content, feel free to
> rephrase the wording)
> 
> ... subscribe your system to the following channel: 
>   Additional Services Channels for Red Hat Enterprise Linux 6 / MRG
> Messaging v.3 (for RHEL-6 Server)
> 
> Install the "MRG Messaging" group using the yum command (as root):
> 
> yum groupinstall "MRG Messaging"
> 
> If only messaging client support is desired, install the "Messaging Client
> Support" group using the yum command (as root): 
> 
> yum groupinstall "Messaging Client Support"
> 
> If High Availability support is desired, subscribe to the following channel:
>   Release Channels for Red Hat Enterprise Linux 6 / RHEL Server High
> Availability
> 
> and install the High Availability support using the following yum command
> (as root):
> 
> yum install qpid-cpp-server-ha

I've restructured the procedure according to your guidance, Petr. You'll note that I've marked the last two steps Optional, because they are up to the customer to determine whether they are required. 

Step 2 remains Required.

http://docbuilder.usersys.redhat.com/18173/#Install_MRG-M_3_Messaging_Server_on_Red_Hat_Enterprise_Linux_6

Hmm, I've also noted that 1.1.4 is also affected, as well as 1.1.3. I've made the appropriate changes to that topic as well using the same Optional and Required notations.

http://docbuilder.usersys.redhat.com/18173/#Upgrade_an_MRG_2_Server_to_MRG_3
Comment 9 Petr Matousek 2014-09-08 08:23:45 EDT
Thanks for the update, unfortunately it is still not 100% accurate, the logic shall reflect the following rules:

1.) You can install _EITHER_ the full messaging support "MRG Messaging"
_OR_ you can install just the "Messaging client support" (it's more an alternative than an optional step).

2.) If you've already installed "MRG Messaging", there is no need to install "Messaging Client Support" (it's a subset of "MRG Messaging").

3.) Installing HA support makes only sense on the full installation (MRG Messaging).

---

So the content may look like following (or similarly):

If you are using RHN classic management for your system, in addition to the base channel for Red Hat Enterprise Linux 6, subscribe your system to the following channel:
        Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server) 

Install the MRG Messaging group using the following yum command (as root):

    yum groupinstall "MRG Messaging"

    Optional: If High Availability support is required, subscribe to the Release Channels for Red Hat Enterprise Linux 6 / RHEL Server High Availability channel 

    and install using the following yum command (as root):

    yum install qpid-cpp-server-ha

Alternative: If only messaging client support is required, install the "Messaging Client Support" group using the following yum command (as root):

    yum groupinstall "Messaging Client Support"

--

Note: 1.1.4. (Update) shall be also updated accordingly.

-> ASSIGNED
Comment 10 Jared MORGAN 2014-09-08 23:20:52 EDT
(In reply to Petr Matousek from comment #9)
> Thanks for the update, unfortunately it is still not 100% accurate, the
> logic shall reflect the following rules:
> 
> 1.) You can install _EITHER_ the full messaging support "MRG Messaging"
> _OR_ you can install just the "Messaging client support" (it's more an
> alternative than an optional step).
> 
> 2.) If you've already installed "MRG Messaging", there is no need to install
> "Messaging Client Support" (it's a subset of "MRG Messaging").
> 
> 3.) Installing HA support makes only sense on the full installation (MRG
> Messaging).
> 
> ---
> 
> So the content may look like following (or similarly):
> 
> If you are using RHN classic management for your system, in addition to the
> base channel for Red Hat Enterprise Linux 6, subscribe your system to the
> following channel:
>         Additional Services Channels for Red Hat Enterprise Linux 6 / MRG
> Messaging v.3 (for RHEL-6 Server) 
> 
> Install the MRG Messaging group using the following yum command (as root):
> 
>     yum groupinstall "MRG Messaging"
> 
>     Optional: If High Availability support is required, subscribe to the
> Release Channels for Red Hat Enterprise Linux 6 / RHEL Server High
> Availability channel 
> 
>     and install using the following yum command (as root):
> 
>     yum install qpid-cpp-server-ha
> 
> Alternative: If only messaging client support is required, install the
> "Messaging Client Support" group using the following yum command (as root):
> 
>     yum groupinstall "Messaging Client Support"
> 
> --
> 
> Note: 1.1.4. (Update) shall be also updated accordingly.
> 
> -> ASSIGNED

Thanks for the technical feedback, Petr.

After some consideration I"ve decided to change the structure of this procedure to make it flow better. 

Change summary:

http://docbuilder.usersys.redhat.com/18173/#Install_MRG-M_3_Messaging_Server_on_Red_Hat_Enterprise_Linux_6 

* I promoted installing the RHEL base channel as a discrete step. It was getting lost in the first step originally. 

* I specified up-front the channel names so customers would know exactly what channels they should subscribe to depending on their requirements.

* I made step 3 specific to what it actually does (install the server and client - terminology may need correcting here...), and broke the two commands down into a variable list which allows some sub-classification in the step.

* I adopted your suggestion about using the "Alternative" heading. I added that this is required if you only want client only, and that the "MRG Messaging" group install option install the client by default.

http://docbuilder.usersys.redhat.com/18173/#Upgrade_an_MRG_2_Server_to_MRG_3

Same changes as above (copied the procedure verbatim) and added the distinction of "MRG Messaging 3 Software Channels" in Step 4, as a visual reminder that customers are upgrading from 2 to 3 in this procedure.
Comment 11 Petr Matousek 2014-09-09 11:35:40 EDT
Well, good work, but there are still few issues:

1.) The "Messaging client support" comes from the RHEL base channel, so the information is misleading

1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6

- Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG Messaging Platform, or Messaging Client Support only installations. 

+ Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG Messaging Platform.

2.) You probably did copy&paste failure:

1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6

For High Availability, following channel shall be used (not "MRG Messaging v.3"): "Red Hat Enterprise Linux 6 / RHEL Server High Availability"

- Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable High Availability installations. 

+ Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / RHEL Server High Availability channel to enable High Availability installations. 

3.) From the new ordering it is not clear that point 3.) may be skipped when only client support is desired, so I would propose the following change (feel free to rephrase the wording):

1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6

- 3. Install the MRG Messaging server and client using the following commands:
+ 3. Install the MRG Messaging server and client using the following commands (if only Messaging client support is required go directly to the step 4.)

4.) 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3

Consider moving the "If you are using RHN classic management for your system" from point 3. to point 1. (because point 2. is also related to RHN classic, so maybe it's better to start with this sentence), but this is just a detail.

5.) NOTE: All the issues 1-3 applies to 1.1.4 upgrade section as well.

-> ASSIGNED
Comment 12 Jared MORGAN 2014-09-09 18:24:46 EDT
(In reply to Petr Matousek from comment #11)
> Well, good work, but there are still few issues:
> 
> 1.) The "Messaging client support" comes from the RHEL base channel, so the
> information is misleading
> 
> 1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6
> 
> - Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG
> Messaging Platform, or Messaging Client Support only installations. 
> 
> + Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG
> Messaging Platform.

Thanks for clarifying this. I was going to make the distinction about MRG Client Only support in the first step, but I think I've round-tripped this ticket enough now. ;)

> 
> 2.) You probably did copy&paste failure:
> 
> 1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6
> 
> For High Availability, following channel shall be used (not "MRG Messaging
> v.3"): "Red Hat Enterprise Linux 6 / RHEL Server High Availability"
> 
> - Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable High
> Availability installations. 
> 
> + Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / RHEL Server High Availability channel to enable High Availability
> installations. 

Yep, a classic case of copy pasta fail. Sorry about that, and thanks for the correction.
 
> 3.) From the new ordering it is not clear that point 3.) may be skipped when
> only client support is desired, so I would propose the following change
> (feel free to rephrase the wording):
> 
> 1.1.3. Install MRG-M 3 Messaging Server on Red Hat Enterprise Linux 6
> 
> - 3. Install the MRG Messaging server and client using the following
> commands:
> + 3. Install the MRG Messaging server and client using the following
> commands (if only Messaging client support is required go directly to the
> step 4.)

I've added the guidance as a note directly under the lead-in sentence.

> 4.) 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> 
> Consider moving the "If you are using RHN classic management for your
> system" from point 3. to point 1. (because point 2. is also related to RHN
> classic, so maybe it's better to start with this sentence), but this is just
> a detail.
> 
> 5.) NOTE: All the issues 1-3 applies to 1.1.4 upgrade section as well.
> 
> -> ASSIGNED

Yep, I agree this fits better at the top (after a day's separation from writing this and reviewing). 

I should have sat on all this work until today and then did a final sanity check before submitting for review.
Comment 13 Petr Matousek 2014-09-10 05:16:57 EDT
Unfortunately you did a c&p failure again in the last update. Otherwise the content looks correct now.

1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3

- If only Messaging Client support is required go directly to Step 4. 
+ If only Messaging Client support is required go directly to Step 6. 

-> ASSIGNED
Comment 14 Petr Matousek 2014-09-10 09:15:11 EDT
(In reply to Petr Matousek from comment #13)
> Unfortunately you did a c&p failure again in the last update. Otherwise the
> content looks correct now.
> 
> 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> 
> - If only Messaging Client support is required go directly to Step 4. 
> + If only Messaging Client support is required go directly to Step 6. 
> 
> -> ASSIGNED

There is one more improvement for consideration, in the upgrade chapter (1.1.4) the text shall use "update" wording instead of "install" (only the text, not the commands), otherwise the upgrade text is exactly the same as the install text (except step 2. and 3.) and is probably redundant (the update chapter may point to follow the installation instructions after the packages are removed and channels unsubscibred). Leaving possible changes on your decision.."
Comment 15 Jared MORGAN 2014-09-16 01:12:00 EDT
(In reply to Petr Matousek from comment #13)
> Unfortunately you did a c&p failure again in the last update. Otherwise the
> content looks correct now.
> 
> 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> 
> - If only Messaging Client support is required go directly to Step 4. 
> + If only Messaging Client support is required go directly to Step 6. 
> 
> -> ASSIGNED

Fixed.

(In reply to Petr Matousek from comment #14)
> (In reply to Petr Matousek from comment #13)
> > Unfortunately you did a c&p failure again in the last update. Otherwise the
> > content looks correct now.
> > 
> > 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> > 
> > - If only Messaging Client support is required go directly to Step 4. 
> > + If only Messaging Client support is required go directly to Step 6. 
> > 
> > -> ASSIGNED
> 
> There is one more improvement for consideration, in the upgrade chapter
> (1.1.4) the text shall use "update" wording instead of "install" (only the
> text, not the commands), otherwise the upgrade text is exactly the same as
> the install text (except step 2. and 3.) and is probably redundant (the
> update chapter may point to follow the installation instructions after the
> packages are removed and channels unsubscibred). Leaving possible changes on
> your decision.."

I've taken your suggestion and changed "install" to "update". 

I have left the full procedure in. There is repeated info, but when a customer lands on this topic directly after a google search, they won't need to visit another section to get the rest of the procedure.
Comment 16 Jared MORGAN 2014-09-16 01:12:19 EDT
(In reply to Petr Matousek from comment #13)
> Unfortunately you did a c&p failure again in the last update. Otherwise the
> content looks correct now.
> 
> 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> 
> - If only Messaging Client support is required go directly to Step 4. 
> + If only Messaging Client support is required go directly to Step 6. 
> 
> -> ASSIGNED

Fixed.

(In reply to Petr Matousek from comment #14)
> (In reply to Petr Matousek from comment #13)
> > Unfortunately you did a c&p failure again in the last update. Otherwise the
> > content looks correct now.
> > 
> > 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> > 
> > - If only Messaging Client support is required go directly to Step 4. 
> > + If only Messaging Client support is required go directly to Step 6. 
> > 
> > -> ASSIGNED
> 
> There is one more improvement for consideration, in the upgrade chapter
> (1.1.4) the text shall use "update" wording instead of "install" (only the
> text, not the commands), otherwise the upgrade text is exactly the same as
> the install text (except step 2. and 3.) and is probably redundant (the
> update chapter may point to follow the installation instructions after the
> packages are removed and channels unsubscibred). Leaving possible changes on
> your decision.."

I've taken your suggestion and changed "install" to "update". 

I have left the full procedure in. There is repeated info, but when a customer lands on this topic directly after a google search, they won't need to visit another section to get the rest of the procedure.
Comment 17 Frantisek Reznicek 2014-09-17 03:48:55 EDT
Dear Jared, see my comments inlined.

(In reply to Jared MORGAN from comment #16)
> (In reply to Petr Matousek from comment #13)
> > Unfortunately you did a c&p failure again in the last update. Otherwise the
> > content looks correct now.
> > 
> > 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> > 
> > - If only Messaging Client support is required go directly to Step 4. 
> > + If only Messaging Client support is required go directly to Step 6. 
> > 
> > -> ASSIGNED
> 
> Fixed.

Ack. Thank you for fix.

> 
> (In reply to Petr Matousek from comment #14)
> > (In reply to Petr Matousek from comment #13)
> > > Unfortunately you did a c&p failure again in the last update. Otherwise the
> > > content looks correct now.
> > > 
> > > 1.1.4. Upgrade a MRG Messaging 2 Server to MRG Messaging 3
> > > 
> > > - If only Messaging Client support is required go directly to Step 4. 
> > > + If only Messaging Client support is required go directly to Step 6. 
> > > 
> > > -> ASSIGNED
> > 
> > There is one more improvement for consideration, in the upgrade chapter
> > (1.1.4) the text shall use "update" wording instead of "install" (only the
> > text, not the commands), otherwise the upgrade text is exactly the same as
> > the install text (except step 2. and 3.) and is probably redundant (the
> > update chapter may point to follow the installation instructions after the
> > packages are removed and channels unsubscibred). Leaving possible changes on
> > your decision.."
> 
> I've taken your suggestion and changed "install" to "update". 

Unfortunatelly, there is still one install pending in Update section. I'd like to get this fixed as we started to migrate the wording (not commands):

--- /tmp/orig.txt       2014-09-17 09:45:34.000000000 +0200
+++ /tmp/new.txt        2014-09-17 09:45:43.000000000 +0200
@@ -10,11 +10,11 @@
  Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG Messaging Platform installations.
  High Availability Channel
  Subscribe to the Additional Services Channels for Red Hat Enterprise Linux 6 / RHEL Server High Availability channel to enable High Availability installations.
- Install the MRG Messaging server and client using the following commands:
+ Update the MRG Messaging server and client using the following commands:
 Note
  If only Messaging Client support is required go directly to Step Six.
  MRG Messaging Server and Client
- Install the "MRG Messaging" group using the following yum command (as root):
+ Update the "MRG Messaging" group using the following yum command (as root):
 yum groupinstall "MRG Messaging"

  High Availability Support


> 
> I have left the full procedure in. There is repeated info, but when a
> customer lands on this topic directly after a google search, they won't need
> to visit another section to get the rest of the procedure.

No problem, this is ok.



Optionally (and typographic-wise) I do not see reason to have step 6 bold:
  Alternative: update Messaging Client Support Only

If there is reason, keep it, if not use same format as other steps.

-> ASSIGNED
Comment 18 Jared MORGAN 2014-09-22 02:06:36 EDT
(In reply to Frantisek Reznicek from comment #17)

> Unfortunatelly, there is still one install pending in Update section. I'd
> like to get this fixed as we started to migrate the wording (not commands):
> 
> --- /tmp/orig.txt       2014-09-17 09:45:34.000000000 +0200
> +++ /tmp/new.txt        2014-09-17 09:45:43.000000000 +0200
> @@ -10,11 +10,11 @@
>   Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / MRG Messaging v.3 (for RHEL-6 Server) channel to enable full MRG
> Messaging Platform installations.
>   High Availability Channel
>   Subscribe to the Additional Services Channels for Red Hat Enterprise Linux
> 6 / RHEL Server High Availability channel to enable High Availability
> installations.
> - Install the MRG Messaging server and client using the following commands:
> + Update the MRG Messaging server and client using the following commands:
>  Note
>   If only Messaging Client support is required go directly to Step Six.
>   MRG Messaging Server and Client
> - Install the "MRG Messaging" group using the following yum command (as
> root):
> + Update the "MRG Messaging" group using the following yum command (as root):
>  yum groupinstall "MRG Messaging"

Sorry for the churn on this. I've replaced the instances of Install to Update.

> Optionally (and typographic-wise) I do not see reason to have step 6 bold:
>   Alternative: update Messaging Client Support Only
> 
> If there is reason, keep it, if not use same format as other steps.
> 
> -> ASSIGNED

The text formats this way because it is a <step> <title>. But I think that because we have put the note in Step 5, we should be able to remove the heading.
Comment 19 Frantisek Reznicek 2014-09-22 03:45:18 EDT
Thank you for the changes, I ack them all.

-> VERIFIED

Note You need to log in before you can comment on or make changes to this bug.