3 navsection: installguide
4 title: Install Keep-balance
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).
10 h2. Install keep-balance
12 Keep-balance can be installed anywhere with access to Keep services. Typically it runs on the same host as keepproxy.
14 On Debian-based systems:
17 <pre><code>~$ <span class="userinput">sudo apt-get install keep-balance</span>
21 On Red Hat-based systems:
24 <pre><code>~$ <span class="userinput">sudo yum install keep-balance</span>
28 Verify that @keep-balance@ is functional:
31 <pre><code>~$ <span class="userinput">keep-balance -h</span>
33 Usage: keep-balance [options]
37 send pull requests (make more replicas of blocks that are underreplicated or are not in optimal rendezvous probe order)
39 send trash requests (delete unreferenced old blocks, and excess replicas of overreplicated blocks)
44 h3. Create a keep-balance token
46 Create a privileged Arvados API token for use by keep-balance. *On the API server*, run:
49 <pre><code>apiserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
50 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>
51 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
55 h3. Create a configuration file
57 Create @/etc/arvados/keep-balance/keep-balance.yml@ using the token you generated in the previous step. Follow this YAML format:
61 APIHost: <span class="userinput">uuid_prefix.your.domain</span>:443
62 AuthToken: zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
66 CollectionBatchSize: 100000
67 CollectionBuffers: 1000
71 If your API server's SSL certificate is not signed by a recognized CA, add the @Insecure@ option to the @Client@ section:
75 <span class="userinput">Insecure: true</span>
80 h3. Start the service (option 1: systemd)
82 If your system does not use systemd, skip this section and follow the "runit instructions":#runit instead.
84 If your system uses systemd, the keep-balance service should already be set up. Start it and check its status:
87 <pre><code>~$ <span class="userinput">sudo systemctl restart keep-balance</span>
88 ~$ <span class="userinput">sudo systemctl status keep-balance</span>
89 ● keep-balance.service - Arvados Keep Balance
90 Loaded: loaded (/lib/systemd/system/keep-balance.service; enabled)
91 Active: active (running) since Sat 2017-02-14 18:46:01 UTC; 3 days ago
92 Docs: https://doc.arvados.org/
93 Main PID: 541 (keep-balance)
94 CGroup: /system.slice/keep-balance.service
95 └─541 /usr/bin/keep-balance -commit-pulls -commit-trash
97 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
98 Feb 14 18:56:01 zzzzz.arvadosapi.com keep-balance[541]: 2017/02/14 18:56:01 Run: start
99 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"
100 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
104 h3(#runit). Start the service (option 2: runit)
106 Install runit to supervise the keep-balance daemon. {% include 'install_runit' %}
108 Create a supervised service.
111 <pre><code>~$ <span class="userinput">sudo mkdir /etc/service/keep-balance</span>
112 ~$ <span class="userinput">cd /etc/service/keep-balance</span>
113 ~$ <span class="userinput">sudo mkdir log log/main</span>
114 ~$ <span class="userinput">printf '#!/bin/sh\nexec keep-balance -commit-pulls -commit-trash 2>&1\n' | sudo tee run</span>
115 ~$ <span class="userinput">printf '#!/bin/sh\nexec svlogd main\n' | sudo tee log/run</span>
116 ~$ <span class="userinput">sudo chmod +x run log/run</span>
117 ~$ <span class="userinput">sudo sv exit .</span>
118 ~$ <span class="userinput">cd -</span>
122 Use @sv stat@ and check the log file to verify the service is running.
125 <pre><code>~$ <span class="userinput">sudo sv stat /etc/service/keep-balance</span>
126 run: /etc/service/keep-balance: (pid 12520) 2s; run: log: (pid 12519) 2s
127 ~$ <span class="userinput">tail /etc/service/keep-balance/log/main/current</span>
128 2017/02/14 18:46:01 starting up: will scan every 10m0s and on SIGUSR1
129 2017/02/14 18:56:01 Run: start
130 2017/02/14 18:56:01 skipping zzzzz-bi6l4-rbtrws2jxul6i4t with service type "proxy"
131 2017/02/14 18:56:01 clearing existing trash lists, in case the new rendezvous order differs from previous run
135 h2. Enable delete operations on keepstore volumes
137 Ensure your keepstore services have the "delete" operation enabled. Otherwise, even when unneeded data is identified by keep-balance, it will never be deleted from the underlying storage devices.
139 Either use the @EnableDelete@ flag in your YAML configuration file @/etc/arvados/keepstore/keepstore.yml@:
143 BlobSigningKeyFile: /etc/keepstore/blob-signing.key
144 <span class="userinput">EnableDelete: true</span>
150 Or use the @-never-delete=false@ command line flag in your run script:
153 <pre><code>keepstore <span class="userinput">-never-delete=false</span> -volume=...