From 221f4909b518cebbf5e3135887741218865cfb84 Mon Sep 17 00:00:00 2001
From: Tom Eastep <teastep@shorewall.net>
Date: Tue, 29 Jan 2013 09:12:04 -0800
Subject: [PATCH] Document perl_action_helper

Signed-off-by: Tom Eastep <teastep@shorewall.net>
---
 docs/Actions.xml | 65 ++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 5 deletions(-)

diff --git a/docs/Actions.xml b/docs/Actions.xml
index addf7e410..dea6b284e 100644
--- a/docs/Actions.xml
+++ b/docs/Actions.xml
@@ -30,6 +30,8 @@
 
       <year>2012</year>
 
+      <year>2013</year>
+
       <holder>Thomas M. Eastep</holder>
     </copyright>
 
@@ -684,7 +686,7 @@ bar:debug</programlisting>
 
     <para>The Shorewall compiler provides a set of services that are available
     to Perl code embedded in an action file. These services are not available
-    in in-line actions.</para>
+    in in-line actions when running Shorewall 4.5.12 or earlier.</para>
 
     <variablelist>
       <varlistentry>
@@ -744,7 +746,9 @@ bar:debug</programlisting>
         [, <replaceable>$expandports</replaceable> ] )</term>
 
         <listitem>
-          <para>This function adds a rule to a chain. Arguments are:</para>
+          <para>This function adds a rule to a chain. As of Shoreall 4.5.13,
+          it is deprecated in favor of Shorewall::Rules::perl_action_helper().
+          Arguments are:</para>
 
           <variablelist>
             <varlistentry>
@@ -774,6 +778,11 @@ bar:debug</programlisting>
               </listitem>
             </varlistentry>
           </variablelist>
+
+          <warning>
+            <para>Do not call this function in a inline action. Use
+            perl_action_helper() instead (see below).</para>
+          </warning>
         </listitem>
       </varlistentry>
 
@@ -788,8 +797,9 @@ bar:debug</programlisting>
         <replaceable>$matches</replaceable> )</term>
 
         <listitem>
-          <para>This function adds a logging rule to a chain. Arguments
-          are:</para>
+          <para>This function adds a logging rule to a chain. As of Shoreall
+          4.5.13, it is deprecated in favor of
+          Shorewall::Rules::perl_action_helper(). Arguments are:</para>
 
           <variablelist>
             <varlistentry>
@@ -875,7 +885,7 @@ bar:debug</programlisting>
 
       <varlistentry>
         <term>Shorewall::Chains::allow::optimize(
-        <replaceable>chainref</replaceable> )</term>
+        <replaceable>$chainref</replaceable> )</term>
 
         <listitem>
           <para>This allows the passed action chain to be optimized away
@@ -884,6 +894,51 @@ bar:debug</programlisting>
           from get_action_chain() described above.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+        <term>Shorewall::Rules::perl_action_helper( $target, $matches )</term>
+
+        <listitem>
+          <para>This function adds a rule to the current chain. For a regular
+          action, the chain will be an action chain; for an inline action, the
+          chain is determined by the invoking rule.</para>
+
+          <para>To use this function, you must include:</para>
+
+          <simplelist>
+            <member><emphasis role="bold">use
+            Shorewall::Rules;</emphasis></member>
+          </simplelist>
+
+          <para>Arguments are:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term>$target</term>
+
+              <listitem>
+                <para>The target of the rule. Legal values are anything that
+                can appear in the TARGET column of in an action body and may
+                include log level, tag, and parameters.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>$matches</term>
+
+              <listitem>
+                <para>ip[6]tables matches to be included in the rule. When
+                called in an inline action, these matches are augmented by
+                matches generated by the invoking rule.</para>
+
+                <important>
+                  <para>The matches must end with a space character.</para>
+                </important>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </listitem>
+      </varlistentry>
     </variablelist>
 
     <para>For an example of using these services, look at the standard action