doc/install/config.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Configuration file
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 The configuration file is normally found at @/etc/arvados/config.yml@.  This configuration file should be kept in sync across every node in the cluster, except compute nodes (which usually do not require config.yml).  We recommend using a devops configuration management tool such as Puppet to synchronize the config file.
  13
  14 h2. Syntax
  15
  16 The configuration file is in "YAML":https://yaml.org/ format.  This is a block syntax where indentation is significant (similar to Python).  By convention we use two space indent.  The first line of the file is always "Clusters:", underneath it at the first indent level is the cluster id.  All the actual cluster configuration comes under the cluster id.  This means all configuration parameters are indented by at least two levels (four spaces).  Comments start with @#@ .  Example
  17
  18 <pre>
  19 Clusters:                         # Clusters block, everything else is listed under this
  20   abcde:                          # Cluster ID
  21     ExampleConfigKey: "fghijk"    # An example configuration string for cluster 'abcde'
  22     ExampleConfigGroup:           # A group of keys
  23       ExampleDurationConfig: 12s  # Example duration
  24       ExampleSizeConfig: 99KiB    # Example with a size suffix
  25 </pre>
  26
  27 Each configuration group may only appear once.  When a configuration key is within a config group, it will be written with the group name leading, for example @ExampleConfigGroup.ExampleSizeConfig@.
  28
  29 Duration suffixes are s=seconds, m=minutes or h=hours.
  30
  31 Size suffixes are K=10 ^3^, Ki=2 ^10^ , M=10 ^6^, Mi=2 ^20^, G=10 ^9^, Gi=2 ^30^, T=10 ^12^, Ti=2 ^40^, P=10 ^15^, Pi=2 ^50^, E=10 ^18^, Ei=2 ^60^.  You can optionally follow with a "B" (eg "MB" or "MiB") for readability (it does not affect the units.)
  32
  33 h2. Essential Configuration
  34
  35 @SystemRootToken@ is used by Arvados system services to authenticate as the system (root) user when communicating with the API server.
  36
  37 @ManagementToken@ is used to authenticate access to system metrics.
  38
  39 @API.RailsSessionSecretToken@ is required by the API server.
  40
  41 @Collections.BlobSigningKey@ is used to construct blob signatures, as part of storage layer access control.
  42
  43 You can generate a random token for each of these items at the command line like this:
  44
  45 <notextile>
  46 <pre><code>~$ <span class="userinput">tr -dc 0-9a-zA-Z &lt;/dev/urandom | head -c40; echo</span>
  47 </code></pre>
  48 </notextile>
  49
  50 Sample configuration file fragment.  Fill in each configuration item with the tokens you generate.
  51
  52 <pre>
  53 Clusters:
  54   abcde:
  55     SystemRootToken: "$system_root_token"
  56     ManagementToken: "$management_token"
  57     API:
  58       RailsSessionSecretToken: "$secret_token"
  59     Collections:
  60       BlobSigningKey: "$blob_signing_key"
  61 </pre>
  62
  63 h2. Services
  64
  65 The @Services@ section of the configuration helps Arvados components contact one another.
  66
  67 Each service has one or more @InternalURLs@ and an @ExternalURL@.
  68
  69 The @InternalURLs@ describe where the service actually runs.
  70
  71 The @ExternalURL@ is how clients contact the service.
  72
  73 <pre>
  74 Clusters:
  75   abcde:
  76     Services:
  77       Controller:
  78         ExternalURL: "https://abcde.example.com"
  79         InternalURLs:
  80           "http://abcde.example.com:8000": {}
  81       RailsAPI:
  82         # Does not have an ExternalURL
  83         InternalURLs:
  84           "http://abcde.example.com:8001": {}
  85
  86 </pre>