Users of Linux distributions know to read smb.conf(5) manual page but apparently not many of them read smbd(8) and winbindd(8) to understand how changes to smb.conf file are reflected in the running processes. Add a small section that makes it clear where to find relevant information. Also correct the information in smbd, nmbd, and winbindd manual pages. The interval at which smbd does check for smb.conf changes was increased from 60 seconds to 180 seconds in 1999 with commit 3db52feb1f3b.
Created attachment 16288 [details] v4.13 version
Created attachment 16289 [details] v4.12 version
Karolin, could you please apply the patches to the relevant branches? Thanks!
(In reply to Andreas Schneider from comment #3) Pushed to autobuild-v4-{13,12}-test.
This bug was referenced in samba v4-13-test: 1b6b85304d357f34638c0976b4c377b40b06efb7
This bug was referenced in samba v4-12-test: fe842a5412a914018e773a9a4930523905772ca2
Closing out bug report. Thanks!
This bug was referenced in samba v4-13-stable (Release samba-4.13.2): 1b6b85304d357f34638c0976b4c377b40b06efb7
This bug was referenced in samba v4-12-stable (Release samba-4.12.10): fe842a5412a914018e773a9a4930523905772ca2
It was requested by Alexander Bokovoy at https://bugzilla.redhat.com/show_bug.cgi?id=1888990#c6 that I post additional comments about this in this ticket. If this is not the correct place please let me know, where I should be making comments or if I should be starting a new bug ID or not. To try to keep as much of this in one place the rest of this specific comment will be partial scrapes of the following two redhat bug ID 1888990 11/9 comments so that the next comment I submit can be taken in context. https://bugzilla.redhat.com/show_bug.cgi?id=1888990#c5 and https://bugzilla.redhat.com/show_bug.cgi?id=1888990#c6 I have put … before or after to indicate that there are is more information. I said ..."This is a huge improvement. I especially like that the reloading information is the first section after the synopsis, I feel like had it been there before, this ticket would never have existed. That being said unless I am looking at the wrong version of the document, I think some more clarification in smb.conf documentation might be helpful. For the rest of this discussion block, I am looking at the smb.conf located at https://git.samba.org/?p=samba.git;a=blob;f=docs-xml/manpages/smb.conf.5.xml;h=c4387187ecc5803cf038617715d1b5daf6c928be;hb=e32846f0692df44b4ee929c5ed6ba1de88ec4bd2. Current line 46 says "The Samba suite's server daemons reload their configuration when requested" but fails to mention that it is automatically reloaded every 3 minutes . I think the just quoted sentence should be changed to something similar to "The Samba suite's server daemons reload their configuration every 3 minutes automatically or by manually reload" or to not have another place to change documentation in the case of a future change of the reload time interval, something like "The Samba suite's server daemons reload their configuration automatically at a regular time interval or sooner by a manually reload" The documentation might be a bit better if in the newly added sentence, to smb.conf (~lines 54/55), "To request Samba server daemons to refresh their configuration , please use smbcontrol utility" the word refresh were replaced with reload to be consistent with the terminology of the command as documented in the smbcontol binary. I really think in the smb.conf man page's WARNINGS section (currently starting on line 881), there should be something added about saving edits to the file and it being auto reloading. Maybe something along the lines of "It is highly recommended that all edits first be made to a copy of smb.conf file and then after completion and passing a testparm, moved into the smb.conf file location, as the Samba suite's server daemons are programed to regularly reloaded their configuration files, and any incomplete/incorrect configuration saved in smb.conf could automatically be implemented, potentially prevent new connections and/or starting new connections with the incomplete configuration that will persist until the client connection is restarted." This could probably be better worded. Note: I purposely didn't say how many minutes so there is one less things to edit should they decide to change the auto-reload interval again."... Alexander Bokovoy's responsed in https://bugzilla.redhat.com/show_bug.cgi?id=1888990#c6 with ..."These are the changes I did upstream after discussing with other developers. We intentionally put the references to individual daemons' man pages instead of mentioning the refresh times in the smb.conf(5). The behavior is different in different daemons and it is better to consult specific man pages for those daemons. It also gives us an opportunity to make users aware of those individual manual pages." ...
I could be misinterpreting Alexander Bokovoy’s response but it sounds like he is saying the samba documentation Team thinks that the way thing are currently in regards to smb.conf and it’s auto-reloading is fine the way it is and that you are already leading users to read the other man pages that talk about the auto reloading that could be different depending on the specific build/daemons. While based on my previous comment, I agree that not mentioning specific time frames for the reload in the smb.conf man page would make some sense, for somebody like me and my co-workers where we are basically just maintaining a samba server that somebody else set up and occasionally adding shares, the smb.conf man page not making any direct mention that smb.conf is automatically reloaded by smbd and other Samba suite servers daemons, is not leading us on to read those other documents, whereas some kind of mention about some samba suite server daemons, automatically reloading smb.conf and a warning about not modifying smb.conf directly, has the potential to encourage us to read the other man pages to see what were are doing be affected, or at least would give us the heads up to be carefull. The current wording of “The Samba suite's server daemons reload their configuration when requested” is highly misleading to me. While technically true automatic reloads are requested by the different daemons, the lack of any wording indicating that certain daemons automatically reload the config file, implies to me that it is only reloaded when the administrator does something to manually requested it be reloaded. This was also the understanding of my long time unix/linux co-workers, who do minor samba share maintenance, additions, removals,…. If it was clearly stated in the smb.conf document in some way that it is regularly automatically reloaded and ideally a later warning about ideally editing a copy of the file, until it passes a tetparm and then moving the copy in place, due to the regularly scheduled reload of some Samba suite server daemons, we may not have been under that impression and thus be better administering samba on our fileservers. Thank you for considering these comments on the smb.conf documentation.
Thanks, Alexander. So, what I see here are two different asks. 1. Improve wording to explain what triggers reload of the configuration files. This would need to be done in the daemon-specific manual pages, in my opinion, since it differs between the daemons. 2. Add a paragraph on best practices how smb.conf changes should be done. This would include use of testparm, working on a copy until satisfied and then copying over the changed file to the place where Samba suite can see it.
(In reply to Alexander Bokovoy from comment #12) RE: #1 I honestly don't know the samba suite code base well enough and haven't read through enough of the different daemon documentation to know if the specific deamons documentation needs wording adding about reloading triggers or not. With my limited knowledge the smbd 8 man page ( https://git.samba.org/?p=samba.git;a=blob;f=docs-xml/manpages/smbd.8.xml;h=73d808c70b735eeb08ca497027d5fb601d90aaf7;hb=e32846f0692df44b4ee929c5ed6ba1de88ec4bd2 ) seems to cover that it reloads configuration files automatically on a time interval or when forced. From my limited samba knowledge that appears sufficient for that document. Though the samba daemon experts would need to decide that on a daemon by daemon basis, as they would be the ones to determine if all of the automatic reload triggers are documented. Re: #2 Depending on how you word/format the Paragraph on Best Practices that could open a huge can of worms on what all should be documented as best practices, so you may want to be careful how you word that. (Though a section of a bunch of best practices for smb.conf might be a good thing.) That being said, I would say a paragraph on best practices of editing smb.conf makes sense. However I don’t think that a Paragraph on Best Practices, should supersede adding an item in the Warnings section about not editing smb.conf directly due to daemons autoreloading smb.conf happening on time intervals and other triggers and potentially preventing new connection/opened connections being persistent based on what was loaded at the time of connection. In my opinion the potential damage that could be caused by directly editing smb.conf warrents a mention in the warnings setion. Though if you were to add a best practices of editing smb.conf somewhere in the warning and why you could refer people to the best practices of editing smb.conf section of the man page. My interpretation of your #1 & #2 leave me thinking that it will miss talking about the automatic reloads in the “ How Changes are Applied” section of smb.conf ( https://git.samba.org/?p=samba.git;a=blob;f=docs-xml/manpages/smbd.8.xml;h=73d808c70b735eeb08ca497027d5fb601d90aaf7;hb=e32846f0692df44b4ee929c5ed6ba1de88ec4bd2 ). Since this section is generic I really think that since the section is entitled “How Changes are applied,” the fact that they are also automatically applied needs to be mentioned somewhere, as they will be applied. Since my initial idea of wording for the paragraph starting on line 46 was too specific, maybe the sentence starting on line #46 of “The Samba suite's server daemons reload their configuration when requested,” could be changed to something like “The Samba suite's server daemons reload their configuration when manually requested or for some daemons via automatic triggers like time intervals” and maybe a some additional example trigger reasons. Then continue onto the already active connections wording as is. That would at least get the general idea that your changes will/could be implemented automatically. Leaveing it up to the end user to do more investigating in other man pages for what those triggers are for each daemon. (Though for my purposes, I think adding a specific example of smbd automatically reloading on a time interval would be ideal.) #3 I know there is a lot here but did you not mention anything about the possibility of changing refresh to reload. Is this because you are still thinking about this at the higher general format level?
(In reply to Alexander Kohr from comment #13) > Re: #2 > Depending on how you word/format the Paragraph on Best Practices that could > open a huge can of worms on what all should be documented as best practices, > so you may want to be careful how you word that. (Though a section of a > bunch of best practices for smb.conf might be a good thing.) That being > said, I would say a paragraph on best practices of editing smb.conf makes > sense. > > However I don’t think that a Paragraph on Best Practices, should supersede > adding an item in the Warnings section about not editing smb.conf directly > due to daemons autoreloading smb.conf happening on time intervals and other > triggers and potentially preventing new connection/opened connections being > persistent based on what was loaded at the time of connection. In my > opinion the potential damage that could be caused by directly editing > smb.conf warrents a mention in the warnings setion. Though if you were to > add a best practices of editing smb.conf somewhere in the warning and why > you could refer people to the best practices of editing smb.conf section of > the man page. I believe Marc (author of Samba documentation in RHEL) and Andreas are working on some clarification for this. I think we'd add a mark to individual parameters that require restart of smbd (e.g. cannot be updated automatically or forced through signals or smbcontrol) -- these are the ones that define what network interfaces smbd will be listening on and some others, like disabling spoolss services. It would take some time to get this clarified as we'd need to go by each parameter in the global section. As for warnings, yes, looks like we need to add something that was considered an obvious behavior for pretty much all UNIX services that dynamically reflect their configuration. Now that I think about it, I couldn't call out exact examples though. ;) So may be you are right that this needs a bit of clarification. > My interpretation of your #1 & #2 leave me thinking that it will miss > talking about the automatic reloads in the “ How Changes are Applied” > section of smb.conf ( > https://git.samba.org/?p=samba.git;a=blob;f=docs-xml/manpages/smbd.8.xml; > h=73d808c70b735eeb08ca497027d5fb601d90aaf7; > hb=e32846f0692df44b4ee929c5ed6ba1de88ec4bd2 ). Since this section is generic > I really think that since the section is entitled “How Changes are applied,” > the fact that they are also automatically applied needs to be mentioned > somewhere, as they will be applied. I think this will apply in the per-parameter flags. We would mention something in that section but then would add some an explicit phrase to the each parameter that requires full smbd restart. > Since my initial idea of wording for the paragraph starting on line 46 was > too specific, maybe the sentence starting on line #46 of “The Samba suite's > server daemons reload their configuration when requested,” could be changed > to something like “The Samba suite's server daemons reload their > configuration when manually requested or for some daemons via automatic > triggers like time intervals” and maybe a some additional example trigger > reasons. Then continue onto the already active connections wording as is. > That would at least get the general idea that your changes will/could be > implemented automatically. Leaveing it up to the end user to do more > investigating in other man pages for what those triggers are for each > daemon. (Though for my purposes, I think adding a specific example of smbd > automatically reloading on a time interval would be ideal.) Kind of that, yes. I guess we can discuss exact content in a merge request once it is ready. > #3 I know there is a lot here but did you not mention anything about the > possibility of changing refresh to reload. Is this because you are still > thinking about this at the higher general format level? There is no way to change refresh to reload. It is hardcoded in smbd for last 20+ years.