# FileConfigurator Operator The **FileConfigurator** operator allows configuring systems tuned by Akamas by interpolating configuration parameters into files on remote machines. The operator performs the following operations: 1. It reads an input file from a remote machine containing templates for interpolating the configuration parameters generated by Akamas 2. It replaces the values of configuration parameters in the input file 3. It writes the file with replaced configuration parameters on a specified path on another remote machine Access on remote machines is performed using SFTP (SSH). ## Templates for configuration parameters The FileConfigurator allows writing templates for configuration parameters in two ways: * specify that a parameter should be interpolated directly: ``` ${component_name.parameter_name} ``` * specify that all parameters of a component should be interpolated: ``` ${component_name.*} ``` ### Suffix or prefix for interpolated parameters It is possible to add a prefix or suffix to interpolated configuration parameters by acting at the component-type level: Notice that any parameter that does not contain the FileConfigurator element in the operators' attribute is ignored and not written. {% code lineNumbers="true" %} ```yaml name: Component Type 1 description: My Component type parameters: - name: x1 domain: type: real domain: [-5.0, 10.0] defaultValue: -5.0 # Under this section, the operator to be used to configure the parameters is defined operators: FileConfigurator: # using this OPTIONAL confTemplate property is possible to interpolate the parameter value with a prefix and a suffix confTemplate: "PREFIX${value}SUFFIX" ``` {% endcode %} In the example above, the parameter `x1` will be interpolated with the prefix `PREFIX` and the suffix `SUFFIX`, `${value}` will be replaced with the actual value of the parameter at each experiment. ### Example Let's assume we want to apply the following configuration: {% code lineNumbers="true" %} ``` component1.param1: 1024 component1.param2: Category1 component2.param3: 7 component2.param4: 35.4 ``` {% endcode %} where `component1` is of type `MyComponentType` and `MyComponentType` is defined as follows: {% code lineNumbers="true" %} ```yaml name: MyComponentType description: "MyComponentType parameters: - name: param1 domain: type: real domain: [-5.0, 10.0] defaultValue: -5.0 # Under this section, the operator to be used to configure the parameters is defined operators: FileConfigurator: # using this OPTIONAL confTemplate property is possible to interpolate the parameter value with a prefix and a suffix confTemplate: "X1:${value}MB" ... ``` {% endcode %} A template file to interpolate only parameter `component1.param1` and all parameters from `component2` would look like this: {% code lineNumbers="true" %} ``` myexecutable.sh -PARAM ${component1.param1} -PARAMS ${component2.*} ``` {% endcode %} The file after the configuration parameters are interpolated would look like this: {% code lineNumbers="true" %} ``` myexecutable.sh -PARAM X1:1024MB -PARAMS 7 35.4 ``` {% endcode %} Note that the file in this example contains a bash command whose arguments are constructed by interpolating configuration parameters. This represents a typical use case for the File Configurator: to construct the right bash commands that will configure a system with the new configuration parameters computed by Akamas. ## Operator arguments | Name | Type | Value Restrictions | Required | Default | Description | | --------------------------- | ------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | Object | should have a structure like the one defined in the next section | no, if the Component whose name is defined in `component` has properties that map to the ones defined within `source` | | Information relative to the source/input file to be used to interpolate optimal configuration parameters discovered by Akamas | | `target` | Object | should have a structure like the one defined in the next section | no, if the Component whose name is defined in `component` has properties that map to the ones defined within `target` | | Information relative to the target/output file to be used to interpolate optimal configuration parameters discovered by Akamas | | `component` | String | should match the name of an existing Component of the System under test | no | | The name of the Component whose properties can be used as arguments of the operator | | `ignoreUnsubstitutedTokens` | Boolean | | no | False |

Behavior of the operator regarding leftover tokens in the target file.
When False, FileConfigurator fails.
When True , FileConfigurator succeeds regardless of leftover tokens

| ### `source` and `target` structures and arguments Here follows the structure of either the `source` or `target` operator argument | Name | Type | Value restrictions | Required | Default | Description | | ---------- | ------ | ------------------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `hostname` | String | should be a valid SSH host address | yes | | SSH endpoint | | `username` | String | | yes | | SSH login username | | `password` | String | cannot be set if `key` is already set | no | | SSH login password | | `sshPort` | Number | 1≤`sshPort`≤65532 | no | 22 | SSH port | | `key` | String | cannot be set if `password` is already set | no | | SSH login key, provided directly its value or the path of the file to import from. The operator supports RSA and DSA Keys | | `path` | String | should be a valid path | yes | | The path of the file to be used either as the source or target of the activity to applying Akamas computed configuration parameters using files | ### Get operator arguments from `component` The `component` argument can be used to refer to a component by name and use its properties as the arguments of the operator. In case the mapped arguments are already provided to the operator, there is no override. In this case, the operator replaces in the template file only tokens referring to the specified component. A parameter bound to any component will cause the substitution to fail. #### Component property to operator argument mapping | Component property | Operator argument | | ------------------ | ------------------------------------- | | `hostname` | `source->hostname` `target->hostname` | | `username` | `source->username` `target->username` | | `sshPort` | `source->sshPort` `target->sshPort` | | `password` | `source->password` `target->password` | | `key` | `source->key` `target->key` | | `sourcePath` | `source->path` | | `targetPath` | `target->path` | ### Examples #### Configure parameters for an Apache server with explicit source and target machines information {% code lineNumbers="true" %} ``` name: RemoteConfOperatorTestStandalone operator: FileConfigurator arguments: source: hostname: template-server username: akamas-user1 password: akamas-password1 path: /templates/frontend-httpd.conf target: hostname: frontend-server username: akamas-user2 password: akamas-password22 path: /etc/httpd/httpd.conf ``` {% endcode %} #### Configure parameters for an Apache server with information taken from a Component {% code lineNumbers="true" %} ```yaml name: RemoteConfOperatorTestStandalone operator: FileConfigurator arguments: component: apache-server-1 ``` {% endcode %} where the `apache-server-1` component is defined as: {% code lineNumbers="true" %} ```yaml name: apache-server-1 description: The Apache server instance componentType: Apache Server 2.4 properties: hostname: apache.akamas.io username: ubuntu key: key.pem sourcePath: templates/httpd.conf.template targetPath: /etc/httpd/httpd.conf ``` {% endcode %}