Document all control files and make it easy to find [#2034391]

Having just been affected by the enable_user_register_protection.info file, I was made aware by users emailing me with requests like "When can I get access to your site?"

It would be nice if maybe daily.sh or aegir (on site creation) would run a touch on all possible config files.

I did a grep across global.inc and came up with the list of control files. I then created all the files within the 'sites/'. $_SERVER['SERVER_NAME'] .'/modules

For example

touch allow_anon_node_add.off
touch cookie_domain.off
touch disable_admin_dos_protection.off
touch disable_user_register_protection.info
touch enable_user_register_protection.off
touch nginx_cache_day.off
touch nginx_cache_hour.off
touch nginx_cache_quarter.off
touch redis_cache_disable.off
touch redis_lock_enable.off

Note that any file which did not exist I set as .off and if it did exist (and is used) then it's left as .info. This allows me to easily rename the file from .off to .info as needed.

I then populated the contents of that file with the url pointing back to Omega docs.

For example

o1.ftp:[modules]$ cat disable_user_register_protection.info 
http://omega8.cc/node/273

While I would love to hack up a quick script, I'm under the gun on a project right now.

A quick little

echo 'http://omega8.cc/node/273' > sites/SITE_NAME/modules/disable_user_register_protection.info (or .off - depending on defaults)

would be really helpful if this happened when a new site is created - or as part of daily.sh or some other script.

It would also be nice to have a new doc file named something like CONTROL.txt within /docs of the source if it's not already there somewhere. It would list the urls and information about the reason for the control file.

Comments

Comment #1

mattman CreditAttribution: mattman commented 4 July 2013 at 00:53

Having just read #2015553: Force user_register policy unless modules/disable_user_register_protection.info exists, it seems like a script which creates these control files could also maintain a registry of the names of all such files.

When Barracuda is updated, a diff against the registry of named control files could cause an administrative email to be sent when a new file is added. With a simple cat of the file itself, this would notify the system admin of the addition of such a file and allow them to review the changes.

I too was affected by the events within the above mentioned issue and my GotDrupal site, which only had 3 accounts, all of a sudden has over 60 accounts due to spam bots because of the unexpected change.

Implementing a change notification system would be really nice for those who are running BOA servers.

Comment #2

Jim Kirkpatrick CreditAttribution: Jim Kirkpatrick commented 4 July 2013 at 08:50

Thanks Matt.

I like the idea because it cleans up a set of unknown states (as far as BOA is concerned at least), but my point in my comment over on 2015553 is that control files in the PHP/Drupal world smell a bit. I'd personally like to see these consolidated into one per-site or per-platform include to override defaults set in global.inc. I just don't like having to look at a directory structure to know how a piece of Drupal code will execute -- seems very old skool and is better suited to the Bash/Perl worlds where there isn't a PHP framework like Drupal involved.

So I'm going to raise a ticket with a fuller proposal this week.

But in the mean time, your approach would go a long way to making what is currently implicit, explicit -- and clarifying behaviours of any given site.

Comment #3

omega8cc CreditAttribution: omega8cc commented 5 July 2013 at 09:34

Title:	Auto generate all control files	» Document all control files and make it easy to find
Component:	Other Services	» Documentation
Status:	Active	» Needs work

I would rather create a single file, like sites/all/modules/CONTROL.info and sites/foo.com/modules/CONTROL.info with all control files explained inside - or even a link to docs on the web, so we don't need to update this file. This is still not enough, because you can't expect that people will expect and find docs like this. This still needs to be documented properly on the web, in the project own docs/ and clearly linked in every welcome and upgrade e-mail.

Comment #4

jeremyr CreditAttribution: jeremyr commented 24 July 2013 at 20:21

I like the idea of the control file docs residing both online and inside of the platform. This would make it easy to find for reference when someone needs to use them. But for sure some way of communicating the new control files is a extremely important. I too have many sites that suffered from the lack of "advertising" the change related to this issue https://drupal.org/node/2015553 One site even has something like 128 pages of blocked user accounts.

Anyway, documentation and notifications should mitigate these type of issues in the future.