Updated docs

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -244,12 +244,12 @@ to your entry-point.
     listen_on = 0.0.0.0
     port = 4242
 
-    # On publicly available interfaces, it can be
+    # On publicly available interfaces, it is
-    # a good idea to configure sensible announce
+    # essential to configure sensible announce
     # rate targets.
     announce_rate_target = 3600
     announce_rate_penalty = 3600
-    announce_rate_grace = 12
+    announce_rate_grace = 6
 
 If instead you want to make a private entry-point from the Internet, you can use the
 :ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.

docs/manual/_sources/interfaces.rst.txt

@@ -1293,11 +1293,14 @@ Announce Rate Control
 =====================
 
 The built-in announce control mechanisms and the default ``announce_cap``
-option described above are sufficient most of the time, but in some cases, especially on fast
+option described above are sufficient most of the time, but in some cases,
-interfaces, it may be useful to control the target announce rate. Using the
+especially on fast interfaces, or when connecting to large public networks,
-``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
+it may be useful to control the target announce rate.
-options, this can be done on a per-interface basis, and moderates the *rate at
+
-which received announces are re-broadcasted to other interfaces*.
+Using the ``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
+options, this can be done on a per-interface basis, or by setting instance-wide defaults.
+When configured, this moderates the *rate at which received announces are
+re-broadcasted to other interfaces*.
 
  * | The ``announce_rate_target`` option sets the minimum amount of time,
      in seconds, that should pass between received announces, for any one
@@ -1315,20 +1318,30 @@ which received announces are re-broadcasted to other interfaces*.
      destination in question will only have its announces propagated every
      3 hours, until it lowers its actual announce rate to within the target.
 
+You can also configure default announce rate parameters for all interfaces that
+do not have these parameters set explicitly by setting the ``default_ar_target``
+``default_ar_penalty`` and ``default_ar_grace`` options in the ``[reticulum]``
+section of the configuration file. If any of these options are set, they will
+automatically be applied to any interface if transport is enabled, and the
+interface does not have the parameters set explicitly.
+
+For auto-connected interfaces, sensible default announce rate control parameters
+will **always** be set, even if the defaults are not configured explicitly, but
+if you set the defaults, auto-connected interfaces will adhere to these as well.
+
 These mechanisms, in conjunction with the ``annouce_cap`` mechanisms mentioned
 above means that it is essential to select a balanced announce strategy for
 your destinations. The more balanced you can make this decision, the easier
-it will be for your destinations to make it into slower networks that many hops
+it will be for your destinations to make it into slower networks, or networks that
-away. Or you can prioritise only reaching high-capacity networks with more frequent
+are many hops away.
-announces.
 
-Current statistics and information about announce rates can be viewed using the
+Statistics and information about announce rates can be viewed using the
-``rnpath -r`` command.
+``rnpath -r`` and ``rnstatus -A`` commands.
 
 It is important to note that there is no one right or wrong way to set up announce
 rates. Slower networks will naturally tend towards using less frequent announces to
 conserve bandwidth, while very fast networks can support applications that
-need very frequent announces. Reticulum implements these mechanisms to ensure
+need more frequent announces. Reticulum implements these mechanisms to ensure
 that a large span of network types can seamlessly *co-exist* and interconnect.
 
 .. _interfaces-ingress-control:

docs/manual/gettingstartedfast.html

@@ -446,12 +446,12 @@ to your entry-point.</p>
 <span class="w">  </span><span class="na">listen_on</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.0.0.0</span>
 <span class="w">  </span><span class="na">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">4242</span>
 
-<span class="w">  </span><span class="c1"># On publicly available interfaces, it can be</span>
+<span class="w">  </span><span class="c1"># On publicly available interfaces, it is</span>
-<span class="w">  </span><span class="c1"># a good idea to configure sensible announce</span>
+<span class="w">  </span><span class="c1"># essential to configure sensible announce</span>
 <span class="w">  </span><span class="c1"># rate targets.</span>
 <span class="w">  </span><span class="na">announce_rate_target</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span>
 <span class="w">  </span><span class="na">announce_rate_penalty</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">3600</span>
-<span class="w">  </span><span class="na">announce_rate_grace</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">12</span>
+<span class="w">  </span><span class="na">announce_rate_grace</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">6</span>
 </pre></div>
 </div>
 <p>If instead you want to make a private entry-point from the Internet, you can use the

docs/manual/interfaces.html

@@ -1458,11 +1458,13 @@ please see the <a class="reference internal" href="understanding.html#understand
 <section id="announce-rate-control">
 <span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Link to this heading">¶</a></h2>
 <p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code>
-option described above are sufficient most of the time, but in some cases, especially on fast
+option described above are sufficient most of the time, but in some cases,
-interfaces, it may be useful to control the target announce rate. Using the
+especially on fast interfaces, or when connecting to large public networks,
-<code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code>, <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code>
+it may be useful to control the target announce rate.</p>
-options, this can be done on a per-interface basis, and moderates the <em>rate at
+<p>Using the <code class="docutils literal notranslate"><span class="pre">announce_rate_target</span></code>, <code class="docutils literal notranslate"><span class="pre">announce_rate_grace</span></code> and <code class="docutils literal notranslate"><span class="pre">announce_rate_penalty</span></code>
-which received announces are re-broadcasted to other interfaces</em>.</p>
+options, this can be done on a per-interface basis, or by setting instance-wide defaults.
+When configured, this moderates the <em>rate at which received announces are
+re-broadcasted to other interfaces</em>.</p>
 <blockquote>
 <div><ul>
 <li><div class="line-block">
@@ -1489,18 +1491,26 @@ destination in question will only have its announces propagated every
 </li>
 </ul>
 </div></blockquote>
+<p>You can also configure default announce rate parameters for all interfaces that
+do not have these parameters set explicitly by setting the <code class="docutils literal notranslate"><span class="pre">default_ar_target</span></code>
+<code class="docutils literal notranslate"><span class="pre">default_ar_penalty</span></code> and <code class="docutils literal notranslate"><span class="pre">default_ar_grace</span></code> options in the <code class="docutils literal notranslate"><span class="pre">[reticulum]</span></code>
+section of the configuration file. If any of these options are set, they will
+automatically be applied to any interface if transport is enabled, and the
+interface does not have the parameters set explicitly.</p>
+<p>For auto-connected interfaces, sensible default announce rate control parameters
+will <strong>always</strong> be set, even if the defaults are not configured explicitly, but
+if you set the defaults, auto-connected interfaces will adhere to these as well.</p>
 <p>These mechanisms, in conjunction with the <code class="docutils literal notranslate"><span class="pre">annouce_cap</span></code> mechanisms mentioned
 above means that it is essential to select a balanced announce strategy for
 your destinations. The more balanced you can make this decision, the easier
-it will be for your destinations to make it into slower networks that many hops
+it will be for your destinations to make it into slower networks, or networks that
-away. Or you can prioritise only reaching high-capacity networks with more frequent
+are many hops away.</p>
-announces.</p>
+<p>Statistics and information about announce rates can be viewed using the
-<p>Current statistics and information about announce rates can be viewed using the
+<code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-r</span></code> and <code class="docutils literal notranslate"><span class="pre">rnstatus</span> <span class="pre">-A</span></code> commands.</p>
-<code class="docutils literal notranslate"><span class="pre">rnpath</span> <span class="pre">-r</span></code> command.</p>
 <p>It is important to note that there is no one right or wrong way to set up announce
 rates. Slower networks will naturally tend towards using less frequent announces to
 conserve bandwidth, while very fast networks can support applications that
-need very frequent announces. Reticulum implements these mechanisms to ensure
+need more frequent announces. Reticulum implements these mechanisms to ensure
 that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p>
 </section>
 <section id="new-destination-rate-limiting">

docs/source/gettingstartedfast.rst

@@ -244,12 +244,12 @@ to your entry-point.
     listen_on = 0.0.0.0
     port = 4242
 
-    # On publicly available interfaces, it can be
+    # On publicly available interfaces, it is
-    # a good idea to configure sensible announce
+    # essential to configure sensible announce
     # rate targets.
     announce_rate_target = 3600
     announce_rate_penalty = 3600
-    announce_rate_grace = 12
+    announce_rate_grace = 6
 
 If instead you want to make a private entry-point from the Internet, you can use the
 :ref:`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.

docs/source/interfaces.rst

@@ -1293,11 +1293,14 @@ Announce Rate Control
 =====================
 
 The built-in announce control mechanisms and the default ``announce_cap``
-option described above are sufficient most of the time, but in some cases, especially on fast
+option described above are sufficient most of the time, but in some cases,
-interfaces, it may be useful to control the target announce rate. Using the
+especially on fast interfaces, or when connecting to large public networks,
-``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
+it may be useful to control the target announce rate.
-options, this can be done on a per-interface basis, and moderates the *rate at
+
-which received announces are re-broadcasted to other interfaces*.
+Using the ``announce_rate_target``, ``announce_rate_grace`` and ``announce_rate_penalty``
+options, this can be done on a per-interface basis, or by setting instance-wide defaults.
+When configured, this moderates the *rate at which received announces are
+re-broadcasted to other interfaces*.
 
  * | The ``announce_rate_target`` option sets the minimum amount of time,
      in seconds, that should pass between received announces, for any one
@@ -1315,20 +1318,37 @@ which received announces are re-broadcasted to other interfaces*.
      destination in question will only have its announces propagated every
      3 hours, until it lowers its actual announce rate to within the target.
 
+You can also configure default announce rate parameters for all interfaces that
+do not have these parameters set explicitly by setting the ``default_ar_target``
+``default_ar_penalty`` and ``default_ar_grace`` options in the ``[reticulum]``
+section of the configuration file. If any of these options are set, they will
+automatically be applied to any interface if transport is enabled, and the
+interface does not have the parameters set explicitly.
+
+For auto-connected interfaces, sensible default announce rate control parameters
+will **always** be set, even if the defaults are not configured explicitly, but
+if you set the defaults, auto-connected interfaces will adhere to these as well.
+
 These mechanisms, in conjunction with the ``annouce_cap`` mechanisms mentioned
 above means that it is essential to select a balanced announce strategy for
 your destinations. The more balanced you can make this decision, the easier
-it will be for your destinations to make it into slower networks that many hops
+it will be for your destinations to make it into slower networks, or networks that
-away. Or you can prioritise only reaching high-capacity networks with more frequent
+are many hops away.
-announces.
 
-Current statistics and information about announce rates can be viewed using the
+Statistics and information about announce rates can be viewed using the
-``rnpath -r`` command.
+``rnpath -r`` and ``rnstatus -A`` commands.
 
-It is important to note that there is no one right or wrong way to set up announce
+It is important to note, that while there is no one right or wrong way to set up announce
-rates. Slower networks will naturally tend towards using less frequent announces to
+rates, it should generally not be necessary to announce any kind of destination.
+more often than once every few hours. Most applications can announce simply when
+the application starts, and then only once every 6 hours or so.
+
+If you're designing an application where you think you need to annonuce more
+often than once an hour, you're most likely doing something wrong.
+
+Slower networks will naturally tend towards using less frequent announces to
 conserve bandwidth, while very fast networks can support applications that
-need very frequent announces. Reticulum implements these mechanisms to ensure
+need more frequent announces. Reticulum implements these mechanisms to ensure
 that a large span of network types can seamlessly *co-exist* and interconnect.
 
 .. _interfaces-ingress-control: