Design notes for allowing an embedded hostcontroller to be started with empty host and / or domain configuration files

Version 7



    Currently, the embedded host controller (embed-host-controller) does not permit empty configuration files to be used when booting a new instance of the HC. A similar behavior is currently supported in standalone embedded, and is a desirable initial state for configuration / provisioning of host-controllers via tools (e.g. provisioning, scripting etc).


    This change proposes addition of the following parameters to the existing embed-host-controller command:

    • --empty-host-config:
      • Start an embedded host controller with an empty host.xml. This may be used in conjunction with --host-config=<some-host.xml> to specify a filename. If this filename exists and is > 0 bytes in length, an error is generated and no changes are made unless --remove-existing-host-config is also provided (see below).
    • --empty-domain-config:
      • This indicates that the embedded-hostcontroller is intended to be started with an empty domain.xml. As above, if the file exists and is > 0 bytes in length, an error is generated unless --remove-existing-domain-config is also used.
    • --remove-existing-host-config / --remove-existing-domain-config:
      • When starting with --empty-host-config or --empty-domain-config respectively, these commands indicate that if the configuration files exist (either with their default names of host.xml or domain.xml, or the specified files indicated with --host-config= or --domain-config=) they will be removed and replaced with new, empty versions of the files. In the case these files exist, and are > 0 bytes in length, and these parameters are not provided, an error is generated, and the operation is aborted with no changes. (This is a safeguard mechanism to try and prevent users from overwriting / truncating existing configurations.)
    • --host-controller-name=<some name>:
      • In some cases a predetermined name for the host-controller may be desirable when starting with an empty configuration. The default behavior (i.e. not using this parameter) is to derive the host name using the existing algorithm in HostControllerEnvironment. This currently uses a combination of properties such as the host's fully qualified domain name (FQDN), local UNIX hostname or windows computer name etc. This change is not persisted in the generated host.xml, unless the name is specifically set using /host=foo:write-attribute(name=name, value=<some name> or some other mechanism.) Use of this parameter requires the use of --empty-host-config or an error is generated and the operation is aborted with no changes.


    Issue Metadata:

    Wildfly Jira: [WFCORE-2933] Add support for --empty-domain-config, --remove-existing-domain-config, --empty-host-config & --remove-exi…




    Hard Requirements

    • The following parameters must be added to the existing embed-host-controller command: {--empty-host-config, --empty-domain-config, --remove-existing-host-config, --remove-existing-domain-config, --host-controller-name=<some name>}. For command descriptions, see Overview above.
    • Each set of commands {--empty-domain-config, --remove-existing-domain-config}, {--empty-host-config, --remove-existing-host-config, --host-controller-name} are usable independently. For example an existing domain.xml may  be used to boot an embedded host controller with an empty host.xml and vice-versa.
    • In all cases of command usage, existing user data preservation should be prioritized, unless the appropriate override parameter is supplied (e.g. using --empty-host-config and specifying an existing > 0 byte length file should abort with an error, and no changes to the indicated file. If the user specifies --remove-existing-host-config, then this file should be truncated / deleted and used.)
    • When an embedded host controller is started with an empty configuration, it must be possible to set the host controller name to an alternate name other than that which would be provided from the current host and HostEnvironment. This is to facilitate deterministic targeting of commands, so rather than requiring that a :read-attribute(local-host-name) before the derived host controller name is known, the host controller is started with a predetermined host controller name that may be used to execute commands in the form /host=<predetermined name>/command. This name must not be persisted in configurations, only if the host controller name is specifically set via :write-attribute (or similar) should the host controller name be persisted in configuration files.
    • The reload command should operate as expected and reload the embedded host controller with the previously indicated host.xml / domain.xml configurations. Subsequent to this, the empty host / domain flag behaviors should no longer be active. [Note, what about the host name? ]
    • Currently performing a /host=foo:write-attribute(name=name, value=bar) will cause the CLI to hang as the host controller name has changed. We should note that this has changed and handle it appropriately.


    Nice-to-have Requirements




    • There is a specific non-requirement for booting an embedded host controller with empty configurations, performing no or inadequate configuration and reloading the host controller. This scenario is considered user error, and will not be handled. [To be more specific, beginning with an empty configuration is not a sufficient configuration to then use those empty files to boot an embedded host controller using these files, additional user specified configuration is required.]


    Design Details


    Most of these changes are changes to add command line parsing and validation.


    A minimal set of default boot time operations will be needed to start an embedded host controller with an "empty" configuration. This set of boot operations is currently determined to be:

      • register-host-model: This is used to set the host name of the host controller on boot. The default value is currently determined in HostControllerEvironment as a derived value from FQDN / HOSTNAME / COMPUTERNAME etc.
      • write-local-domain-controller: This is used to indicate that we are at least initially going to be a domain controller (DC). This has little bearing on the configuration and the domain-controller configuration will either be overwritten by user configuration or left at the default value (either this HC will end up as a slave or DC after configuration).



    - add thoughts on /host=foo:add() and interaction with the above. [Do we need this? It doesn't seem so.]

    - consider changing --host-controller-name= to --host-controller-alias or something similar to indicate its temporary, non-persistent nature.