doc/install/install-keep-balance.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install Keep-balance
   5 ...
   6
   7 Keep-balance deletes unreferenced and overreplicated blocks from Keep servers, makes additional copies of underreplicated blocks, and moves blocks into optimal locations as needed (e.g., after adding new servers).
   8
   9 {% include 'notebox_begin' %}
  10
  11 If you are installing keep-balance on an existing system with valuable data, you can run keep-balance in "dry run" mode first and review its logs as a precaution. To do this, use the @keepstore -never-delete=true@ flag or remove the @-commit-trash@ flag from your keep-balance startup script.
  12
  13 {% include 'notebox_end' %}
  14
  15 h2. Install keep-balance
  16
  17 Keep-balance can be installed anywhere with network access to Keep services. Typically it runs on the same host as keepproxy.
  18
  19 On Debian-based systems:
  20
  21 <notextile>
  22 <pre><code>~$ <span class="userinput">sudo apt-get install keep-balance</span>
  23 </code></pre>
  24 </notextile>
  25
  26 On Red Hat-based systems:
  27
  28 <notextile>
  29 <pre><code>~$ <span class="userinput">sudo yum install keep-balance</span>
  30 </code></pre>
  31 </notextile>
  32
  33 Verify that @keep-balance@ is functional:
  34
  35 <notextile>
  36 <pre><code>~$ <span class="userinput">keep-balance -h</span>
  37 ...
  38 Usage: keep-balance [options]
  39
  40 Options:
  41   -commit-pulls
  42         send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
  43   -commit-trash
  44         send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
  45 ...
  46 </code></pre>
  47 </notextile>
  48
  49 h3. Create a keep-balance token
  50
  51 Create an Arvados superuser token for use by keep-balance. *On the API server*, run:
  52
  53 <notextile>
  54 <pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  55 apiserver:/var/www/arvados-api/current$ <span class="userinput">sudo -u <b>webserver-user</b> RAILS_ENV=production bundle exec script/create_superuser_token.rb</span>
  56 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  57 </code></pre>
  58 </notextile>
  59
  60 h3. Create a configuration file
  61
  62 On the host running keep-balance, create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated in the previous step.  Follow this YAML format:
  63
  64 <notextile>
  65 <pre><code>Client:
  66   APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
  67   AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  68 KeepServiceTypes:
  69   - disk
  70 RunPeriod: 10m
  71 CollectionBatchSize: 100000
  72 CollectionBuffers: 1000
  73 </code></pre>
  74 </notextile>
  75
  76 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
  77
  78 <notextile>
  79 <pre><code>Client:
  80   <span class="userinput">Insecure: true</span>
  81   APIHost: ...
  82 </code></pre>
  83 </notextile>
  84
  85 h3. Start the service (option 1: systemd)
  86
  87 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
  88
  89 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
  90
  91 <notextile>
  92 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
  93 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
  94 &#x25cf; keep-balance.service - Arvados Keep Balance
  95    Loaded: loaded (/lib/systemd/system/keep-balance.service; enabled)
  96    Active: active (running) since Sat 2017-02-14 18:46:01 UTC; 3 days ago
  97      Docs: https://doc.arvados.org/
  98  Main PID: 541 (keep-balance)
  99    CGroup: /system.slice/keep-balance.service
 100            └─541 /usr/bin/keep-balance -commit-pulls -commit-trash
 101
 102 Feb 14 18:46:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 103 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 Run: start
 104 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 105 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 106 </code></pre>
 107 </notextile>
 108
 109 h3(#runit). Start the service (option 2: runit)
 110
 111 Install runit to supervise the keep-balance daemon.  {% include 'install_runit' %}
 112
 113 Create a supervised service.
 114
 115 <notextile>
 116 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/keep-balance</span>
 117 ~$ <span class="userinput">cd /etc/service/keep-balance</span>
 118 ~$ <span class="userinput">sudo mkdir log log/main</span>
 119 ~$ <span class="userinput">printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run</span>
 120 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
 121 ~$ <span class="userinput">sudo chmod +x run log/run</span>
 122 ~$ <span class="userinput">sudo sv exit .</span>
 123 ~$ <span class="userinput">cd -</span>
 124 </code></pre>
 125 </notextile>
 126
 127 Use @sv stat@ and check the log file to verify the service is running.
 128
 129 <notextile>
 130 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/keep-balance</span>
 131 run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
 132 ~$ <span class="userinput">tail /etc/service/keep-balance/log/main/current</span>
 133 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
 134 2017/02/14 18:56:01 Run: start
 135 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
 136 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
 137 </code></pre>
 138 </notextile>
 139
 140 h2. Enable delete operations on keepstore volumes
 141
 142 Ensure your keepstore services have the "delete" operation enabled. If it is disabled (which is the default), unneeded blocks will be identified by keep-balance, but will never be deleted from the underlying storage devices.
 143
 144 Add the @-never-delete=false@ command line flag to your keepstore run script:
 145
 146 <notextile>
 147 <pre><code>keepstore <span class="userinput">-never-delete=false</span> -volume=...
 148 </code></pre>
 149 </notextile>
 150
 151 {% comment %}
 152 // To replace the above section when the keepstore page recommends YAML...
 153
 154 Use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
 155
 156 <notextile>
 157 <pre><code>...
 158 BlobSigningKeyFile: /etc/keepstore/blob-signing.key
 159 <span class="userinput">EnableDelete: true</span>
 160 Listen: :25107
 161 ...
 162 </code></pre>
 163 </notextile>
 164 {% endcomment %}