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

     1  # filegen-server
     2  The *filegen-server* daemon serves computed files for the **Dominator** system.
     3  
     4  The *[dominator](../dominator/README.md)* queries zero or more *filegen-server*
     5  instances when it needs to distribute *computed files*. This *filegen-server* is
     6  a reference implementation and serves some simple computed files. For more
     7  custom types of computed files, see the documentation for the
     8  [lib/filegen](https://godoc.org/github.com/Cloud-Foundations/Dominator/lib/filegen)
     9  package. This reference implementation may be used as a template for writing
    10  your own file generator.
    11  
    12  ## Status page
    13  The *filegen-server* provides a web interface on port `6972` which provides a
    14  status page, links to built-in dashboards and access to performance metrics and
    15  logs. If *filegen-server* is running on host `myhost` then the URL of the main
    16  status page is `http://myhost:6972/`. An RPC over HTTP interface is also
    17  provided over the same port.
    18  
    19  
    20  ## Startup
    21  *Filegen-Server* is started at boot time, usually by one of the provided
    22  [init scripts](../../init.d/). The *filegen-server* process is baby-sat by the
    23  init script; if the process dies the init script will re-start it. It may be
    24  stopped with the command:
    25  
    26  ```
    27  service filegen-server stop
    28  ```
    29  
    30  which also kills the baby-sitting init script. It may be started with the
    31  comand:
    32  
    33  ```
    34  service filegen-server start
    35  ```
    36  
    37  There are many command-line flags which may change the behaviour of
    38  *filegen-server* but many have defaults which should be adequate for most
    39  deployments. Built-in help is available with the command:
    40  
    41  ```
    42  filegen-server -h
    43  ```
    44  
    45  ### Key configuration parameters
    46  The init script reads configuration parameters from the
    47  `/etc/default/filegen-server` file. The following is the minimum likely set of
    48  parameters that will need to be configured.
    49  
    50  The `CONFIG_FILE` variable specifies the name of the file from which to read the
    51  configuration.
    52  
    53  The `USERNAME` variable specifies the username that *filegen-server* should run
    54  as. Since *filegen-server* does not need root privileges, the init script runs
    55  *filegen-server* as this user.
    56  
    57  ## Security
    58  RPC access is restricted using TLS client authentication. *Filegen-Server*
    59  expects a root certificate in the file `/etc/ssl/CA.pem` which it trusts to sign
    60  certificates which grant access. It also requires a certificate and key which
    61  clients will use to validate the server. These should be in the files
    62  `/etc/ssl/filegen-server/cert.pem` and `/etc/ssl/filegen-server/key.pem`,
    63  respectively.
    64  
    65  ## Configuration file
    66  The configuration file contains zero or more lines of the form:
    67  `keyword pathname [args...]`. The keyword specifies an algorithm to use to
    68  generate data for the specified *pathname*. The following keywords are
    69  supported:
    70  
    71  - **DynamicTemplateFile** pathname *filename*: the contents of *filename* are
    72    used as a template to generate the file data. If the file contains sections of
    73    the form `{{.MyVar}}` then the value of the `MyVar` variable from the MDB for
    74    the host are used to replace the section. If *filename* changes (replaced with
    75    a different inode), then the data are regenerated and distributed to all
    76    clients
    77  
    78  - **File** pathname *filename*: the contents of *filename* are used to provide
    79    the file data. If *filename* changes (replaced with a different inode), then
    80    the data are regenerated and distributed to all clients
    81  
    82  - **MDB** pathname: the file data are the JSON encoding the MDB data for the
    83    host
    84  
    85  - **StaticTemplateFile** pathname *filename*: the contents of *filename* are
    86    used as a template to generate the file data. If the file contains sections of
    87    the form `{{.MyVar}}` then the value of the `MyVar` variable from the MDB for
    88    the host are used to replace the section