FIREWHEEL Configuration

While we recommend setting a few FIREWHEEL configuration options during installation (see Set Environment Variables). There are numerous other options to set which are located in src/firewheel/firewheel.yaml.

This section outlines how to change the configuration and of the available options.

Configuration Options

The main configuration options which must change are modified during installation with install.sh. Here are all configuration options which are available to be changed.

`attribute_defaults`

This setting is a YAML dictionary which enables users to set a default model component if there is more than one which accomplishes the same Attribute. That is, if Model Components mc.A and mc.B both provides the Attribute hostname, FIREWHEEL will be unable to automatically determine which Model Component should be selected. To resolve this, the user can either add the Model Component on the command line or use this setting to enable FIREWHEEL to automatically assume the default Model Component, unless overwritten via the command line. See Dependency Management for more information.

Setting	Value	Description
`<Attribute Name>`	`<Model Component Name>`	The attribute for which FIREHWEEL should select the given Model Component by default.

`cli`

These settings are used by FIREWHEEL’s Command Line Interface.

Setting	Value Type	Default	Description
`cache_dir`	string	`fw_cli`	The folder name of the CLI Helper cache.
`root_dir`	string	`""`	The path to the `cache_dir`. If left empty, the `system.default_output_dir` value will be used.

`cluster`

These settings control the FIREWHEEL Cluster.

Setting	Value Type	Default	Description
`compute`	list	`[]`	The list of IP address or hostname for Compute Nodes in the FIREWHEEL Cluster.
`control`	list	`[]`	A list with the ONE IP address or hostname for the Control Node for your FIREWHEEL Cluster.

`discovery`

These settings are used for interaction between FIREWHEEL and discovery.

Setting	Value Type	Default	Description
`hostname`	string	`localhost`	The hostname or IP address of the discovery service.
`install_dir`	string	`/opt/discovery`	The installation directory of discovery. This is used to locate the discovery binary files.
`port`	int	`8080`	The port number for the discovery service.

`grpc`

These settings are used by FIREWHEEL’s gRPC service.

Setting	Value Type	Default	Description
`cache_dir`	string	`fw_grpc`	The folder name of the gRPC database cache.
`db`	string	`prod`	The name of the database to use. We use `prod` for production and `test` for running our test suite.
`hostname`	string	`""`	The hostname or IP address of FIREWHEEL’s gRPC service. This is typically the Control Node.
`port`	int	`50051`	The port number for FIREWHEEL’s gRPC service.
`root_dir`	string	`""`	The path to the `cache_dir`. If left empty, the `system.default_output_dir` value will be used.
`threads`	int	`2`	The number of threads used for the gRPC service. If the cluster is larger, the number of threads should be increased to facilitate better performance.

`logging`

These settings are used to manage FIREWHEEL’s logging capabilities.

Setting	Value Type	Default	Description
`cli_log`	string	`cli.log`	The name of the CLI log file. This file contains the responses for all CLI commands issued.
`discovery_log`	string	`discovery.log`	The name of the discovery log file.
`firewheel_log`	string	`firewheel.log`	The name of the primary FIREWHEEL log file.
`level`	string	`DEBUG`	The logging level for FIREWHEEL. Valid values are found here.
`minimega_log`	string	`minimega.log`	The name of the minimega log file.
`root_dir`	string	`""`	The path to the log files. If left empty, the `system.default_output_dir` value will be used.
`vmr_log_dir`	string	`vm_resource_logs`	The folder name for VM Resource logs. The full path will be `<root_dir>/<vmr_log_dir>`.

`minimega`

These settings are used for interaction between FIREWHEEL and minimega.

Setting	Value Type	Default	Description
`base_dir`	string	`/tmp/minimega`	minimega’s `MINIMEGA_DIR` configuration option. This is where minimega stores all of its run time files.
`control_bridge`	string	`mega_bridge`	The bridge which is used by minimega to manage communication with the FIREWHEEL Cluster.
`degree`	int	`1`	The minimega degree for the cluster. This specifies the number of other nodes minimega should try to connect to and should be equal to the number of nodes in your FIREWHEEL Cluster.
`experiment_interface`	string	`""`	The NIC for the current host for which will be used to connect to other Cluster Nodes.
`files_dir`	string	`/tmp/minimega/files`	minimega’s `filepath` option, which is used in their iomeshage capability.
`install_dir`	string	`""`	The installation directory for minimega. This is set with `install.sh` and is typically `/opt/minimega`.
`namespace`	string	`firewheel`	The name of the minimega namespace.
`use_gre`	boolean	`false`	minimega defaults to using VLANs to segment traffic between Cluster Nodes, to use GRE tunnels instead of VLAns, set this to `true`.

`python`

These settings are used to specify the Python version, virtual environment, and executable to be used by FIREWHEEL.

Setting	Value Type	Default	Description
`bin`	string	`python3`	The Python executable to use for running FIREWHEEL. This is set with `install.sh` and is typically just `python3`.
`venv`	string	`""`	The path to the virtual environment to use for running FIREWHEEL. This is set with `install.sh` and is typically `/opt/firewheel/fwpy`.

`ssh`

These settings are used for SSH/SCP amongst nodes in the FIREWHEEL Cluster.

Setting	Value Type	Default	Description
`user`	string	`null`	A username for SSH and SCP between Cluster Nodes. This is only needed if it differs from the current user.

`system`

These settings are used for system-level interactions.

Setting	Value Type	Default	Description
`default_group`	string	`minimega`	The user group for FIREWHEEL.
`default_output_dir`	string	`/tmp/firewheel`	The default directory for FIREWHEEL outputs (e.g. logs, cached data, etc.).
`firewheel_root_dir`	string	`/opt/firewheel`	For users installing FIREWHEEL from source code, this is the root directory of the source code repository.
`umask`	int	`0o0`	The default umask settings, if any.

`test`

These settings are used for testing FIREWHEEL without interfering with the production settings.

Setting	Value Type	Default	Description
`grpc_db`	string	`test`	The name of the gRPC database to use. We use `test` for running our test suite.
`image_db`	string	`testImageStoreDb`	The name of the test `ImageStore` database.
`schedule_test_database`	string	`testScheduleDB`	The name of the test `ScheduleDb` database.
`vm_resource_store_test_database`	string	`testVmResourceDB`	The name of the test `VmResourceStore` database.
`vmmapping_test_database`	string	`testVmMappingDB`	The name of the test `VMMapping` database.

`vm_resource_manager`

These settings are used with FIREWHEEL’s VM Resource Manager.

Setting	Value Type	Default	Description
`default_state`	string	`uninitialized`	The default state of VMs after they are launched.
`experiment_start_buffer_sec`	int	`60`	The number of seconds after all experiment VMs have been configured to start Positive Time.

Changing FIREWHEEL Settings

To get and set configuration values, there are two commands: config get and config set.

The config set command enables replacing the entire configuration file or modifying a given setting.

Additionally, config get command enables retrieving the entire configuration file or only a given setting.

When updating or retrieving a single setting, a nested option is indicated with a period separating the keys. For example, to set the value for the config key {'logging':{'level':'DEBUG'}}, you can use the command:

firewheel config set -s logging.level INFO

To get the value of {'cluster':{'compute':[]}}, you can use the command:

firewheel config get cluster.compute

Please see config get and config set for more details.

Changing minimega Settings

Some minimega settings are used by FIREWHEEL (e.g. those used in minimega configuration section above). However, while FIREWHEEL uses these settings, users have to modify both the underlying minimega settings and the corresponding FIREWHEEL configuration. Therefore, if you would like to modify where minimega caches files then the minimega configuration file (see Configuring minimega) setting MM_FILEPATH should be updated then the corresponding FIREWHEEL setting minimega.files_dir should be updated. Once both settings have been updated, a simple firewheel restart hard will help the settings take effect.

Default Configuration

The file src/firewheel/firewheel.yaml contains the settings for FIREWHEEL. The default file is shown below.

Listing 5 firewheel.yaml

attribute_defaults: {}
cli:
    cache_dir: fw_cli
    root_dir: ""
cluster:
    compute: []
    control: []
discovery:
    hostname: localhost
    install_dir: /opt/discovery
    port: 8080
grpc:
    cache_dir: fw_grpc
    db: prod
    hostname: ""
    port: 50051
    root_dir: ""
    threads: 2
logging:
    cli_log: cli.log
    discovery_log: discovery.log
    firewheel_log: firewheel.log
    level: DEBUG
    minimega_log: minimega.log
    root_dir: ""
    vmr_log_dir: vm_resource_logs
minimega:
    base_dir: /tmp/minimega
    control_bridge: mega_bridge
    degree: 1
    experiment_interface: ""
    files_dir: /tmp/minimega/files
    install_dir: /opt/minimega
    namespace: firewheel
    use_gre: false
python:
    bin: python3
    venv: ""
ssh:
    user: null
system:
    default_group: minimega
    default_output_dir: /tmp/firewheel
    umask: 0o0
test:
    grpc_db: test
    image_db: testImageStoreDb
    schedule_test_database: testScheduleDB
    vm_resource_store_test_database: testVmResourceDB
    vmmapping_test_database: testVmMappingDB
vm_resource_manager:
    default_state: uninitialized
    experiment_start_buffer_sec: 60

FIREWHEEL Configuration

Configuration Options

attribute_defaults

cli

cluster

discovery

grpc

logging

minimega

python

ssh

system

test

vm_resource_manager