dchil...@bestmail.us: > Hi Wietse > > > > On Tue, 05 Apr 2011 22:07 -0400, "Wietse Venema" <wie...@porcupine.org> > > For more, see: > > > > http://www.postfix.org/POSTSCREEN_README.html > > http://www.postfix.org/postscreen.8.html > > > > If any text in there is not 100% clear, send suggestions for > > improvement. > > Since you asked about clarity in documentation and suggestions ... I > hope the following perspective will be of some help. It includes 'a > suggestion for improvement'; just my $0.02.
I find that Postfix documentation can always be improved. Despite a lot of review there are still inaccuracies and omissions. > In some instances, although I'm reading and re-reading the docs, I'm not > finding it an efficient process to get the info I need out. Indeed. The current documentation focuses on the basics: being precise (no errors or omissions). It's like an illustrated encyclopedia. This does not help people who don't know what they are looking for, or what solutions may exist for a problem that may not be well understood. Unfortunately, it's not practical for me to maintain lots of ready-to-run examples beyond the examples in the README files. > I'm finding > I have to dig in a lot of different places to ferret out a single answer > in the context of a 'real world' setup. And, I'm not being very > successful at it. I'll shoulder my part of the bargain, and admit to > lack of experience & understanding at this point. > > Two current examples. > > postscreen & stress support. I see in the postscreen docs that certain > paramaters support stress parameters. To find out how to turn it on, I > have to go to the stress docs, and find the "-o stress=yes" param, then > surmise that it need to be added to the master.cf entry that contains > postscreen, only in the postfix instance that invokes it, and not in the > 'primary' config that's declared to be "more equal than others" ... > > In retrospect, or to the experienced user, the answer may be obvious. > To me it wasn't. It could've been made much simpler, imo, without > really changing the docs, but rather by having a commented set of config > files from a single, working, 'complex' example -- where I could SEE > what was done. There is no documentation about how to configure postscreen stress with master.cf, because that is not possible :-) All the steps to turn on/off postscreen are documented in POSTSCREEN_README examples at the end of the document. If the description of any step is incorrect, or if a step is missing, then a concrete suggestion for improvement is welcome. > as a 2nd example, TLS, which I'd mentioned in another message. again, > I've found the docs & man pages, and read through them. I'm still not > sure in how many places I'm supposed to add my key definitions, for > example. Only in the postscreen containing postfix instance's main.cf? > as "tls_" params for tlsproxy? Do I also need to add key defs in other > instances' configs? And if so, as "tls_" params for tlsproxy or as > "smtpd_" params? (this, e.g., "tlsproxy_tls_CAfile ($smtpd_tls_CAfile)" > is not clear as usage from the docs ...). When you configure TLS for receiving email, then you configure TLS for smtpd as documented in TLS_README. These settings for smtpd become the default settings for postscreen and tlsproxy, as documented in their respective manpages. Because of these default settings, postscreen and tlsproxy will use 100% identical TLS settings as smtpd. The idea is to make it easier than having to configure each program separately to do the same thing. > to have made this clearer, again, no change to the docs really required, > rather that same "single, working, 'complex' example" would do ... I suppose you can recommend some changes for the examples at the end of POSTSCREEN_README. I would not recommend burdening TLS_README with explicit configuration examples for postscreen and tlsproxy, because there is no good reason why those daemons should use TLS configuration that is different. > Among the better examples I can reference of what, for me, has worked > well in deploying a complex/dense product is 'Shorewall' documentation. > That it's a different product, topic, application is acknowledged and of > little relevance to my point ... > > If you take a look here: > http://www.shorewall.net/Documentation_Index.html, you'll note an > extensive list of 'use case' articles, tutorials, and documentation. In > addition to its similarly exhaustive documentation on parameters and > usage, I find these to be invaluable in actually getting a complex > conifg up and running. Someone would have to invest a huge amount of time not only writing up "complete" examples, but also keeping them up to date on Postfix development. That is the biggest problem with all the Postfix howtos on the web. They often have errors, and they almost always lag years of Postfix development. More practical, Postfix documentation is unlikely to evolve beyond the examples in the README files, simply because the cycles don't exist to maintain a set that is accurate, complete, and that is up to date on Postfix development. Wietse > I'm not suggesting getting to that point in one giant leap, and to > attempt to cover all scenarios. rather, as a first step, pick/define > _one_ more-or-less complex setup ***, using the tools-&-toys > modern/latest postfix provides, and provide a known working set of > configs for it. It would provide single, consistent context within > which to understand and apply the individually well-documented > componenets. > > With my luck, this already exists and I just haven't found it ... yet. > > HTH! > > DChil > > *** e.g., multiple instance, across multiple servers, listening at > multiple IPs, servicing multiple domains, using TLS, stress management, > etc. yes, i recognize it's challenging and requires effort to put > something like that together. that's the point ... > >
