Please improve documentation

[akaegi]

In particular I am missing in the docs:

• Section Synopsis: explain what the effect is of calling waf:exec() in all of access_by_lua, header_filter_by_lua and body_filter_by_lua. why do you need to call waf:exec() in each of them?
• Section Synopsis: it seems there is an error in log_by_lua. It seems to me it should rather log there and not call exec, as described by https://github.com/Kusumoto/docker-openresty
• It would be nice to have an example "curl" that shows that the WAF is indeed functioning as expected.

[p0pr0ck5]

Hi,

Section Synopsis: explain what the effect is of calling waf:exec() in all of access_by_lua, header_filter_by_lua and body_filter_by_lua. why do you need to call waf:exec() in each of them?

Calling exec in each phase executes the rules associated with the currently running phase. (also, we have plans to pass a phase to exec to arbitrary phase rules can be run anywhere). I can probably write a few sentences about this if it's thoroughly confusing :)

Section Synopsis: it seems there is an error in log_by_lua. It seems to me it should rather log there and not call exec, as described by https://github.com/Kusumoto/docker-openresty

The documentation in the dockerfile is out of date, since 22f1b1c we have allowed calling exec for log phase rules. I've opened Kusumoto/docker-openresty#1 to address this.

It would be nice to have an example "curl" that shows that the WAF is indeed functioning as expected.

Is this something you cannot see yourself? Maybe we can write an in-depth blog post for beginners. Or if you want to contribute to the documentation yourself, that would be wonderfully accepted :)

[akaegi]

Ok, thanks for your answer.
For 2: Ok, if I call exec in the log_by_lua phase then it also does the logging? This was confusing to me...
For 3: You're right that was not too difficult :-) Still it would have helped me as it was my first contact with setting up a web app firewall.

[p0pr0ck5]

Hi,

For 2: Ok, if I call exec in the log_by_lua phase then it also does the logging? This was confusing to me...

Yes, this is the case. The docs for this were updated in 31436e7, but I will try to clarify this a bit more. Patches welcome if there is specific language you think would be helpful :)

For 3: You're right that was not too difficult :-) Still it would have helped me as it was my first contact with setting up a web app firewall.

Makes sense :) I can write up a blog post or "getting started" wiki page and link to it in the docs. Again, if you'd like to write something up about your experiences, we'd love to have the contribution :)