15467: Add note about units for byte sizes, reorganize config a bit

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <pamstutz@veritasgenetics.com>

diff --git a/doc/install/crunch2-slurm/install-dispatch.html.textile.liquid b/doc/install/crunch2-slurm/install-dispatch.html.textile.liquid
index 8ed6dc105a85463a3e995d95bbc2b2eac6daf1f8..8a4467de4e178e95745e72fa9b33a78d996667b8 100644 (file)
--- a/doc/install/crunch2-slurm/install-dispatch.html.textile.liquid
+++ b/doc/install/crunch2-slurm/install-dispatch.html.textile.liquid
@@ -31,47 +31,63 @@ On Debian-based systems:
 </code></pre>
 </notextile>
 
+h2. Configure the dispatcher (optional)
 
-h2. Configure the dispatcher
+Crunch-dispatch-slurm reads the common configuration file at @/etc/arvados/config.yml@.  The essential configuration parameters will already be set by previous install steps, so no additional configuration is required.  The following sections describe optional configuration parameters.
 
-Edit @/etc/arvados/config.yml@.
+h3(#PollPeriod). Containers.PollInterval
+
+crunch-dispatch-slurm polls the API server periodically for new containers to run.  The @PollInterval@ option controls how often this poll happens.  Set this to a string of numbers suffixed with one of the time units @ns@, @us@, @ms@, @s@, @m@, or @h@.  For example:
 
 <notextile>
-<pre><code class="userinput">Client:
-  APIHost: <b>zzzzz.arvadosapi.com</b>
-  AuthToken: <b>zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</b>
+<pre>
+Clusters:
+  zzzzz:
+    Containers:
+      <code class="userinput">PollInterval: <b>3m30s</b>
 </code></pre>
 </notextile>
 
-This is the only configuration required by crunch-dispatch-slurm.  The subsections below describe optional configuration flags you can set inside the main configuration object.
+h3(#ReserveExtraRAM). Containers.ReserveExtraRAM: Extra RAM for jobs
 
-h3(#KeepServiceURIs). Containers.SLURM.KeepServices
+Extra RAM to reserve (in bytes) on each SLURM job submitted by Arvados, which is added to the amount specified in the container's @runtime_constraints@.  If not provided, the default value is zero.  Helpful when using @-cgroup-parent-subsystem@, where @crunch-run@ and @arv-mount@ share the control group memory limit with the user process.  In this situation, at least 256MiB is recommended to accomodate each container's @crunch-run@ and @arv-mount@ processes.
 
-Override Keep service discovery with a predefined list of Keep URIs. This can be useful if the compute nodes run a local keepstore that should handle all Keep traffic. Example:
+Supports suffixes @KB@, @KiB@, @MB@, @MiB@, @GB@, @GiB@, @TB@, @TiB@, @PB@, @PiB@, @EB@, @EiB@ (where @KB@ is 10[^3^], @KiB@ is 2[^10^], @MB@ is 10[^6^], @MiB@ is 2[^20^] and so forth).
 
 <notextile>
 <pre>
 Clusters:
   zzzzz:
     Containers:
-      SLURM:
-        <span class="userinput">KeepServices:
-          00000-bi6l4-000000000000000:
-           InternalURLs:
-              "http://127.0.0.1:25107": {}</span>
-</code></pre>
+      <code class="userinput">ReserveExtraRAM: <b>256MiB</b></code>
+</pre>
 </notextile>
 
-h3(#PollPeriod). Containers.PollInterval
+h3(#MinRetryPeriod). Containers.MinRetryPeriod: Rate-limit repeated attempts to start containers
 
-crunch-dispatch-slurm polls the API server periodically for new containers to run.  The @PollInterval@ option controls how often this poll happens.  Set this to a string of numbers suffixed with one of the time units @ns@, @us@, @ms@, @s@, @m@, or @h@.  For example:
+If SLURM is unable to run a container, the dispatcher will submit it again after the next PollPeriod. If PollPeriod is very short, this can be excessive. If MinRetryPeriod is set, the dispatcher will avoid submitting the same container to SLURM more than once in the given time span.
 
 <notextile>
 <pre>
 Clusters:
   zzzzz:
     Containers:
-      <code class="userinput">PollInterval: <b>3m30s</b>
+      <code class="userinput">MinRetryPeriod: <b>30s</b></code>
+</pre>
+</notextile>
+
+h3(#KeepServiceURIs). Containers.SLURM.SbatchEnvironmentVariables
+
+Some Arvados installations run a local keepstore on each compute node to handle all Keep traffic.  To override Keep service discovery and access the local keep server instead of the global servers, set ARVADOS_KEEP_SERVICES in SbatchEnvironmentVariables:
+
+<notextile>
+<pre>
+Clusters:
+  zzzzz:
+    Containers:
+      SLURM:
+        <span class="userinput">SbatchEnvironmentVariables:
+              "http://127.0.0.1:25107": {}</span>
 </code></pre>
 </notextile>
 
@@ -149,32 +165,6 @@ Clusters:
 </pre>
 </notextile>
 
-h3(#MinRetryPeriod). Containers.MinRetryPeriod: Rate-limit repeated attempts to start containers
-
-If SLURM is unable to run a container, the dispatcher will submit it again after the next PollPeriod. If PollPeriod is very short, this can be excessive. If MinRetryPeriod is set, the dispatcher will avoid submitting the same container to SLURM more than once in the given time span.
-
-<notextile>
-<pre>
-Clusters:
-  zzzzz:
-    Containers:
-      <code class="userinput">MinRetryPeriod: <b>30s</b></code>
-</pre>
-</notextile>
-
-h3(#ReserveExtraRAM). Containers.ReserveExtraRAM: Extra RAM for jobs
-
-Extra RAM to reserve (in bytes) on each SLURM job submitted by Arvados, which is added to the amount specified in the container's @runtime_constraints@.  If not provided, the default value is zero.  Helpful when using @-cgroup-parent-subsystem@, where @crunch-run@ and @arv-mount@ share the control group memory limit with the user process.  In this situation, at least 256MiB is recommended to accomodate each container's @crunch-run@ and @arv-mount@ processes.
-
-<notextile>
-<pre>
-Clusters:
-  zzzzz:
-    Containers:
-      <code class="userinput">ReserveExtraRAM: <b>256MiB</b></code>
-</pre>
-</notextile>
-
 h2. Restart the dispatcher
 
 {% include 'notebox_begin' %}