What can be defined in sites-enable/a_site

[James Sumners]

On 2015-04-14 17:21:47 +0000, Alan DeKok said:

> On Apr 14, 2015, at 1:01 PM, James Sumners <james.sumners at clayton.edu> wrote:
>> It's pretty simple to indicate how many times a block can be used in 
>> the configuration: once or multiple. Asking users to infer this from 
>> the 200 or so configuration files that double as the documentation is, 
>> frankly, ridiculous.
> 
>   So... asking people to read the configuration files is ridiculous?

That's not what I said. I said relying on them to be the documenation 
is ridiculous. There are MANY of them, they are not in any order, are 
not easily referenced, and it is very easy to get lost in them.

>   The radiusd.conf file says "the 'modules' section loads modules".  
> There is NOTHING which says that modules can be located elsewhere.  The 
> conclusion should be pretty simple.
> 
>   Unfortunately, some people want to be spoon fed.  You can't put 
> "listen" sections into module configurations.  You can't put virtual 
> servers into module configurations.  You can't put module 
> configurations in virtual servers.  You can't put module configurations 
> into client definitions.

Yes, it's unfortunate that the people who didn't develop the product 
expect the people who did to actually provide information on how to use 
it.

>   The list of what is NOT allowed is infinite.  The list of what IS 
> allowed is small, and is clearly documented.

I didn't suggest you list the infinite. I suggested you list how the 
block is interpreted by the config parser. Is a block unique or do 
subsequent definitions override previous definitions? How difficult is 
that to understand?

> 
>> I'll break down what led to the orginal post in this thread:
>> 
>> 1) I read the thread where someone was having an issue with rlm_memcached
>> 2) I tried to investigate this module as I could be interested in using it
>> 3) I go to the web site to read the documenation
>> 4) I browse through the few man pages on the site that don't 404
>> 5) I see that the few documented modules indicate that their 
>> configuration can be included in a `modules` block
>> 6) I realize that my site file also contains global definitions for clients
>> 7) I attempt to move one of my `mods-enabled` configs to the global 
>> space of my site file
> 
>   i.e. NOT reading "radiusd.conf" to see where modules.  NOT reading 
> raddb/mods-available/README.rst to see HOW the modules are defined.  
> Instead, just going "I know, I'll starry putting random things into 
> random config files.  WTF?  It doesn't work?  YOU BASTARDS".

Let's look at an example of the documentation in radiusd.conf:

# PROXY CONFIGURATION
#
#  proxy_requests: Turns proxying of RADIUS requests on or off.
#
#  The server has proxying turned on by default.  If your system is NOT
#  set up to proxy requests to another server, then you can turn proxying
#  off here.  This will save a small amount of resources on the server.
#
#  If you have proxying turned off, and your configuration files say
#  to proxy a request, then an error message will be logged.
#
#  To disable proxying, change the "yes" to "no", and comment the
#  $INCLUDE line.
#
#  allowed values: {no, yes}

Okay, I can turn proxying on or off. Great. What is it useful for? Why 
would I want to turn it on? "Read proxy.conf" you say? Okay...

#######################################################################
#
#  Proxy server configuration
#
#  This entry controls the servers behaviour towards ALL other servers
#  to which it sends proxy requests.

Uh, wonderful. That's all we get to describe the feature. The rest of 
the file describes each option (as should be done). It doesn't do 
anything to explain how to use the feature or why you'd want to.

> 
>   Forgive me if I don't have a lot of sympathy.  While the 
> documentation isn't perfect, I'm continually amazed at the people who 
> look every EXCEPT the documentation that ships with the server.

They're looking elsewhere because the documentation that ships with the 
server is not sufficient for someone who didn't write the software.

> 
>   Should I put big warnings on the web pages which say "PLEASE READ THE 
> CONFIG FILES YOU ARE EDITING.  IT HELPS"  ?
> 
>> 8) Failure
>> 9) Spend 45 minutes trying to find documentation to figure out the problem
> 
>   Yeah, it's hard work to find the READMEs that come with the server.   
> Things in raddb/mods-available?  Woo.... can't look THERE for 
> documentation.  That wouldn't make any sense.

No, it doesn't really make sense. In basically every other project the 
"documentation" in the configuration files is to explain the options 
defined in those configuration files. That is not the same as 
describing the features, what they do, and how they work together.

> 
>> 10) Give up and post to this list
> 
>   And get told that a little bit of thought is productive.  Which is I 
> think your main point of frustration.

You know what is meant in the docs you are referencing because you 
wrote them. You can fill in the gaps because you know what should be in 
those gaps. Telling the users to infer those with no prior knowledge of 
how the software works is akin to saying "why don't you know what I'm 
thinking?"

Getting back to this subject of this thread... Phil Mayers actually 
answered my question. You tried to answer something I didn't even ask: 
"can clients be defined in a server section?" I knew the answer to 
that; that part is actually documented. But the example, literally 
`sites-available/example`, shows client blocks being defined _outside_ 
of the server block. Thus, it can be inferred, which is you suggestion 
every time, from that example that other configuration blocks can also 
be included in the site file. And since I want to modify the shipped 
configuration files as little as possible, I attempted to contain my 
modules config in the same way as I evidently could my clients -- in 
the same file as my server configuration.

In short you can't have it both ways: you can't ask us to piece stuff 
together from the stuff in the config files and then complain when we 
attempt to do so.