# Service VMs

Service VMs can be used to provide, as you've probably guessed, services to the VMs.
These could include, e.g., mail servers, file sharing services like Samba or FTP, or
just other participants to mimic network activity.

```yaml
name: Docker-compose config
description: Configuration file for integration of Docker containers in ForTrace++
author: Mr. X
root: /var/tmp/ForTrace_Service_VM_scenario
domain:
  - examples/Service_VM/win10.yaml
service_vms:
  docker_compose: path/to/docker_compose_dir
```

- `root`: This key identifies the configuration as a *root-configuration*
- `domain`: List of domains to participate in this scenario
- `service_vms`: Dict with different methods to configure and set up service VMs (the
  possible entries are discussed in the sections below)

## Docker containers

The {py:class}`fortrace.core.simulation_monitor.SimulationMonitor` offers native support
for integration of Docker containers in a scenario.

There are some preliminary requirements to make the Docker containers discoverable for
the VMs. The network of the Docker containers has to use the same IP range as the
libvirt network of the VMs. The [figure below](#fig_libvirt_default_network) shows the
`default` network configuration
of libvirt. Thus, we create a network with the following command, called
**service-vm-net**. It is important to use the driver **macvlan**, so the containers can
connect directly to the physical network.

:::{figure-md} fig_libvirt_default_network
![alt text](../../_static/libvirt_default_network_config.png)

libvirt default network configuration
:::

```{eval-rst}
.. warning::
    If you decide to change the name of the created docker network, make sure to update
    it in the docker-compose file as well.
```

```console
$ docker network create --driver=macvlan --subnet=192.168.122.0/24 -o parent=virbr0 service-vm-net
```

`default` network of libvirt. Notice in this screenshot the name of the created
network device **virbr0** and in the IPv4 configuration section the value of
the network **192.168.122.0/24**, which must be supplied as the value for the
*subnet* option in the command for the creation of the Docker network.

### Docker-compose

The code block below shows the root configuration file of a scenario involving a
docker-compose file.

```yaml
service_vms:
  docker_compose: examples/Service_VM/docker_compose
```

- `docker_compose`: Path, relative to ForTrace++'s root directory, pointing to the
  directory containing the 'compose.yaml' file

The SimulationMonitor automatically runs `docker-compose` in the pre-scenario step. In
the listing below you can see an example docker-compose file, which starts a container
running a Samba server. See the
[Compose file reference](https://docs.docker.com/reference/compose-file/) for more
information about the structure of this file. The content of the configuration depends
mainly on the Docker container. The configurations can regularly be found on
[dockerhub](https://hub.docker.com/), e.g., the config for the
[dockurr/samba](https://hub.docker.com/r/dockurr/samba) container.

Other services can be added by providing more configurations in the `services`
section. Very often you will find the template for the compose file on Dockerhub and can
simply add it to the local compose file.

```{eval-rst}
.. note::

    Just remember to **always** add the ``networks`` entry to the Docker container, so
    it can be discovered by other VMs.
```

```yaml
services:
  samba:
    image: dockurr/samba
    container_name: samba
    environment:
      USER: "samba"
      PASS: "secret"
    ports:
      - "445:445"
    networks:
      - service-vm-net
    volumes:
      - ../shared_dir:/storage
networks:
  service-vm-net:
    external: true
```

#### Docker containers

Custom docker containers can be integrated into the scenario also through the
docker-compose file, below the `services` section. The `networks` section from above has
to remain in place. You can find more details and a good example in
the [Compose Build Specification](https://docs.docker.com/reference/compose-file/build/).

The example below assumes the following directory structure:

```text
docker_compose
|- compose.yaml
|- alpine_test
    |- Dockerfile
```

The content of the `compose.yaml` file:

```yaml
services:
  ping_google:
    build: alpine_test
    networks:
      - service-vm-net
networks:
  service-vm-net:
    external: true
```

- `ping_google`: This is the name of the service to be started by docker-compose
- `build`: Specify here the path to the directory of the Dockerfile, relative to the
  compose.yaml file you are writing this line to (or specify the `context` variable,
  which defaults to `.`.)
- `networks`: Make the container discoverable by other VMs

The content of the custom `Dockerfile` in the directory `alpine_test`:

```dockerfile
FROM alpine:latest

RUN ping -c 32 google.com
```

## Other VMs

This is currently not supported but planned for future releases. One possibility would
be to include the Service VM as a normal domain and boot it right at the beginning, so
it can offer its service.