Bug 1269970

*** Bug 1267504 has been marked as a duplicate of this bug. ***

Assigning the bug back to the default queue for it to get re-assigned and prioritized.

oVirt 4.0 Alpha has been released, moving to oVirt 4.0 Beta target.

This update should be made in the 4.1 documentation. If the same update can be easily cherry-picked to the 4.0 documentation, the update can be applied there as well.

Hi Mi

Hi Michal. Could you please take a look at this KB article and let me know how much of this information is still accurate and can be used in the Admin Guide, and what needs to be updated. For example, the interface with Active Directory.

Thanks!

https://access.redhat.com/articles/1979233

Hi Derek
I'd appreciate it if you could take a look at this KB topic and let me know what you think.
https://access.redhat.com/articles/1979233

It contains a lot of information in a workflow format. I'll definitely be checking whether all the rhev-related information is up-to-date in the guide but it also has information about sealing the Windows before creating the pool, as well as testing information. Neither of these things usually appear in the guides.

Thanks a lot
Emma

section Customizations should be updated with the feature allowing to specify custom script in GUI (bug 1080002, bug 1073961)

there's also bug 1439738 which is very unhelpful ATM

(In reply to Michal Skrivanek from comment #8)
> section Customizations should be updated with the feature allowing to
> specify custom script in GUI (bug 1080002, bug 1073961)
> 
> there's also bug 1439738 which is very unhelpful ATM

Hi Michal

A few questions.
1. Is this the correct documentation for the sysprep feature that you're referring to?
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.1/html/virtual_machine_management_guide/sect-using_sysprep_to_automate_the_configuration_of_virtual_machines

2. What about the other sections? Are you the right person to review them all to say what is correct or incorrect? And if not, who else could help? Infra?

3. Do you feel that the article has critical information that is missing from the guides?

Working on this offline with Lucy, Derek and Greg to try and see exactly what is required.

There have been many offline discussions so I would like to add some of the information here:

Miguel Martin:
Hi all,

I am familiar with both 'ovirt-engina-aaa-ldap' and 'Windows VDI Pools' as I had to deal with them in a couple of cases recently.
I'm also familiar with the KCS because I suffered it when trying to figure out how it actually works.

As Greg said, most of the information, if not all, is still good in the KCS but there are some things that need clarification, like:

1. How do I specify the users/passwords to join the AD domains if I have more than one Pool each one joining to its own AD domain? The KCS says that you need to use the legacy 'engine-manage-domains' (unsupported in 4.x) or engine-config to setup the default user/pass. In this case we would have the same user/pass for all the domains.

2. How do I customize my sysprep file for each domain? The KCS only shows how to customize the sysprep file and use it, overwriting the corresponding config in the '99-defaults.properties' file. But this way we can only have a custom sysprep per OS version, not per Pool.

3. How do I specify the windows license activation key for each domain? The same approach as in the previous question works for windows product key, overwriting the productKey variable in '99-defaults.properties' ( for example 'os.windows_2003.productKey.value ='). But, again, we can only specify a different windows product key per OS version.

Regarding question 1. I had some additional confusion because It is possible to specify the user/pass to join a domain in the 'Alternative credentials' section when you 'Run once' a VM based on a windows template, but this is not possible in a Template or Pool level because there is no such section in the 'Initial Run' tab (I think a bug should be filed for this).

It is also confusing because of the 'Admin password' section on 'Initial Run' in a Template or Pool (just below the domain related configurations), corresponds to the local windows administrator, not the domain administrator. To add more confusion the default local administrator is the user named 'user'.


So, I will try to summarize the two ways I found to get it working, the first is when you have only a domain and mainly is a summary of the KCS:

1. Modify default admin/pass to join the domain with engine-config:
                          engine-config -s "SysPrepDefaultPassword=interactive"
                          engine-config -s "SysPrepDefaultUser=example\administrator"
2. Modify the productKey variable in '99-default.properties' for the corresponding windows version
3. Restart the engine.
4. Install a Windows Machine, seal it, and create a template from it, just as described in the KCS.
5. Create a pool based on the previous template

The second would be a more general approach (and simpler) and you can specify the user/pass and the product key (and any other customization) at Pool creation time:

1. Install a Windows Machine, seal it, and create a template from it, just as described in the KCS.
2. Create a pool based on the previous template with sysprep customization.

For this solution, we will specify the user/pass and the product key using a custom sysprep (in pool 'Initial Run' tab), that is, a copy of the default sysprep.
In case of a Windows 7 x64 os, the default sysprep is in file '/usr/share/ovirt-engine/conf/sysprep/sysprep.w7x64'.

So, once we pasted the content of the file in the 'sysprep' textbox (in the pool 'Inital Run' tab) we modify the following info:

......
                <ProductKey>
                    <Key><![CDATA[$ProductKey$]]></Key>  ----------------------> with <Key>xxxx-xxx-xxx-xxx</Key>
                </ProductKey>
.....
                <Credentials>
                    <Domain><![CDATA[$JoinDomain$]]></Domain>
                    <Password><![CDATA[$DomainAdminPassword$]]></Password>  ----------------------> with the domain password<Password>mypassword</Password>
                    <Username><![CDATA[$DomainAdmin$]]></Username> ----------------------> with the domain admin user<Username>DomainAdministrator</Username>
                </Credentials>
......

There is no need to modify rest of the variables in the xml as they can be filled from the 'Initial Run' tab fields (Domain, OU, Organization Name, Custom Locale..)
Well, maybe I would modify the local user admin named 'user',:

......
           <UserData>
            ..........
                <FullName>"user"</FullName> <----------------------------- with <FullName>"mylocaladmin"</FullName>
            ..........
            </UserData>
......
               <LocalAccounts>
                    <LocalAccount wcm:action="add">
                        <Password>
                            <Value><![CDATA[$AdminPassword$]]></Value>
                            <PlainText>true</PlainText>
                        </Password>
                        <DisplayName>user</DisplayName> <----------------------------- with <DisplayName>mylocaladmin</DisplayName>
                        <Group>administrators</Group>
                        <Name>user</Name> <----------------------------- with <Name>mylocaladmin</Name>
                    </LocalAccount>
                </LocalAccounts>
.........


In the end, the procedure is simple and I think it can be documented easily (I would prefer the second approach as it is more general and we don't need to restart the engine when the user/pass or product key are modified).

A discussion with Martin Perina with relation to the script/tool and to bug 1462294 "AD domain configuration is not supported in ovirt-engine-extension-aaa-ldap-setup, provide examples how to configure AD domain":

So once again, tool can configure following AD setups:
1. Whole forrest with multi-domain trust
 2. Whole forrest containing only single domain (aka single domain setup)
 No other configurations are supported within the tool
<mperina> For everything else manual setup is needed

 In .. (4.1.6) what examples will you be providing for manual configuration?
<mperina> The description of example is contained in RPM, after installation it's located in /usr/share/ovirt-engine-extension-aaa-ldap/examples/README.md
.....

i.e. the tool is only meant to be used for two specific scenarios and for all other cases Martin hopes that GSS/customers will be able to use the examples to configure their setups.

I'm adding here the scenarios that appear in the README file:
1. Active Directory with selected single server using StartTLS
2. Active Directory with selected multiple servers using StartTLS
3. Active Directory with selected multiple servers using LDAPS
4. Active Directory with server defined in DNS SRV records using LDAPS
5. Single sign-on with Active Directory

Some additional information from a conversation with Martin P with regards to comments concerning the use of ldap-aaa with AD and kerberos

AD can be used without kerberos or with it.
<mperina> Default simplest way is not using kerberos, that's what aaa-ldap-setup-tool does
<mperina> Previous engine-manage-domains offered only kerberos and only for a single domain (no forrest) and it was written in a really bad way
...
<mperina> If someone wants, to configure kerberos for aaa-ldap, it's of course possible, but it's fully manual operation

<mperina> ... certificates are relevant, if you choose StartTLS or LDAPS connection, but they can also be relevant for kerberos

... bug which covers how to configure aaa-ldap using kerberos to access AD ...
<mperina> Here are relevant bugs:
<mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1322940
<mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1361223

Martin also suggested that they will create an example for this and add it to the next aaa-ldap release

Martin, if you do create such an example please let me know as i think it could be useful to document the examples that are being provided...

(In reply to Emma Heftman from comment #11)
> There have been many offline discussions so I would like to add some of the
> information here:
> 
> Miguel Martin:
> Hi all,
> 
> I am familiar with both 'ovirt-engina-aaa-ldap' and 'Windows VDI Pools' as I
> had to deal with them in a couple of cases recently.
> I'm also familiar with the KCS because I suffered it when trying to figure
> out how it actually works.
> 
> As Greg said, most of the information, if not all, is still good in the KCS
> but there are some things that need clarification, like:
> 
> 1. How do I specify the users/passwords to join the AD domains if I have
> more than one Pool each one joining to its own AD domain? The KCS says that
> you need to use the legacy 'engine-manage-domains' (unsupported in 4.x) or
> engine-config to setup the default user/pass. In this case we would have the
> same user/pass for all the domains.
> 
> 2. How do I customize my sysprep file for each domain? The KCS only shows
> how to customize the sysprep file and use it, overwriting the corresponding
> config in the '99-defaults.properties' file. But this way we can only have a
> custom sysprep per OS version, not per Pool.
> 
> 3. How do I specify the windows license activation key for each domain? The
> same approach as in the previous question works for windows product key,
> overwriting the productKey variable in '99-defaults.properties' ( for
> example 'os.windows_2003.productKey.value ='). But, again, we can only
> specify a different windows product key per OS version.
> 
> Regarding question 1. I had some additional confusion because It is possible
> to specify the user/pass to join a domain in the 'Alternative credentials'
> section when you 'Run once' a VM based on a windows template, but this is
> not possible in a Template or Pool level because there is no such section in
> the 'Initial Run' tab (I think a bug should be filed for this).
> 
> It is also confusing because of the 'Admin password' section on 'Initial
> Run' in a Template or Pool (just below the domain related configurations),
> corresponds to the local windows administrator, not the domain
> administrator. To add more confusion the default local administrator is the
> user named 'user'.
> 
> 
> So, I will try to summarize the two ways I found to get it working, the
> first is when you have only a domain and mainly is a summary of the KCS:
> 
> 1. Modify default admin/pass to join the domain with engine-config:
>                           engine-config -s
> "SysPrepDefaultPassword=interactive"
>                           engine-config -s
> "SysPrepDefaultUser=example\administrator"
> 2. Modify the productKey variable in '99-default.properties' for the
> corresponding windows version
> 3. Restart the engine.
> 4. Install a Windows Machine, seal it, and create a template from it, just
> as described in the KCS.
> 5. Create a pool based on the previous template
> 
> The second would be a more general approach (and simpler) and you can
> specify the user/pass and the product key (and any other customization) at
> Pool creation time:
> 
> 1. Install a Windows Machine, seal it, and create a template from it, just
> as described in the KCS.
> 2. Create a pool based on the previous template with sysprep customization.
> 
> For this solution, we will specify the user/pass and the product key using a
> custom sysprep (in pool 'Initial Run' tab), that is, a copy of the default
> sysprep.
> In case of a Windows 7 x64 os, the default sysprep is in file
> '/usr/share/ovirt-engine/conf/sysprep/sysprep.w7x64'.
> 
> So, once we pasted the content of the file in the 'sysprep' textbox (in the
> pool 'Inital Run' tab) we modify the following info:
> 
> ......
>                 <ProductKey>
>                     <Key><![CDATA[$ProductKey$]]></Key> 
> ----------------------> with <Key>xxxx-xxx-xxx-xxx</Key>
>                 </ProductKey>
> .....
>                 <Credentials>
>                     <Domain><![CDATA[$JoinDomain$]]></Domain>
>                     <Password><![CDATA[$DomainAdminPassword$]]></Password> 
> ----------------------> with the domain
> password<Password>mypassword</Password>
>                     <Username><![CDATA[$DomainAdmin$]]></Username>
> ----------------------> with the domain admin
> user<Username>DomainAdministrator</Username>
>                 </Credentials>
> ......
> 
> There is no need to modify rest of the variables in the xml as they can be
> filled from the 'Initial Run' tab fields (Domain, OU, Organization Name,
> Custom Locale..)
> Well, maybe I would modify the local user admin named 'user',:
> 
> ......
>            <UserData>
>             ..........
>                 <FullName>"user"</FullName> <-----------------------------
> with <FullName>"mylocaladmin"</FullName>
>             ..........
>             </UserData>
> ......
>                <LocalAccounts>
>                     <LocalAccount wcm:action="add">
>                         <Password>
>                             <Value><![CDATA[$AdminPassword$]]></Value>
>                             <PlainText>true</PlainText>
>                         </Password>
>                         <DisplayName>user</DisplayName>
> <----------------------------- with <DisplayName>mylocaladmin</DisplayName>
>                         <Group>administrators</Group>
>                         <Name>user</Name> <-----------------------------
> with <Name>mylocaladmin</Name>
>                     </LocalAccount>
>                 </LocalAccounts>
> .........
> 
> 
> In the end, the procedure is simple and I think it can be documented easily
> (I would prefer the second approach as it is more general and we don't need
> to restart the engine when the user/pass or product key are modified).

Marina 
Do you agree with Miguel's suggestion that the second option is the preferred way to configure the sysprep file in order to specify the user/pass and the product key?

Should this appear in the doc's in your opinion or is this only used for a very specific case, in which case perhaps updating the KB article would be better.

Could you pls. bring up this issue with the teams and let me know what you think I should do.
Thanks!

(In reply to Emma Heftman from comment #13)
> Some additional information from a conversation with Martin P with regards
> to comments concerning the use of ldap-aaa with AD and kerberos
> 
> AD can be used without kerberos or with it.
> <mperina> Default simplest way is not using kerberos, that's what
> aaa-ldap-setup-tool does
> <mperina> Previous engine-manage-domains offered only kerberos and only for
> a single domain (no forrest) and it was written in a really bad way
> ...
> <mperina> If someone wants, to configure kerberos for aaa-ldap, it's of
> course possible, but it's fully manual operation
> 
> <mperina> ... certificates are relevant, if you choose StartTLS or LDAPS
> connection, but they can also be relevant for kerberos
> 
> ... bug which covers how to configure aaa-ldap using kerberos to access AD
> ...
> <mperina> Here are relevant bugs:
> <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1322940
> <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1361223
> 
> Martin also suggested that they will create an example for this and add it
> to the next aaa-ldap release

Tracked by BZ1489402

> 
> Martin, if you do create such an example please let me know as i think it
> could be useful to document the examples that are being provided...

I don't think so, here it should be noted only that aaa-ldap needs to be configured for relevant AD server, but it does not matter how (no reason to distinguish between setup tool or manual configuration or even mentioning some special configuration).

(In reply to Martin Perina from comment #15)
> (In reply to Emma Heftman from comment #13)
> > Some additional information from a conversation with Martin P with regards
> > to comments concerning the use of ldap-aaa with AD and kerberos
> > 
> > AD can be used without kerberos or with it.
> > <mperina> Default simplest way is not using kerberos, that's what
> > aaa-ldap-setup-tool does
> > <mperina> Previous engine-manage-domains offered only kerberos and only for
> > a single domain (no forrest) and it was written in a really bad way
> > ...
> > <mperina> If someone wants, to configure kerberos for aaa-ldap, it's of
> > course possible, but it's fully manual operation
> > 
> > <mperina> ... certificates are relevant, if you choose StartTLS or LDAPS
> > connection, but they can also be relevant for kerberos
> > 
> > ... bug which covers how to configure aaa-ldap using kerberos to access AD
> > ...
> > <mperina> Here are relevant bugs:
> > <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1322940
> > <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1361223
> > 
> > Martin also suggested that they will create an example for this and add it
> > to the next aaa-ldap release
> 
> Tracked by BZ1489402
> 
> > 
> > Martin, if you do create such an example please let me know as i think it
> > could be useful to document the examples that are being provided...
> 
> I don't think so, here it should be noted only that aaa-ldap needs to be
> configured for relevant AD server, but it does not matter how (no reason to
> distinguish between setup tool or manual configuration or even mentioning
> some special configuration).

We need to be able to say that for 
1. Whole forest with multi-domain trust
 2. Whole forest containing only a single domain (aka single domain setup)

 you can use the tool, but for 

1. Active Directory with selected single server using StartTLS
2. Active Directory with selected multiple servers using StartTLS
3. Active Directory with selected multiple servers using LDAPS
4. Active Directory with server defined in DNS SRV records using LDAPS
5. Single sign-on with Active Directory
6. 4.1.7 kerberos

 configure the properties file manually by customizing the examples.

Those examples would be great. And if the Active Directory side needs any special setups, we need to document that too.  We cannot assume that the Active Directory side will have already-working certificate servers and an SSL/TLS infrastructure ready to go.  Most don't. Most just use Kerberos and DNS SRV records for everything.

(In reply to Greg Scott from comment #17)
> Those examples would be great. And if the Active Directory side needs any
> special setups, we need to document that too.  We cannot assume that the
> Active Directory side will have already-working certificate servers and an
> SSL/TLS infrastructure ready to go.  Most don't. Most just use Kerberos and
> DNS SRV records for everything.

Thanks Greg. I think we need to separate the issue of customers setting up their certificate infrastructure from the scope of this specific bug.
I'm going to focus on getting as much information as possible with regards to improving the Active Directory setup procedures.

Hi Martin
I have a question about the interactive setup for AD. In bug 1472254 you said that you can only use the forest name (i.e. root domain), however in step 4 of the following section about using the tool for AD, it says that 

"If the forest name is not resolvable by your Manager's DNS, the script prompts you to enter a space-separated list of Active Directory DNS server names. "

Does this mean that it is possible to enter domain names instead of the forest name?

Also, in bug 1462294, it mentions that if you enter the wrong forest name the script exits. Has this behavior been fixed?

Thanks!
Emma

After discussing Miguel Martin's sysprep configuration method with Yaniv Kaul, he suggested we document both methods:
Using RHV's sysprep template
Customizing the standard template - Miguel's method. As this method has not been tested by QE, I have opened a separate bug to track this issue:

https://bugzilla.redhat.com/show_bug.cgi?id=1490107

Hi Michal
I'm working through feedback from support with regard to configuring templates and pools in Windows environments.

One comment that I received was 
"It is also confusing because of the 'Admin password' section on 'Initial Run' in a Template or Pool (just below the domain related configurations), corresponds to the local windows administrator, not the domain administrator. To add more confusion the default local administrator is the user named 'user'.

In the documentation, when configuring a template or pool, for most fields, we refer the user to the docs for creating a new virtual machine.
So for example, when creating a windows template/pool, in the Initial Run tab, the documentation says:

Admin Password:
The administrative user password for the virtual machine. Click the disclosure arrow to display the settings for this option.

    Use already configured password: This check box is automatically selected after you specify an initial administrative user password. You must clear this check box to enable the Admin Password and Verify Admin Password fields and specify a new password.
    Admin Password: The administrative user password for the virtual machine. Enter the password in this text field and the Verify Admin Password text field to verify the password.


Do you think I should change this to say. "Note that when configuring templates or pools, you must define the local windows administrator as user, and not the domain administrator"

(In reply to Emma Heftman from comment #16)
> (In reply to Martin Perina from comment #15)
> > (In reply to Emma Heftman from comment #13)
> > > Some additional information from a conversation with Martin P with regards
> > > to comments concerning the use of ldap-aaa with AD and kerberos
> > > 
> > > AD can be used without kerberos or with it.
> > > <mperina> Default simplest way is not using kerberos, that's what
> > > aaa-ldap-setup-tool does
> > > <mperina> Previous engine-manage-domains offered only kerberos and only for
> > > a single domain (no forrest) and it was written in a really bad way
> > > ...
> > > <mperina> If someone wants, to configure kerberos for aaa-ldap, it's of
> > > course possible, but it's fully manual operation
> > > 
> > > <mperina> ... certificates are relevant, if you choose StartTLS or LDAPS
> > > connection, but they can also be relevant for kerberos
> > > 
> > > ... bug which covers how to configure aaa-ldap using kerberos to access AD
> > > ...
> > > <mperina> Here are relevant bugs:
> > > <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1322940
> > > <mperina> https://bugzilla.redhat.com/show_bug.cgi?id=1361223
> > > 
> > > Martin also suggested that they will create an example for this and add it
> > > to the next aaa-ldap release
> > 
> > Tracked by BZ1489402
> > 
> > > 
> > > Martin, if you do create such an example please let me know as i think it
> > > could be useful to document the examples that are being provided...
> > 
> > I don't think so, here it should be noted only that aaa-ldap needs to be
> > configured for relevant AD server, but it does not matter how (no reason to
> > distinguish between setup tool or manual configuration or even mentioning
> > some special configuration).
> 
> We need to be able to say that for 
> 1. Whole forest with multi-domain trust
>  2. Whole forest containing only a single domain (aka single domain setup)
> 
>  you can use the tool, but for 

More correct is to say:

"You can use the tool for above, but anything else need to be configured manually. Here are examples of most common advanced configuration, which can be customized to your environment"

> 
> 1. Active Directory with selected single server using StartTLS
> 2. Active Directory with selected multiple servers using StartTLS
> 3. Active Directory with selected multiple servers using LDAPS
> 4. Active Directory with server defined in DNS SRV records using LDAPS
> 5. Single sign-on with Active Directory
> 6. 4.1.7 kerberos
> 
>  configure the properties file manually by customizing the examples.

(In reply to Emma Heftman from comment #19)
> Hi Martin
> I have a question about the interactive setup for AD. In bug 1472254 you
> said that you can only use the forest name (i.e. root domain), however in
> step 4 of the following section about using the tool for AD, it says that 
> 
> "If the forest name is not resolvable by your Manager's DNS, the script
> prompts you to enter a space-separated list of Active Directory DNS server
> names. "
> 
> Does this mean that it is possible to enter domain names instead of the
> forest name?

No the above message just mean that entered forrest cannot be resolved by DNS servers specified on engine host. But you can enter different DNS servers, which can be used for aaa-ldap instead of changing DNS servers configured on engine host.

> 
> Also, in bug 1462294, it mentions that if you enter the wrong forest name
> the script exits. Has this behavior been fixed?

I think you are referring to [1], but this comment is no longer valid, because we found out that complete implementation would be almost impossible. So [1] has been replaced with [2] and [3], which contain valid information.

So if users enter invalid forrest, then the tool will exit (but we have improved error message to be more detailed)


[1] https://bugzilla.redhat.com/show_bug.cgi?id=1462294#c2
[2] https://bugzilla.redhat.com/show_bug.cgi?id=1462294#c4
[3] https://bugzilla.redhat.com/show_bug.cgi?id=1462294#c5

Putting the bug back to Modified in order to document the "standard" method using QE as the method documented and approved was not officially tested by QE and is pending bug: https://bugzilla.redhat.com/show_bug.cgi?id=1497933

*** Bug 1490107 has been marked as a duplicate of this bug. ***

We have now been given clearance to go ahead with documenting the tested procedure for 4.2.3 (RHV 4.2 GA).

Given that Emma already has a full workload leading up to that milestone, I'm reassigning this BZ to Avital for review.

Avital, you might be able to use some of the existing content in Emma's merge request (see comment 36) as a starting point for this one.

verified and merged.

The needinfo request[s] on this closed bug have been removed as they have been unresolved for 1000 days