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

     1  # dominator
     2  The *dominator* daemon is the heart of the **Dominator** system. It continuously
     3  **polls** all the known *subs* and directs them to make corrections if needed.
     4  
     5  The list of known *subs* is read from a local file (`/var/lib/Dominator/mdb` by
     6  default). This file is updated by the *[mdbd](../mdbd/README.md)* companion
     7  daemon.
     8  
     9  ## Status page
    10  The *dominator* provides a web interface on port `6970` which provides a status
    11  page, links to built-in dashboards and access to performance metrics and logs.
    12  If *dominator* is running on host `myhost` then the URL of the main status page
    13  is `http://myhost:6970/`.
    14  
    15  ## Startup
    16  *Dominator* is started at boot time, usually by one of the provided
    17  [init scripts](../../init.d/). The *dominator* process is baby-sat by the init
    18  script; if the process dies the init script will re-start it. It may be stopped
    19  with the command:
    20  
    21  ```
    22  service dominator stop
    23  ```
    24  
    25  which also kills the baby-sitting init script. It may be started with the
    26  comand:
    27  
    28  ```
    29  service dominator start
    30  ```
    31  
    32  There are many command-line flags which may change the behaviour of *dominator*
    33  but many have defaults which should be adequate for most deployments. Built-in
    34  help is available with the command:
    35  
    36  ```
    37  dominator -h
    38  ```
    39  
    40  ### Key configuration parameters
    41  The init script reads configuration parameters from the `/etc/default/dominator`
    42  file. The following is the minimum likely set of parameters that will need to be
    43  configured.
    44  
    45  The `IMAGE_SERVER_HOSTNAME` variable specifies the hostname where the
    46  *[imageserver](../imageserver/README.md)* is running. This hostname must be
    47  resolvable by the *dominator* and all the *subs*. In a multi-zone deployment,
    48  it is recommended to use a geoDNS name, as it makes *dominator* configuration
    49  uniform across zones.
    50  
    51  The `USERNAME` variable specifies the username that *dominator* should run as.
    52  Since *dominator* does not need root privileges, the init script runs
    53  *dominator* as this user.
    54  
    55  ## Security
    56  RPC access is restricted using TLS client authentication. *Dominator* expects a
    57  root certificate in the file `/etc/ssl/CA.pem` which it trusts to sign
    58  certificates which grant access.
    59  
    60  *Dominator* will require signed SSL certificates in order to communicate with
    61  *[subd](../subd/README.md)* and the *[imageserver](../imageserver/README.md)*.
    62  The certificate and key should be in the files
    63  `/etc/ssl/dominator/cert.pem` and `/etc/ssl/dominator/key.pem`, respectively.
    64  
    65  If any of these files are missing, *dominator* will refuse to start. This
    66  prevents accidental deployments without access control.
    67  
    68  ## Control
    69  The *[domtool](../domtool/README.md)* utility may be used to manipulate various
    70  operating parameters of a running *dominator* and perform RPC requests. The most
    71  important controls are described below for convenience.
    72  
    73  ### Emergency Stop
    74  To disable automated updates, issue the following command:
    75  
    76  ```domtool -domHostname=mydom.zone disable-updates "my stop reason"```
    77  
    78  This will prevent the *dominator* running on the host `mydom.zone` from
    79  performing automated updates. The reason for the emergency stop along with the
    80  username of the person issuing the stop is logged.
    81  
    82  ### Restart
    83  To enable automated updates, issue the following command:
    84  
    85  ```domtool -domHostname=mydom.zone enable-updates "my restart reason"```
    86  
    87  This will restart automated updates. The reason for the restart (typically an
    88  explanation of why the emergency stop is no longer needed) along with the
    89  username of the person issuing the restart is logged.