github.com/cloud-foundations/dominator@v0.0.0-20221004181915-6e4fee580046/cmd/domtool/README.md (about)

     1  # domtool
     2  A utility to control the *[dominator](../dominator/README.md)*.
     3  
     4  The *domtool* utility may be used to control a running *dominator*.
     5  *Domtool* may be run on any machine and can be used to manipulate various
     6  operating parameters of a running *dominator* and perform RPC requests. It is
     7  typically run on a desktop or bastion machine.
     8  
     9  ## Usage
    10  *Domtool* supports several sub-commands. There are many command-line flags which
    11  provide parameters for these sub-commands. The most commonly used parameter is
    12  `-domHostname` which specifies which host the *dominator* to control is running
    13  on.
    14  The basic usage pattern is:
    15  
    16  ```
    17  domtool [flags...] command [args...]
    18  ```
    19  
    20  Built-in help is available with the command:
    21  
    22  ```
    23  domtool -h
    24  ```
    25  
    26  Some of the sub-commands available are:
    27  
    28  - **configure-subs**: set the current configuration of all *subs* (such as rate
    29                        limits for scanning the file-system and **fetching**
    30                        objects)
    31  - **disable-updates** *reason*: tell *dominator* to not perform automatic
    32                                  updates of *subs*. The given *reason* must be
    33                                  provided and is logged
    34  - **enable-updates** *reason*: tell *dominator* to perform automatic updates of
    35                                 *subs*. The given *reason* must be provided and
    36                                 is logged
    37  - **get-subs-configuration**: get the current configuration that is pushed to
    38                                all *subs*
    39  
    40  ## Security
    41  *[Dominator](../dominator/README.md)* restricts RPC access using TLS client
    42  authentication. *Domtool* will load certificate and key files from the
    43  `~/.ssl` directory. *Domtool* will present these certificates to *dominator*. If
    44  one of the certificates is signed by a certificate authority that *dominator*
    45  trusts, *dominator* will grant access.
    46  
    47  ## Critical Sub-Commands
    48  The most important sub-commands are described below for convenience.
    49  
    50  ### Emergency Stop
    51  To disable automated updates, issue the following command:
    52  
    53  ```domtool -domHostname=mydom.zone disable-updates "my stop reason"```
    54  
    55  This will prevent the *[dominator](../dominator/README.md)* running on the host
    56  `mydom.zone` from performing automated updates. The reason for the emergency
    57  stop along with the username of the person issuing the stop is logged.
    58  
    59  ### Restart
    60  To enable automated updates, issue the following command:
    61  
    62  ```domtool -domHostname=mydom.zone enable-updates "my restart reason"```
    63  
    64  This will restart automated updates. The reason for the restart (typically an
    65  explanation of why the emergency stop is no longer needed) along with the
    66  username of the person issuing the restart is logged.