services/keep-balance/usage.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: AGPL-3.0
   4
   5 package main
   6
   7 import (
   8         "flag"
   9         "fmt"
  10         "os"
  11 )
  12
  13 var exampleConfigFile = []byte(`
  14 Client:
  15     APIHost: zzzzz.arvadosapi.com:443
  16     AuthToken: xyzzy
  17     Insecure: false
  18 KeepServiceTypes:
  19     - disk
  20 Listen: ":9005"
  21 ManagementToken: xyzzy
  22 RunPeriod: 600s
  23 CollectionBatchSize: 100000
  24 CollectionBuffers: 1000
  25 RequestTimeout: 30m`)
  26
  27 func usage() {
  28         fmt.Fprintf(os.Stderr, `
  29
  30 keep-balance rebalances a set of keepstore servers. It creates new
  31 copies of underreplicated blocks, deletes excess copies of
  32 overreplicated and unreferenced blocks, and moves blocks to better
  33 positions (according to the rendezvous hash algorithm) so clients find
  34 them faster.
  35
  36 Usage: keep-balance [options]
  37
  38 Options:
  39 `)
  40         flag.PrintDefaults()
  41         fmt.Fprintf(os.Stderr, `
  42 Example config file:
  43 %s
  44
  45     Client.AuthToken must be recognized by Arvados as an admin token,
  46     and must be recognized by all Keep services as a "data manager
  47     key".
  48
  49     Client.Insecure should be true if your Arvados API endpoint uses
  50     an unverifiable SSL/TLS certificate.
  51
  52 Periodic scanning:
  53
  54     By default, keep-balance operates periodically, i.e.: do a
  55     scan/balance operation, sleep, repeat.
  56
  57     RunPeriod determines the interval between start times of
  58     successive scan/balance operations. If a scan/balance operation
  59     takes longer than RunPeriod, the next one will follow it
  60     immediately.
  61
  62     If SIGUSR1 is received during an idle period between operations,
  63     the next operation will start immediately.
  64
  65 One-time scanning:
  66
  67     Use the -once flag to do a single operation and then exit. The
  68     exit code will be zero if the operation was successful.
  69
  70 Committing:
  71
  72     By default, keep-service computes and reports changes but does not
  73     implement them by sending pull and trash lists to the Keep
  74     services.
  75
  76     Use the -commit-pull and -commit-trash flags to implement the
  77     computed changes.
  78
  79 Tuning resource usage:
  80
  81     CollectionBatchSize limits the number of collections retrieved per
  82     API transaction. If this is zero or omitted, page size is
  83     determined by the API server's own page size limits (see
  84     max_items_per_response and max_index_database_read configs).
  85
  86     CollectionBuffers sets the size of an internal queue of
  87     collections. Higher values use more memory, and improve throughput
  88     by allowing keep-balance to fetch the next page of collections
  89     while the current page is still being processed. If this is zero
  90     or omitted, pages are processed serially.
  91
  92     RequestTimeout is the maximum time keep-balance will spend on a
  93     single HTTP request (getting a page of collections, getting the
  94     block index from a keepstore server, or sending a trash or pull
  95     list to a keepstore server). Defaults to 30 minutes.
  96
  97 Limitations:
  98
  99     keep-balance does not attempt to discover whether committed pull
 100     and trash requests ever get carried out -- only that they are
 101     accepted by the Keep services. If some services are full, new
 102     copies of underreplicated blocks might never get made, only
 103     repeatedly requested.
 104
 105 `, exampleConfigFile)
 106 }