I propose removing Appendix C: Administration settings from the Administering Foreman guide for the following reasons:
- It duplicates information that is already documented in procedures.
- It requires constant maintenance.
+1
It doesn’t add any value to information that users can see in the web UI.
Also the Settings depend on the installed plugins what is not mentioned at all.
I think having this as a reference only makes sense if we can auto-generate it like we did in the old manual with the command line parameters, everything else is to much effort for to less benefit.
+1 from me too.
When supporting users here on Discourse I have used the reference documentation so I can link to the exact setting so I think there is value in keeping it.
Building a script to export the settings in asciidoc is not hard. I was going to say we already have it, but it looks like I never committed it. I created lib/tasks/settings.rake with the following:
namespace :settings do
task overview: :environment do
registry = SettingRegistry.instance
registry.categories.each do |category, label|
puts <<~HEADER
= #{label} settings
[cols="30%,30%,40%",options="header"]
|====
HEADER
registry.category_settings(category).each_value do |setting|
puts "| *#{setting.name}* | #{setting.default} | #{setting.description}"
end
puts "|==="
end
end
end
It probably needs a bit more polish and scripting to automate updates around releases.
Having a list of options for a quick review without access to the web UI can be useful. Also, I don’t think the reference is available from the Hammer CLI, is it? (EDIT: Apparently it is! hammer settings list)
The point I’m trying to make is that while the lists are a (significant and annoying) maintenance burden, a reference like this is useful to have because not everyone can access the web UI from anywhere, at any time.
I recall that in the past we discussed the option of referencing the options + their definitions through linking to the code but that was deemed not very user-friendly.
I like the option of exporting the settings programmatically very much. It’s what we do with the Hammer reference right now – we recognize the value in having an online reference for Hammer commands, so we found a way to provide that to users with a script.
0 from RH support (I’ve checked with them.)
They are not against removing it, but we don’t know how many users have been using it. Support themselves don’t need it.
They like the idea of generating the reference programmatically.
If we decide to remove it, we should add a deprecation notice in the release notes of the preceding release.
“Just reading settings from docs would do no good if you can’t change them due to access issues.“
I already created Fixes #35577 - Add a settings:reference rake task by ekohl · Pull Request #9438 · theforeman/foreman · GitHub to automate it for the current website, but never really followed up on that.
Generating the sections with a rake task seems like a good solution.
I could check the numbers of page views for the sections, but it would be irrelevant if we are going to keep the section in and generate it automatically.
FYI - page visits over last 3 months for non-Red Hat visitors to the downstream Satellite Admin guide, App. C (all subsections):
- Oct. 2025: 6.17 - 27
- Nov. 2025: 6:17 - 10, 6.18 - 18
- Dec. 2025: 6.17 - 9, 6.18 - 13
I could generate stats for more months and versions but I think you get the idea.
Can we generate all the Admin settings? If so, that would remove the maintenance burden completely.
I do like Ewoud’s idea of keeping it and automating it. In fact, I kind of assumed it was automated from the start, since I recognized the wording from reading hammer help.
I think so far everyone agrees that the manually-maintained guide is not worth keeping. So the question is do we commit the additional effort to automate it (moving the maintenance burden more to developers), or go the other direction and remove it.
The responsibility for updating the reference doesn’t necessarily have to move to developers as long as we have guidelines how to generate it. (Which would have to happen once per release.)
But I don’t think that the reference is a useful way of documenting the settings - they should be documented in such a way that the docs provide additional context and use cases for changing them.
This is a great point. In Settings documentation I would expect to see additional explanation and overview of things like how Settings work, the fact that they are universal (not per-user or per-org), the different ways to set them, comparison and contrast of Settings, installer options, user preferences, and other ways to set application behavior, etc. That’s the real value that documentation can provide, which is much more than just a reference.
A layout that does not use tables would improve the usability of this section significantly. Bullet lists and definition lists are much easier to read. The default value of a setting could be appended to the description.
We are about to update our documentation for the containerized install. I think this would be a good time to mark this RFC as “decision made” and remove the guide.
The opportunity would be good, but I don’t think we’ve reached a consenzus on the deletion. Some people are for it, some are against it.
I’m not sure how to proceed.
Yes, it seems the consenzus is “Automate and improve or remove” which is still a decision to make. What do you think would it take to use what ekohl prepared/created for the old manual to at least automate it? If already this would need too much time spend better on real improvements, I would say “remove”. If this would not be a big thing, then we would still have the question on how to improve it and how much time this would cost, so probably this would also sum up to say “remove” and use the time for other improvements is the better option.
We could also remove it for now and re-add an automated, improved version later. Would everyone be okay with that?
That sounds good to me 
I took the opportunity and implemented something we already do for Foreman Error Codes. A rake task (as was suggested by @ekohl) which not only list settings locally, but can optionally also upload and update list of settings on our wiki:
As you can see I already executed it. The rake task has the following capabilities:
- Lists all the settings including all installed plugins
- Creates a page named
Setting_xxx - RedMine ignores the update if the content is the same as previous page
- Reads the main index page
Settingsand merges it with the list of new settings - Updates the index page
- Ensures this is all executed with English i18n
- There is a warning that the page was auto-generated everywhere
This way, we get a super-easy way of updating this anytime we want, from any environment (dev, test, prod) with or without plugins. All settings will be just added to the wiki. To test this:
FOREMAN_REDMINE_API_KEY=XXX bundle exec rake settings:wiki
Here is the PR:
The only limitation is that individual pages are generated, changes will be overwritten. I can add a link to the every page something like SettingNotesXXX which will create a (red) link to non-existing page with additional notes we can optionally fill in for some if we want.
Once this is merged, I will likely also update our error code generator so it also auto-updates the index page: ErrorCodes - Foreman