# LinuxConfigurator Operator

The **LinuxConfigurator** operator allows configuring systems tuned by Akamas by applying parameters related to the Linux kernel using different strategies.

The operator can configure provided Components or can configure every Component which has parameters related to the Linux kernel.

The parameters are applied via SSH protocol.

## Operator arguments

| Name        | Type   | Value Restrictions                                                         | Required | Default | Description                                                                              |
| ----------- | ------ | -------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `component` | String | It should match the name of an existing Component of the System under test | No       |         | The name of the Component for which available Linux kernel parameters will be configured |

If no `component` is provided, this operator will try to configure every parameter defined for the Components of the System under test

```yaml
- name: LinuxConf
  operator: LinuxConfigurator
  arguments:
    component: ComponentName
```

### Example

In this example, the Operator is used to automatically the OS parameters of the specified component.

```yaml
- name: LinuxConf
  operator: LinuxConfigurator
  arguments:
    component: OS_serveraml
```

### `component` structure and arguments

The following table describes the `component` structure and arguments.

| Name                             | Type             | Value Restrictions                                           | Required | Default | Description                                                                                                               |
| -------------------------------- | ---------------- | ------------------------------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| <p><br><code>username</code></p> | String           |                                                              | Yes      |         | SSH login username                                                                                                        |
| `key`                            | Multiline string |                                                              | Yes      |         | SSH login key, provided directly its value or the path of the file to import from. The operator supports RSA and DSA Keys |
| `blockDevices`                   | List of objects  | It should have a structure like the one described here below | No       |         | Allows the user to restrict and specify to which block-device apply block-device-related parameters                       |
| `networkDevices`                 | List of objects  | It should have a structure like the one described here below | No       |         | Allows the user to restrict and specify to which network-device apply network-device-related parameters                   |

### `blockDevices` and `networkDevices` structure and arguments <a href="#filter-parameters-and-block-network-devices" id="filter-parameters-and-block-network-devices"></a>

The properties `blockDevices` and `networkDevices` allow to speficify which parameters to apply each block and network device associated with the Component, as well as which block and network device should be left untouched by the LinuxConfigurator operator\_.\_

If the properties are omitted, then all block and network devices associated with the Component will be configured will all the available related parameters.

Notice: all block devices called \_`loopN` \_ (where *N* is an integer number greater or equal to 0) are automatically excluded from the Component’s block devices.

The properties `blockDevices` and `networkDevices` are lists of objects with the following structure:

| Name         | Type            | Value Restrictions                                                     | Required | Default |                                                                                                                                                                                          |
| ------------ | --------------- | ---------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | String          | It should be a valid regular expression to match block/network-devices | Yes      |         | A regular expression that matches block/network-devices to configure with related parameters of the Component                                                                            |
| `parameters` | List of strings | It should contain the names of matching parameters of the Component    | No       |         | The list of parameters to be configured for the specified block/network-devices. If the list is empty, then no parameter will be applied for the block/network-devices matched by `name` |

### Examples

In the following example, only the parameters *`os_StorageReadAhead` \_ and `os_StorageQeueuScheduler` \_ are applied to all the devices that match the regex ‘`xvd[a-z]`*’ (i.e. `xvda`, `xvdb`, …, `xvdc`):

```yaml
blockDevices:
- name: "xvd[a-z]"
  parameters:
    - os_StorageReadAhead
    - os_StorageQueueScheduler
```

In the following example, only the parameter *`os_StorageMaxSectorKb`* is applied to block device *`xvdb`* and *`loop0`:*

```yaml
blockDevices:
- name: "xvdb|loop0"
  parameters:
    - os_StorageMaxSectorsKb
```

Also notice that in this example, the parameter is applied also to the block device `loop0`, since it is explicitly specified in the name filter, which overrides the default behavior since *`loopN`* devices are excluded by the Linux Optimization Pack.

In the following example, no parameters are applied to the *`wlp4s0`* network device, which is therefore excluded from the optimization:

```yaml
networkDevices:
  - name: wlp4s0
    parameters: []
```

### Strategies

Several strategies are supported by this operator which, depending on the specific strategy, can be specified at ComponentType and at each parameter level.

#### Sysctl strategy

With this strategy, a parameter is configured by leveraging the *sysctl* utility. The *sysctl* variable to map to the parameter that needs to be configured is specified using the `key` argument.

```yaml
name: Component Type 1
description: My Component type
parameters:
  - name: net_forwarding
    domain:
      type: integer
      domain: [0, 1]
    defaultValue: 1
    operators:
      # the parameter is configured using LinuxConfigurator
      LinuxConfigurator:
        sysctl:
          key: net.ipv4.forwarding
```

#### Echo strategy <a href="#echo-strategy" id="echo-strategy"></a>

With this strategy, a parameter is configured by echoing and piping its value into a provided file. The path of the file is specified using the `file` argument.

```yaml
name: Component Type 1
description: My Component type
parameters:
  - name: os_MemoryTransparentHugepageEnabled
    domain:
      type: categorical
      categories: [always, never]
    defaultValue: always
    operators:
      LinuxConfigurator:
        echo:
          file: /sys/kernel/mm/transparent_hugepage/enabled
```

#### Map strategy <a href="#hardbreak-map-strategy" id="hardbreak-map-strategy"></a>

With this strategy, each possible value of a parameter is mapped to a command to be executed on the machine the LinuxConfigurator operates on(this is especially useful for categorical parameters).

```yaml
name: Component Type 1
description: My Component type
parameters:
  - name: os_MemorySwap
    domain:
      type: categorical
      categories: [swapon, swapoff]
    defaultValue: swapon
    operators:
      LinuxConfigurator:
        map:
          swapon: command1
          swapoff: command2
```

#### Command strategy <a href="#command-strategy" id="command-strategy"></a>

With this strategy, a parameter is configured by executing a command into which the parameter value is interpolated.

```yaml
name: Component Type 1
description: My Component type
parameters:
  - name: os_MemorySwap
    domain:
      type: categorical
      categories: [swapon, swapoff]
    defaultValue: swapon
    operators:
      LinuxConfigurator:
        command:
          cmd: sudo ${value} -a
```