// file      : bbot/agent.cli
// license   : TBC; see accompanying LICENSE file

include <bbot/common.cli>;

"\section=1"
"\name=bbot-agent"
"\summary=build bot agent"

namespace bbot
{
  {
    "<options> <url>",

    "
    \h|SYNOPSIS|

    \c{\b{bbot-agent --help}\n
       \b{bbot-agent --version}\n
       \b{bbot-agent} [<options>] <url>...}

    \h|DESCRIPTION|

    \cb{bbot-agent} @@ TODO.

    Note that on termination \cb{bbot-agent} may leave behind a machine lock
    and working machine snapshot. It is expected that the caller (normally
    Build OS monitor) cleans them up before restarting the agent.
    "
  }

  class agent_options
  {
    "\h|OPTIONS|"

    bool --help {"Print usage information and exit."}
    bool --version {"Print version and exit."}

    uint16_t --verbose = 1
    {
      "<level>",
      "Set the diagnostics verbosity to <level> between 0 and 6 with level 1
       being the default."
    }

    bool --systemd-daemon
    {
      "Run as a simple systemd daemon."
    }

    string --toolchain-name = "default"
    {
      "<str>",
      "Toolchain name, \cb{default} by default."
    }

    uint16_t --toolchain-num = 1
    {
      "<num>",
      "Toolchain number, 1 by default. If agents are running for several
       toolchains, then each of them should have a unique toolchain number
       between 1 and 99. This number is used as an offset for network ports,
       interfaces, etc."
    }

    standard_version --toolchain-ver
    {
      "<stdver>",
      "Toolchain version. If unspecified, then the agent's version will be
       used (which will be imprecise for snapshot versions)."
    }

    string --toolchain-id
    {
      "<str>",
      "Toolchain id. If unspecified or empty, then no re-bootstrapping on
       toolchain changes will be performed (which is primarily useful for
       testing)."
    }

    // We reserve 0 in case in the future we want to distinguish a single-
    // instance mode or some such.
    //
    uint16_t --instance = 1
    {
      "<num>",
      "Instance number, 1 by default. If several instances of an agent are
       running for the same toolchain, then each of them should have a unique
       instance number between 1 and 99. This number is used as an offset for
       network ports, interfaces, etc."
    }

    size_t --cpu = 1
    {
      "<num>",
      "Number of CPUs (threads) to use, 1 by default."
    }

    size_t --ram (1024 * 1024) // 1G
    {
      "<num>",
      "Amount of RAM (in kB) to use, 1G by default."
    }

    string --bridge = "br1"
    {
      "<iface>",
      "Bridge interface to use for machine networking, \cb{br1} by default."
    };

    path --auth-key
    {
      "<file>",
      "Private key for the public key-based agent authentication. If not
       specified, then the agent will not be able to request tasks from
       controllers that require authentication.

       The file is expected to contain a single PEM-encoded private key
       without a password. A suitable key can be generated using the
       following command:

       \
       $ openssl genrsa 4096 >key.pem
       \
       "
    }

    strings --trust
    {
      "<fingerprint>",
      "Trust repository certificate with a SHA256 <fingerprint>."
    }

    dir_path --machines = "/build/machines/"
    {
      "<dir>",
      "The location of the build machines, \cb{/build/machines/} by default."
    }

    dir_path --tftp = "/build/tftp/"
    {
      "<dir>",
      "The location of the TFTP server root, \cb{/build/tftp/} by default."
    }

    // Low 23401+, 23501+, 23601+, etc., all look good collision-wise with
    // with anything useful.
    //
    uint16_t --tftp-port = 23400
    {
      "<num>",
      "TFTP server port base, 23400 by default. The actual port is calculated
       by adding an offset calculated based on the toolchain and instance
       numbers."
    }

    size_t --bootstrap-timeout = 1800
    {
      "<sec>",
      "Maximum number of seconds to wait for machine bootstrap completion,
       1800 (30 minutes) by default."
    }

    size_t --bootstrap-retries = 2
    {
      "<num>",
      "Number of times to retry a mis-booted bootstrap, 2 (3 attempts total)
       by default."
    }

    size_t --build-timeout = 3600
    {
      "<sec>",
      "Maximum number of seconds to wait for build completion, 3600 (60
       minutes) by default."
    }

    size_t --build-retries = 2
    {
      "<num>",
      "Number of times to retry a mis-booted build, 2 (3 attempts total) by
       default."
    }

    size_t --connect-timeout = 60
    {
      "<sec>",
      "Maximum number of seconds to wait for controller request connection,
       60 (1 minute) by default."
    }

    size_t --request-timeout = 300
    {
      "<sec>",
      "Maximum number of seconds to wait for controller request completion,
       300 (5 minutes) by default."
    }

    size_t --request-retries = 4
    {
      "<num>",
      "Number of times to retry a controller request, 4 (5 attempts total) by
       default. Note that both the total time for all retries as well as the
       time of each retry are limited by the same \c{--request-timeout}
       value. This means that a successful request may take up to twice as
       long if a connection was established at the end of the retry window
       and took just as long to complete."
    }

    path --openssl = "openssl"
    {
      "<path>",
      "The openssl program to be used for crypto operations. You can also
       specify additional options that should be passed to the openssl program
       with \cb{--openssl-option}. If the openssl program is not explicitly
       specified, then \cb{bbot-agent} will use \cb{openssl} by default."
    }

    strings --openssl-option
    {
      "<opt>",
      "Additional option to be passed to the openssl program (see
       \cb{--openssl} for details). Repeat this option to specify multiple
       openssl options."
    }

    // Testing options.
    //
    bool --dump-machines
    {
      "Dump the available machines to \cb{stdout}, (re)-bootstrapping any if
       necessary, and exit."
    }

    bool --dump-task
    {
      "Dump the received build task to \cb{stdout} and exit."
    }

    bool --dump-result
    {
      "Dump the obtained build result to \cb{stdout} and exit."
    }

    bool --fake-bootstrap
    {
      "Fake the machine bootstrap process by creating the expected bootstrapped
       machine manifest."
    }

    bool --fake-build
    {
      "Fake the package building process by creating the aborted build result."
    }

    path --fake-machine
    {
      "<file>",
      "Fake the machine enumeration process by reading the machine header
       manifest from <file> (or \cb{stdin} if <file> is '\cb{-}')."
    }

    path --fake-request
    {
      "<file>",
      "Fake the task request process by reading the task manifest from <file>
       (or \cb{stdin} if <file> is '\cb{-}')."
    }
  };

  "
  \h|EXIT STATUS|

  Non-zero exit status is returned in case of an error.
  "
}