Bug 1061908

This is a follow-up from the following bug: 
https://bugzilla.redhat.com/show_bug.cgi?id=890568

This bug was created to address customer security requirements. During testing, it was found that there was no documentation created for the packages and that the version information for the Welcome page comes from the JSP file.

Work-around/fix for this ...

I changed the lines in the JSP to the following:

    <div class="obrand_main">
        <div class="obrand_welcome"><fmt:message key="obrand.welcome.welcome.text" /></div>
        <div class="obrand_welcome">
             <script type="text/JavaScript">
            <!--
            document.write('Custom Version: 1.0')
            //-->
            </script>

I am unsure I understand the problem.

Can you please repeat the description?

Currently the string of the product is taken from branding while the version is taken from product configuration.

I get:
---
Welcome to Red Hat Enterprise Virtualization Manager.
Version 3.5.0-0.0.16.20140203gitf629db1.root.master.el6ev 
---

Which looks good.

Alon -

That does look good for default installation. However, the rebranding package is supposed to allow total rebranding (obscure product information, etc.). In using the banding package with message.properties, the templates, and CSS files, you can customize everything. The "Welcome to Red Hat Enterprise Virtualization Manager." can be replaced with your own text everywhere, and version information can be changed with the About links on both UserPortal and Admin Portal. However, the welcome landing page comes from the JSP file and by default will give you the 

Version 3.5.0-0.0.16.20140203gitf629db1.root.master.el6ev, as you've placed in the ticket above. The goal is to obscure and change this on the Welcome landing page. The code in the 

/usr/share/ovirt-engine/engine.ear/root.war/WEB-INF/ovirt-engine.jsp

uses the branding and items from the templates package and can replace the 
"Welcome to Red Hat Enterprise Virtualization Manager." with whatever is placed in the Branding directory. However, it would appear the following line:

document.write('<fmt:message key="obrand.welcome.version"><fmt:param value="${requestScope[\'version\']}" /> </fmt:message>')

Takes the actual version information of packages and ignores the branding.


Additionally, there is no documentation for the proper use of the branding package that should have been created as part of the bug/RFE to release a rebranding package for RHEVM.

I disagree.

Product version is not something that should be branded, it is the product version we provide, and is required for proper support.

Documentation for the branding package is available[1].

[1] http://gerrit.ovirt.org/gitweb?p=ovirt-engine.git;a=blob;f=README.branding;hb=HEAD

Alon -

That information is what we used to configure the re-branding. I placed support tickets and the RFE for rebranding for our customer. We have multiple security requirements that state we cannot display product information to end-users, this includes the Welcome page version information. 

We were very specific with our RFE as to our requirements and what was expected by security. The branding package does allow the items to be changed from the User Portal and Admin Portal as expected. When clicking on the About, it shows the rebranded information and replacing the {0} with our custom version information works just fine there. We maintain internal cross reference to our version against the official Red Hat version/package version.

Travis you got everything right except for one minor detail which achieves what you want to do.

The branding is layered, so in essence the RHEV branding sits on top of the oVirt branding. Now if you have a specific use case where you need to hide the version you can do the following.

Create a new branding package that will sit on top of RHEV. To have a new package sit on top of RHEV just make sure the directory containing your branding package has a higher number than the RHEV branding. I believe the RHEV branding directory name is 50-rhev.brand, so if yours is called 51-mybrand.brand yours will be applied on top of RHEV.

Now your brand doesn't need to be a complete override of everything, you can just override the parts you want to change, in this case lets assume we want to not show the version numbers.

If you look in the messages.properties you will notice there are 2 keys associated with version (the welcome page version is in the oVirt branding):

obrand.common.version_about=Red Hat Enterprise Virtualization Manager Version: {0}
obrand.welcome.version=Version {0}

Both of which have a {0} which is a place holder for the version. So if you don't want to show the actual version, simply remove the {0} in your branding package. So all you have to do is create your messages.properties with lets say the following lines:

obrand.common.version_about=Red Hat Enterprise Virtualization Manager
obrand.welcome.version=

The code is smart enough to simply not add the version if the place holder is not there. As you might have gathered the RHEV branding package is not a complete override of the oVirt branding, just like yours doesn't need to be a complete override of RHEV to achieve what you need.

So in short we already support what you need, and I saw a patch from Alon that attempts to explain this in the README.developer already.

I forgot to mention, you should do that for all the languages as well, otherwise the translations might have the {0} place holder and still display the version.

Does this do what you need or did I miss anything?

Alexander -

Thanks for the information. 

Where I had issues was with the documentation - what I could find as well as the examples.

obrand.welcome.version=Version {0}

Was missing from the message.properties files I had seen. Therefore, when I created my custom branding for the customer, there as no "overlay" of the branding version. I was able to figure everything else out with the documentation from oVirt as well as the items in all the other files and noted the {0} was used as variable for the version information. 

I replaced the {0} in all the places, but couldn't get rid of it on the welcome page. I added the following to my message.properties

obrand.welcome.version=Version My_Customer_Version_#

Switched the JSP file in the /usr/share/ovirt-engine/engine.ear ...

back to normal, restarted ovirt-engine service.

Everything appears to work.

Could you please provide the information on where/how to get the new documentation created by Alon?

-- Travis

Travis,

The documentation is available in README.branding (Alon's patch cleaned it up a little bit) in the oVirt source code. You can find a list of all available keys in:

packaging/branding/ovirt.brand/messages.properties: localiz-able messages (regular strings can be translated)
packaging/branding/ovirt.brand/external_resources.properties: unlocaliz-able messages (urls and the like)
packaging/branding/ovirt.brand/resources.properties: resources of which only one can exist, for instance the favicon.ico.

Only the oVirt source code properties files have an up-to-date list of keys (we expect keys to be added on a regular basis). If the README.branding doesn't explain everything clearly maybe we will need a KB article to explain it better. Unfortunately I am developer not a documentation writer, so things that seem obvious to me might not be obvious to other people.

Alexander -

That will work for me now. Thanks for clearing things up for me. The README.branding is a good starting point. I think a KB article is the way to go as well. I'm an on-site consultant for a large RHEV implementation and would be happy to assist with this effort, but the issue is finding people with all the correct information. I've had a support ticket opened for a couple weeks and didn't get any traction until I opened a BZ ticket. Most of my issues are ok and I can get this working for the customer and satisfy security, however, once our customer takes the system over, they will want official Red Hat documentation.


-- Traivs

Travis,

Since I am the author and maintainer of the RHEV branding package, I will have all the latest up to date information. Alon is a good resource as well. I am more than willing to help with the article as well, but like I said I am not a great documentation writer, but I do have all the information.

Alexander

Hi,

I am unsure that duplication of documentation will have positive impact.

The branding packaging should work by example, the ovirt theme is a full theme that can be reference as the resource. The rhevm-branding-rhev package is a good reference for how to write standalone package which delivers the content.

Improvements to the README.branding which are not carbon copy of the actual sources in the theme are welcomed.

But please avoid duplication at any cost, sooner or later it will be out of sync and create more noise than good.

Alon -

While I agree with you in principle, I disagree in practice. Our customer does not want to use upstream documentation or packages in their environment. Sending them to non-official documentation from an upstream project like oVirt would not be an accepted practice in their eyes. We have been able to make use of Red Hat KB solutions/articles from the Red Hat site, but long term, it would be the desire to have this become part of the official RHEV documentation either in the (Technical Reference Guide, Administration Guide, Developer Guide). I'm not sure where that would make the most sense, but I do know they are picky about documentation and packages. As a Red Hat employee and consultant resource to the government, I can see the desire by the government users to get documentation only from official channels, but I also know with RHEV being so fast moving, it isn't always practical.


-- Travis

Travis/Alon - any reason for this BZ to remain open?
AFAIU, the requested feature is already available, hence I would like to close this BZ.

Thanks you.

(In reply to Einav Cohen from comment #15)
> Travis/Alon - any reason for this BZ to remain open?
> AFAIU, the requested feature is already available, hence I would like to
> close this BZ.
> 
> Thanks you.

If the reason for branding is to hide artifacts like version, we should explicit support that. Using string tables is not a solution as any translation added will expose this information. We also have several commands that returns that data.

I do not believe this is the role of branding, it was not design to do that, this is why I added pm-ack, if there is an ack, we should consider where to support fake version, within product or at branding.

so the idea is not to "Support fake version within branding interface" (as the BZ title currently states) - it is to "properly hide version / support fake version in general", correct? so if engine is configured with "HideRealVersion=true" or similar, any api call to get the version will actually fail or return a default fake version or something like that?

(In reply to Einav Cohen from comment #17)
> so the idea is not to "Support fake version within branding interface" (as
> the BZ title currently states) - it is to "properly hide version / support
> fake version in general", correct? so if engine is configured with
> "HideRealVersion=true" or similar, any api call to get the version will
> actually fail or return a default fake version or something like that?

Correct, the assignment to branding component is a kind suggestion as I understand. The real question is if we would like to support a feature of fake version.

(In reply to Alon Bar-Lev from comment #18)
> (In reply to Einav Cohen from comment #17)
> > so the idea is not to "Support fake version within branding interface" (as
> > the BZ title currently states) - it is to "properly hide version / support
> > fake version in general", correct? so if engine is configured with
> > "HideRealVersion=true" or similar, any api call to get the version will
> > actually fail or return a default fake version or something like that?
> 
> Correct, the assignment to branding component is a kind suggestion as I
> understand. The real question is if we would like to support a feature of
> fake version.

as you mentioned in comment #16: If it is problematic to expose the version in general, it should be hidden properly, including from the rest-api, etc. 
so the branding is definitely not the place to do that. 

if the user simply wants to alter the text that is being displayed in the welcome page and/or in the "about" dialogs (i.e. there isn't a general problem exposing the version, the user may simply choose to not include it in the welcome-page/"about" dialog text) - he should do that via the branding mechanism, including relevant updates to the different locales' .properties files, etc., - this is what a user should do upon any branded-text change, whether that text change include removing the "{0}" placeholder or not. 

[IMO, there is nothing 'in between' the two approaches above that should be supported via the branding mechanism]

if it is the former, it is an 'infra' RFE and 'Whiteboard' should be changed accordingly. 

if it is the latter, it is already supported and this BZ should be closed. 

needinfo'ing Arthur (ux/infra PM) for a final decision.

Einav/Alon -

I'm fine to have this bug closed. I opened this bug based on lack of documentation and believing that the version on the welcome page wasn't supported by the rebranding package. I have verified based on Alexander's feedback that you can in fact change the versioning from the package by adding the required fields in message.properties.

Based on changing that information there is no bug in the fact that the re-branding doesn't work as designed. We will be submitting a different bugzilla attached to the case for documentation on the proper use of the branding package and the creation of the KCS article on how to use the package which will hopefully be integrated into the developer or administration documentation. 

As for supporting a "fake" version, I'm not sure it matters. The customer security requirement is to obscure version information to end-users (don't display in branding, landing pages, help, abouts). From my point of view with showing the initial PoC to our security team, they were happy with the re-branding results. As long as this information isn't exposed via the web to the end users of the system, we are meeting the requirements.


-- Travis

Per comment#19 and comment#20, closing as NOTABUG.