Announcement: Red Hat Satellite 6.1 Documentation Updates
The Red Hat Satellite Documentation Team has released the first async update to the Satellite 6.1 documentation. This includes updates to the following books:
- Installation Guide: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/Installation_Guide/index.html
- User Guide: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/User_Guide/index.html
- Puppet Guide: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html-single/Puppet_Guide/index.html
This asynchronous release addresses various bugs that existed in the GA release, and also covers some new topics:
- The Installation Guide includes a new chapter on how to configure a self-registered Satellite.
- The User Guide includes new chapters and sections on Discovery, how to enable debug logging, and using OpenSCAP.
Other improvements were also made to enhance readability. See the Revision History of each book for more details.
We would like to hear from you if you have any feedback or questions about these or any other Satellite guides.
Cheers,
Red Hat Satellite Documentation Team
Responses
David,
I have found a few minor inconsistencies in this documentation. A good example is this virt-who documentation https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html/Installation_Guide/sect-Red_Hat_Satellite-Installation_Guide-Managing_Hypervisors_and_Virtual_Guest_Subscriptions-Setting_up_a_VMware_Hypervisor.html
This sentence:
The system running virt-who requires open access to vCenter on ports 80 and 443. Before following these steps, create a firewall exception to allow connections on port 80 and 443 from the Red Hat Satellite server to the vCenter:
The system that needs access to vCenter on ports 80/443 is the RHEL VM running virt-who, so connectivity is from the RHEL VM to the vCenter server (this RHEL VM may be the Satellite server). Directly under this paragraph the documentation provides firewall rules for the RHEL VM (that is running virt-who) that are inbound for new connections, this is in the incorrect direction.. the vCenter doesn't initiate new connections to the RHEL VM.
From the above paragraph "from the Red Hat Satellite server to the vCenter", this isn't completely correct. It is the RHEL VM that is running virt-who that needs access to the vCenter on 80/443, not the Satellite server. The Satellite server may be running virt-who, but this isn't the scenario described in the documentation. If virt-who is running on a different guest (commonly described configuration), Satellite doesn't interact with vCenter directly.
Hello
Thank you for reporting this.
The vCenter is receiving, so ports need to be opened on the base system running vCenter. What would that typically be? Could it ever be the same base system as is running the VMs?
We can raise a bug in the mean time.
Thank you
vCenter will either be installed on a Windows server or a standalone vCenter virtual appliance (Linux, but not something you need to modify). It won't ever be the RHEL server running virt-who.
The Puppet guide also seems to have a consistency issue in the section referring to building your own class and configuring smart variables.
In section 3.7 the comment is:
For example, mymodule contains a parameter for the HTTP port of our web server. This parameter, httpd_port, is set to a default of 8120.
Except the mymodule class that is built in the tutorial doesn't include an httpd_port parameter. There is an httpd_port variable referenced in the template and in the SELinux rule, but it's not a parameter with a default value in the mymodule class.
From section 2.9 of the same document (no parameter in mymodule class declaration)
class mymodule {
include mymodule::httpd
include mymodule::app
}
I also believe the way the firewall and SELinux exec resources are configured in the example mymodule is likely to cause problems. They are both subscribed to the httpd package resource and are configured for refresh only, so will only fire/execute if the httpd package resource changes. If the httpd package is already installed on the server Puppet won't change the state of the httpd package resource, so I don't believe it will execute these Execs. Additionally, if you run the module and it configures the port (say 8120) and you then change the port and re-run Puppet, the firewall and iptables Exec won't execute to update the port because the httpd package state won't change (it's already installed), so your saved firewall and SELinux configuration will be out of step with your passed in parameter.
Apologies for formatting, there is currently something wrong with the discussion forum that is breaking formatting in responses.
To follow up on the 'mymodule' example Puppet module problems, here is an example of the issue. I have created a basic manifest to run locally that triggers an exec in the same way as the sample module (httpd_port variable provided inline rather than a parameter, but same outcome).
$httpd_port = 4000
package { "httpd":
ensure => installed,
}
exec { "firewall-cmd ${httpd_port}":
command => "/bin/echo \"this message in place of iptables\"",
refreshonly => true,
subscribe => Package['httpd'],
}
Results from the first run are in the below code block. httpd is installed and exec fires because state of 'httpd' package changes from not installed to installed.
[root@cupcake ~]# puppet apply mymodule.pp
Notice: Compiled catalog for cupcake.pixeldrift.local in environment production in 0.40 seconds
Notice: /Stage[main]/Main/Package[httpd]/ensure: created
Notice: /Stage[main]/Main/Exec[firewall-cmd 4000]: Triggered 'refresh' from 1 events
Notice: Finished catalog run in 10.15 seconds
Now that the package is installed, the Exec will no longer fire, so the firewall port will never be updated. To demonstrate this, you can change the httpd_port variable at the start of the mymodule.pp file, eg.
$httpd_port = 3000
Now when you re-run the script the Exec (firewall) update won't occur because the httpd package is already installed even though the variable/parameter has changed.
[root@cupcake ~]# puppet apply mymodule.pp
Notice: Compiled catalog for cupcake.pixeldrift.local in environment production in 0.39 seconds
Notice: Finished catalog run in 0.53 seconds
This problem exists for both the firewall and semanage commands in the example mymodule Puppet module. I think the example needs reworking.
Thank you very much for reporting this problem. I have raised this bug:
Bug 1290076 - mymodule class example has no httpd_port parameter
Hello, that is now resolved: https://bugzilla.redhat.com/show_bug.cgi?id=1290076#c12
I realise this is probably a little late.. but I still feel the examples are still broken. Yes the parameter has been added to the module, but changing this parameter won't update the server's configuration.
The 'exec' being used for the firewall and the semanage commands just won't work as expected. If the httpd package is already installed they won't fire because they are configured with 'refreshonly' on the httpd resource. The same issue with port exists as I mentioned above. If someone changes the input parameter for httpd_port, there will be no change made on the server.
The firewall resource should be managed with the firewall resource type.
https://forge.puppet.com/puppetlabs/firewall
When using exec, the semanage rule should have an 'unless' that checks if the port is already listed/configured (eg. semanage port -l), and update the rule if it isn't.
This is handled in the following module under 'selinux::portcontext':
https://forge.puppet.com/thias/selinux
I realise the 'exec' calls have been added for simplicity of the example, but the example isn't showing the real benefit of puppet being able to update/reconfigure servers based on input.
Thanks Stephen,
I also think the Content View section of the user guide needs some additional details around filters: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html/User_Guide/sect-Red_Hat_Satellite-User_Guide-Using_Content_Views-Filtering_Content.html Currently there is no explanation as to how the Content View filters are parsed. There doesn't appear to be a method in the UI to order the Content View filters, so are they parsed in the order they are added? or are exclude filters parsed before include or vice-versa? How are conflicts in rules resolved? Is it suggested that include/exclude filters not be mixed in the same Content view?
There also isn't any discussion in the documentation with regard to Content View versions and their relationships. Is version 2.0 inclusive of version 1.0 content? or is it a completely different instance of the content so all filters must be redefined? (Diagram figure 6.1 doesn't make this clear)
Can the documentation also possibly include a description as to why a Composite Content View can't contain content from two different Content Views if they contain the same repository? This seems like an artificial constraint.
Thank you again for reporting problems in the docs. I have raised this bug:
Bug 1290411 - Improve docs for Content View filters and versions
I have found discussion around this topic dating back to 2012, unfortunately it still doesn't appear to be formally documented anywhere (please provide a link if someone has one). https://www.redhat.com/archives/katello-devel/2012-October/msg00301.html
In the User Guide, the section on Global Parameters needs to better describe the impact of selecting 'Hidden value'. In section '13.2.1. Creating a Global Simple Parameter', step 5 just states 'Select if value is hidden' without providing any insight or indication as to what impact selecting this option has.
Hello, thank you for pointing that out. I have raised this bug to get that procedure improved:
Bug 1291182 - What is hidden value in Creating a Global Simple Parameter
Add yourself to the cc field of these bugs if you would like to track the progress.
Hello, turned out this is just a feature to hide sensitive details in the web UI. That bug is now resolved.
The section Creating a Global Simple Parameter is now improved in 6.2 Host Configuration Guide.
Thank you.
Pro
798 points
General Satellite 6.x documentation question: are there any Release Notes or other documentation that indicate what specific bugs or features were addressed in the post-GA releases 6.1.{2,3,4}? The "Release Notes" document for 6.1 seems to only show 6.1.1 GA.
Please note that I found some additional typos and ambiguities in the Puppet Guide documentation, noted in: http vs httpd class, files directory, and puppet on FIPS.
Welcome! Check out the Getting Started with Red Hat page for quick tours and guides for common tasks.