# Building Facts for distribution

There is `Vagrantfile` to automatically populate `facts` for all supported operating systems by spawning a new VM and launches a provisioning scripts.

## Vagrant

[Vagrant](https://www.vagrantup.com/) is a tool for creating reproducible virtual machine builds.
We use it to ensure facts are generated as similarly as possible every time.

Vagrant starts by downloading a `box` - a pre-build skeleton of a virtual machine - and then running multiple steps on it.
Our workflow generally looks like this:

1. One or more setup steps to make the VM ready to install puppet and generate facts (for example, setting up the network)
1. Calling the `get_facts` script which installs multiple versions of Puppet and generates facts for multiple versions of facter.
1. Shutting down the VM (Vagrant doesn't do this automatically).

### Plugins

The vagrant timezone plugin is recommended to prevent unnecessary changes to timezone facts:

```
vagrant plugin install vagrant-timezone
```

## Hypervisor

The distributed facts are built using [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
Building the facts will work with other visualization hosts, but will produce different results (eg. IP ranges) that will break spec tests.

VirtualBox versions 6 and 7 have been tested.
The GPLv3 version of VirtualBox is sufficient - the proprietary `Oracle VM VirtualBox Extension Pack` is not required.

## Building Facts

To build facts, specify an operating system or list of systems.

```
$ vagrant up --provision debian-11-x86_64
$ vagrant up --provision debian-11-x86_64 debian-12-x86_64 redhat-8-x86_64 redhat-9-x86_64
```

Windows systems are also available.

```
$ vagrant up --provision windows-server-2019-x86_64 windows-server-2022-x86_64 windows-10-x86_64 windows-11-x86_64
```

You can build a list of supported facter versions and operating systems:

```
$ bundle exec rake database
```

These are also included in our YARD documentation build.

### Converted Facts

Not all facts can (or should) be built from VMs.
It often isn't necessary to run a separate VM to create some facts that won't be significantly different for existing facts.
Some operating systems are harder to run in VMs.

#### Create i386 facts from x86_64's ones

```
for file in facts/*/*-x86_64.facts; do cat $file | sed -e 's/x86_64/i386/' -e 's/amd64/i386/' > $(echo $file | sed 's/x86_64/i386/'); done
```

## Legacy Facts

*NOTE*: When using Facter version 4, by default some "legacy facts" are hidden from the output.
To generate a fact set with the legacy facts use the command `puppet facts show --show-legacy`

## OS-Specific Notes

### Ubuntu 18.04

The default Ubuntu 18.04 `box` creates a console log file (ubuntu-bionic-18.04-cloudimg-console.log).
Newer Ubuntu `boxes` don't do this.
This behavior can be modified by changing the `box` configuration: `config.vm.provider "virtualbox" do |vb|  vb.customize ["modifyvm", :id, "--uartmode1", "disconnected"]  end`

### Windows

There are publicly available Windows `boxes` for Vagrant.

We currently use publicly-availble `boxes` from Vagrant Community, but we also included packer templates so you can build your own (currently outdated).

run `packer build <file>.json`
followed by `vagrant add <boxname> <boxfile>`

Once the box is added, change the `Vagrantfile` to use your new `box` and run `vagrant up <windows_os_name>`

## CentOS

To ensure proper shared folder functionality on CentOS Vagrant boxes, VirtualBox Guest Additions must be installed. The `vagrant-vbguest` plugin, previously used for this purpose, is now archived and suffers from dependency conflicts. Therefore, we've implemented a custom `vbguest_install.sh` script to manage the installation process. This script performs a check for the vboxsf kernel module, which is a key component of the Guest Additions. If the module is not found, the script installs the necessary Guest Additions. Due to this installation step, the first provisioning run will primarily focus on installing the Guest Additions, followed by other provisioning tasks and a VM shutdown. A second run, with the mount_synced_folder parameter, will then successfully mount the /vagrant shared folder, as the Guest Additions will now be present.

```shell
vagrant up --provision centos-stream9-x86_64
mount_synced_folder=true vagrant up --provision centos-stream9-x86_64
```
