Skip to content

Commit

Permalink
qrouting: Document the recently added logic
Browse files Browse the repository at this point in the history
  • Loading branch information
@liviuchircu
liviuchircu committed Feb 12, 2020
1 parent 5990fce commit 9765dce
Show file tree
Hide file tree
Showing 2 changed files with 204 additions and 6 deletions.
206 changes: 202 additions & 4 deletions modules/qrouting/doc/qrouting_admin.xml
View file
Expand Up @@ -72,6 +72,8 @@
</para>
</section>

<!-- ============================= PARAM ================================ -->

<section id="dependencies" xreflabel="Dependencies">
<title>Dependencies</title>
<section id="deps_modules" xreflabel="OpenSIPS Module Dependencies">
Expand Down Expand Up @@ -158,8 +160,115 @@ modparam("qrouting", "sampling_interval", 5)
</programlisting>
</example>
</section>

<section id="param_event_bad_dst_threshold" xreflabel="event_bad_dst_threshold">
<title><varname>event_bad_dst_threshold</varname> (integer)</title>
<para>
The minimally accepted quality of a gateway. If a destination (i.e.
prefix + gateway combination) receives a score below this threshold,
the E_QROUTING_BAD_DST event will be triggered.
</para>
<para>
<emphasis>
Default value is <emphasis role='bold'>5</emphasis> (all stats are
allowed to hit the WARN threshold simultaneously)
</emphasis>
</para>
<example>
<title>Setting the <varname>event_bad_dst_threshold</varname> parameter</title>
<programlisting format="linespecific">

modparam("qrouting", "event_bad_dst_threshold", 4)
</programlisting>
</example>
</section>

</section>

<!-- ============================= FUNC ================================ -->

<section id="exported_functions" xreflabel="exported_functions">
<title>Exported Functions</title>

<section id="func_qr_disable_dst" xreflabel="qr_disable_dst()">
<title>
<function moreinfo="none">qr_disable_dst(rule_id, dst_name, [part])</function>
</title>
<para>
Within a given routing rule, temporarily remove the given gateway or
carrier from routing, until they are re-enabled via
<xref linkend="func_qr_enable_dst"/> or <xref linkend="mi_qr_enable_dst"/>.
The removal effect will be lost on an OpenSIPS restart.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>rule_id (integer)</emphasis> - database id of the
drouting rule
</para></listitem>
<listitem><para>
<emphasis>dst_name (string)</emphasis> - gateway or carrier
to disable
</para></listitem>
<listitem><para>
<emphasis>part (string, optional)</emphasis> - drouting partition
</para></listitem>
</itemizedlist>
<para>
This function can be used from any route.
</para>
<example>
<title><function>qr_disable_dst()</function> usage</title>
<programlisting format="linespecific">

# the signaling quality for @rule_id through @dst_name is degrading, remove it!
event_route [E_QROUTING_BAD_DST]
{
qr_disable_dst($param(rule_id), $param(dst_name), $param(partition));
}
</programlisting>
</example>
</section>

<section id="func_qr_enable_dst" xreflabel="qr_enable_dst()">
<title>
<function moreinfo="none">qr_enable_dst(rule_id, dst_name, [part])</function>
</title>
<para>
Within a given routing rule, re-introduce the given gateway or
carrier into the routing process.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>rule_id (integer)</emphasis> - database id of the
drouting rule
</para></listitem>
<listitem><para>
<emphasis>dst_name (string)</emphasis> - gateway or carrier
to disable
</para></listitem>
<listitem><para>
<emphasis>part (string, optional)</emphasis> - drouting partition
</para></listitem>
</itemizedlist>
<para>
This function can be used from any route.
</para>
<example>
<title><function>qr_enable_dst()</function> usage</title>
<programlisting format="linespecific">

# the ban has expired, let's re-enable this gateway and see how it behaves
qr_enable_dst($param(rule_id), $param(dst_name), $param(partition));
</programlisting>
</example>
</section>

</section>

<!-- ================================ MI ================================= -->

<section id="exported_mi_functions" xreflabel="Exported MI Functions">
<title>Exported MI Functions</title>

Expand Down Expand Up @@ -190,16 +299,16 @@ opensips-cli -x mi qr_reload
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>partition_name (optional)</emphasis> - a specific
<emphasis>partition (optional)</emphasis> - a specific
drouting partition to list statistics for
</para></listitem>
<listitem><para>
<emphasis>rule_id (optional)</emphasis> - a specific drouting
rule ID to list statistics for
rule database id to list statistics for
</para></listitem>
<listitem><para>
<emphasis>dst_id (optional)</emphasis> - a specific gateway or
carrier ID to list statistics for
<emphasis>dst_name (optional)</emphasis> - a specific gateway or
carrier name to list statistics for
</para></listitem>
</itemizedlist>
<para>
Expand All @@ -215,6 +324,95 @@ opensips-cli -x mi qr_status pstn MY-CARR-7
</programlisting>
</section>

<section id="mi_qr_disable_dst" xreflabel="qr_disable_dst">
<title><function moreinfo="none">qr_disable_dst</function></title>

<para>
Within a given routing rule, temporarily remove the given gateway or
carrier from routing, until they are re-enabled manually. The removal
effect will be lost on an OpenSIPS restart.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>partition (optional)</emphasis> - drouting partition
</para></listitem>
<listitem><para>
<emphasis>rule_id</emphasis> - database id of the drouting rule
</para></listitem>
<listitem><para>
<emphasis>dst_name</emphasis> - gateway or carrier to disable
</para></listitem>
</itemizedlist>
<para>
MI FIFO Command Format:
</para>

<programlisting format="linespecific">

opensips-cli -x mi qr_disable_dst 14 MY-CARR-7
opensips-cli -x mi qr_disable_dst pstn 81 MY-GW-3
</programlisting>
</section>

<section id="mi_qr_enable_dst" xreflabel="qr_enable_dst">
<title><function moreinfo="none">qr_enable_dst</function></title>

<para>
Within a given routing rule, re-introduce the given gateway or
carrier into the routing process.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>partition (optional)</emphasis> - drouting partition
</para></listitem>
<listitem><para>
<emphasis>rule_id</emphasis> - database id of the drouting rule
</para></listitem>
<listitem><para>
<emphasis>dst_name</emphasis> - gateway or carrier to enable
</para></listitem>
</itemizedlist>
<para>
MI FIFO Command Format:
</para>

<programlisting format="linespecific">

opensips-cli -x mi qr_enable_dst 14 MY-CARR-7
opensips-cli -x mi qr_enable_dst pstn 81 MY-GW-3
</programlisting>
</section>

</section>

<!-- ============================= EVENT ================================ -->

<section id="exported_events" xreflabel="Exported Events">
<title>Exported Events</title>
<section id="event_E_QROUTING_BAD_DST" xreflabel="E_QROUTING_BAD_DST">
<title>
<function moreinfo="none">E_QROUTING_BAD_DST</function>
</title>
<para>
This event may be raised during routing, asynchronously, whenever a
gateway's score falls below <xref linkend="param_event_bad_dst_threshold"/>.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem><para>
<emphasis>partition</emphasis> - drouting partition name
</para></listitem>
<listitem><para>
<emphasis>rule_id</emphasis> - database id of the drouting rule
</para></listitem>
<listitem><para>
<emphasis>dst_name</emphasis> - name of the concerned gateway or carrier
</para></listitem>
</itemizedlist>
</section>

</section>

</chapter>
4 changes: 2 additions & 2 deletions modules/qrouting/qrouting.c
View file
Expand Up @@ -96,15 +96,15 @@ static cmd_export_t cmds[] = {
{CMD_PARAM_STR|CMD_PARAM_OPT, NULL, NULL},
{0, 0, 0}
},
REQUEST_ROUTE|FAILURE_ROUTE|LOCAL_ROUTE|BRANCH_ROUTE
ALL_ROUTES
},
{"qr_enable_dst", (cmd_function)w_qr_enable_dst,
{ {CMD_PARAM_INT, NULL, NULL},
{CMD_PARAM_STR, NULL, NULL},
{CMD_PARAM_STR|CMD_PARAM_OPT, NULL, NULL},
{0, 0, 0}
},
REQUEST_ROUTE|FAILURE_ROUTE|LOCAL_ROUTE|BRANCH_ROUTE
ALL_ROUTES
},
{0,0,{{0,0,0}},0}
};
Expand Down

0 comments on commit 9765dce

Please sign in to comment.