Mercurial > prosody-modules
comparison mod_firewall/README.md @ 6538:de1f17ed4dac
mod_firewall: Add support for tracing rule evaluation in real-time
| author | Matthew Wild <mwild1@gmail.com> |
|---|---|
| date | Mon, 11 May 2026 13:37:19 +0100 |
| parents | 74774ec3af1d |
| children | 556d9584c65b |
comparison
equal
deleted
inserted
replaced
| 6537:9bc83fba89ac | 6538:de1f17ed4dac |
|---|---|
| 840 and the 'stanza' object, which is the stanza being considered within the current rule. Whatever value the expression returns will be converted to a string. | 840 and the 'stanza' object, which is the stanza being considered within the current rule. Whatever value the expression returns will be converted to a string. |
| 841 | 841 |
| 842 Example to limit stanzas per session type: | 842 Example to limit stanzas per session type: |
| 843 | 843 |
| 844 LIMIT: normal on $(session.type) | 844 LIMIT: normal on $(session.type) |
| 845 | |
| 846 ### Tracing | |
| 847 | |
| 848 mod_firewall has tracing functionality, to help with debugging scripts and | |
| 849 rules. | |
| 850 | |
| 851 To enable tracing for a script, add at the top: | |
| 852 | |
| 853 ``` | |
| 854 @@ trace = on | |
| 855 ``` | |
| 856 | |
| 857 All chains defined in the script will then have tracing activated. Note that | |
| 858 this has a small performance impact (in processing and in memory allocations), | |
| 859 even when the tracing functionality is not actively being used. | |
| 860 | |
| 861 You need to reload mod_firewall after enabling tracing in a script, so it will | |
| 862 pick up the change and recompile the rules. | |
| 863 | |
| 864 When tracing is enabled, you can trace all evaluations by running: | |
| 865 | |
| 866 ``` | |
| 867 prosodyctl shell firewall trace HOST | |
| 868 ``` | |
| 869 | |
| 870 Replace HOST with the name of the host/component you want to trace (obviously | |
| 871 mod_firewall must be loaded on that host). | |
| 872 | |
| 873 What is a trace? When tracing is enabled, a trace is generated each time a | |
| 874 chain runs an evaluation of a stanza. The trace records the script name, chain | |
| 875 name, the stanza that was being evaluated, and which rules/conditions matched. | |
| 876 This information is then sent to any active 'trace' commands. If no commands | |
| 877 are active, traces are discarded. | |
| 878 | |
| 879 Note that traces are per-chain and only printed when they are complete. This | |
| 880 can result in unintuitive ordering of the output when multiple chains are | |
| 881 invoked during processing of a stanza. Results of traces from "inner" chains | |
| 882 will be displayed before traces from an "outer" chain. | |
| 883 | |
| 884 #### Tagging traces | |
| 885 | |
| 886 Sometimes you only need to trace a subset of evaluations. To do this, you can | |
| 887 use the `TAG TRACE` action. This will apply a tag to the trace of the current | |
| 888 evaluation. | |
| 889 | |
| 890 For example, if you only want to trace stanzas sent to a specific JID: | |
| 891 | |
| 892 ``` | |
| 893 TO: user@example.com | |
| 894 TAG TRACE=interesting | |
| 895 ``` | |
| 896 | |
| 897 Then you can filter for this tag when you watch traces: | |
| 898 | |
| 899 ``` | |
| 900 prosodyctl shell firewall trace --tag=interesting HOST | |
| 901 ``` | |
| 902 | |
| 903 You can filter by the special tag name `untagged` to only show traces which | |
| 904 have not been tagged. | |
| 905 | |
| 906 Notes on trace tagging: | |
| 907 | |
| 908 - Traces are per chain, however tags will propagate through to future chains | |
| 909 which execute on the same event. This allows easily tracing a stanza through | |
| 910 multiple chains, for example. | |
| 911 - A trace may only have one tag. If `TAG TRACE` is used multiple times, it | |
| 912 will overwrite the tag for the current trace and any future chains which run | |
| 913 on this event/stanza. Chains (other than the current one) which already | |
| 914 began evaluation won't use the new tag. |