Fortinet Document Library

Version:


Table of Contents

FortiGate-VM on KVM

Resources

Upgrade Path Tool
  • Select version:
  • 6.0
6.0.0
Download PDF
Copy Link

Cloud-init

The cloud-init service is used for customizing a prepared image of a virtual installation. The cloud-init service is build into the virtual instances of FortiGate-VM that are found on the support site so that they can be used on VM platform that support the use of the service. In order to customize the installation of a new FortiGate-VM instance the seed image from the support site just has to be combined with user data information that is customizes for each new installation.

The use of this service is supported by hypervisor platforms such as QEMU/KVM on most major Linux distributions, as well as BSD, and Hyper-V. It is also supported on a number of cloud based environments such as VMware and AWS.

The cloud-init service can be used to help install different instances based on a common seed image by assigning hostnames, adding SSH keys, and settings particular to the specific installation. Other more general customizations can be added such as the running of post install scripts.

While cloud-init is the service that is used to accomplish the customized installations of virtual machines, various other programs, depending on the platform, are used to create the customized ISOs that used to create the images that will build the FortiGate-VM.

Note

The home page for cloud-init can is at: https://cloud-init.io/

Documentation for the cloud-init program can be found at: https://cloudinit.readthedocs.io/en/latest/index.html

Steps

The basic steps of the process are:

  1. Make sure that the needed software is on the system
  2. Prepare the files to customize the seed image
  3. Collect the customizing files into a single folder
  4. Convert the folder to an ISO image
  5. Install the image into the VM platform

Installing the software

Installing Virt-install

Another required program is virt-install. Among other things, this program allows you to combine the userdata file with the seed image for the FortiGate-VM installation. In order to run virt-install, libvirt and KVM need to be running on the system.You need root privileges to run virt-install

To install virt-install on a Red Hat based system use the command:

sudo yum install libvirt libguestfs-tools virtinst

To install virt-install on a Debian based system use the command:

sudo apt install libvert-bin libguestfs-tools virtinst

You can also install virt-manager using the same methods.

There may be other methods of installing the software but these are two common methods.

Caution

Make sure that after the installation that libvirt-bin is installed and the service is running.

Verifying mkisofs is installed

Some distros like Ubuntu may have a variation of the program called genisoimage, but using the original mkisofs command should still work, as mkisofs is used as an alias for genisoimage in many of the distros.

To verify whether or not you have the utility intalled, enter the command:

mkisofs --version

 

Tooltip

If your system has genisoimage instead you may get a message along the lines of:

mkisofs 2.0.1 is not what you see here. This line is only a fake for too clever GUIs and other frontend applications. In fact, the program is:

genisoimage 1.1.11 (Linux)

Preparing the files for the customized image

Preparing the userdata file

The cloud-init service passes a script to newly created VMs, in this case FortiGate-VM. The title of the file is userdata.txt. All configuration on the FortiGate is done through the configuration file so components of the the scripts follow the syntax of the configuration file or commands being entered through the CLI.

The following example content is from a basic userdata.txt file:

#this is for fgt init config file. Can only handle fgt config.

config sys interface

edit port1

set mode dhcp

set allowaccess http https ssh ping telnet

next

end

config sys dns

set primary 8.8.8.8

unset secondary

end

config sys global

set hostname cloud-init-test

end

License file

The other file that is used to configure the customized install, contains the license key. Take the license key you receive from Fortinet and place it into a text file. This file is named 0000, without any extension.

Preparing the folder

There are no requirements for where the holding folder that will be used to create the new ISO image is placed, but there are requirements as to the folder structure within the folder. The cloud-init needs to find specific content in specific folders in order to work correctly. The folder structure should be as follows:

<holding folder>

/openstack

/content

0000

/latest

userdata.txt

It may seem counter-intuitive to use the folder name openstack in an instance where the target VM platform is not OpenStack, but a number of utilities are common to both OpenStack and KVM environments.

Converting the folder to an ISO image

Once you have your userdata.txt file andthe licence key file, you can create an ISO image containing all of the files that are used to customize the seed image of the FortiGate-VM. This is done using the mkisofs utility.

The syntax of the command is:

mkisofs [options] [-o <filename of new ISO> pathspec [pathspec...]

Some of the options are:

Option

Description

-o <filename> Sets the filename of the resulting ISO image file.

pathspec [pathspec...]

direction to the folder(s) that are to be included in the ISO image file. Separate the paths with a space.

-input-charset Input charset that defines the characters used in local file names. To get a list of valid charset names, use the command mkisofs -input-charset help. To get a 1:1 mapping, you may use default as charset name.

- R

Generate SUSP and RR records using the Rock Ridge protocol to further describe the files on the iso9660 filesystem.

- r

This is like the -R option, but file ownership and modes are set to more useful values. The uid and gid are set to zero, because they are usually only useful on the author's system, and not useful to the client. All the file read bits are set true, so that files and directories are globally readable on the client.

Example:

The iso-folder holds the data structure for the new ISO image. The /home/username/test folder contains the iso-folderfolder.The name for the new ISO image is fgt-bootstrap.iso.

cd /home/username/test

sudo mkisofs -R -r -o fgt-bootstrap.iso iso-folder

Installing the ISO in the VM platform

The following table contains some of the more common options used in setting up a FortiGate-VM image. Not all of them are required. To get a complete listing of the options, at the command prompt, type in the command virt-install --help or virt-install -h.

Option

Description

--connect <option>

This connects the VM image to a non-default VM platform. If one is not specified, libvirt will attempt to choose the most suitable default platform.

Some valid options are:

  • qemu:///system

    Creates KEM and QEMU guests run by the system. This is the most common option.

  • qem:///session

    Creates KEM and QEMU guests run as a regular user.

  • xen:///

    For connecting to Xen.

--name <name>

-n <name>

Name of the new guest virtual machine instance. This must be unique amongst all guests known to the hypervisor on the connection, including those not currently active.

To re-define an existing guest, use the virsh tool

--memory <option>

Memory to allocate for the guest, in MiB. (This deprecates the -r/--ram option.)

Sub options are available, like:

  • maxmemory
  • hugepages
  • hotplugmemorymax
  • hotplugmemoryslots
--vcpus <options>

Number of virtual cpus to configure for the guest.

If 'maxvcpus' is specified, the guest will be able to hotplug up to MAX vcpus while the guest is running, but will startup with VCPUS.

Use --vcpus=? to see a list of all available sub options.

--cdrom <options>

-c <options>

File or device used as a virtual CD-ROM device. It can be path to an ISO image, or to a CDROM device.

It can also be a URL from which to fetch/access a minimal boot ISO image. The URLs take the same format as described for the "--location" argument. If a cdrom has been specified via the "--disk" option, and neither "--cdrom" nor any other install option is specified, the "--disk" cdrom is used as the install media.

--location <options>

-l <options>

Distribution tree installation source. virt-install can recognize certain distribution trees and fetches a bootable kernel/initrd pair to launch the install.

With libvirt 0.9.4 or later, network URL installs work for remote connections. virt-install will download kernel/initrd to the local machine, and then upload the media to the remote host. This option requires the URL to be accessible by both the local and remote host.

--location allows things like --extra-args for kernel arguments, and using --initrd-inject. If you want to use those options with CDROM media, you have a few options:

* Run virt-install as root and do --location ISO

* Mount the ISO at a local directory, and do --location DIRECTORY

* Mount the ISO at a local directory, export that directory over local http, and do --location http://localhost/DIRECTORY

The "LOCATION" can take one of the following forms:

  • http://host/path

    An HTTP server location containing an installable distribution image.

  • ftp://host/path

    An FTP server location containing an installable distribution image.

  • nfs:host:/path or nfs://host/path

An NFS server location containing an installable distribution image. This requires running virt-install as root.

  • DIRECTORY

    Path to a local directory containing an installable distribution image. Note that the directory will not be accessible by the guest after initial boot, so the OS installer will need another way to access the rest of the install media.

  • ISO

    Mount the ISO and probe the directory. This requires running virt-install as root, and has the same VM access caveat as DIRECTORY.

--import Skip the OS installation process, and build a guest around an existing disk image. The device used for booting is the first device specified via "--disk" or "--filesystem".
--disk <options>

Specifies media to use as storage for the guest, with various options.

The general format of a disk string is

--disk opt1=val1,opt2=val2,...

When using multiple options, separate each option with a comma (no spaces before or after the commas).

Example options:

  • size

    size (in GiB) to use if creating new storage

    example: size=10

  • path

    A path to some storage media to use, existing or not. Existing media can be a file or block device.

    Specifying a non-existent path implies attempting to create the new storage, and will require specifying a 'size' value. Even for remote hosts, virt-install will try to use libvirt storage APIs to automatically create the given path.

    If the hypervisor supports it, path can also be a network URL, like http://example.com/some-disk.img . For network paths, they hypervisor will directly access the storage, nothing is downloaded locally.

  • format

    Disk image format. For file volumes, this can be 'raw', 'qcow2', 'vmdk', etc. See format types in http://libvirt.org/storage.html for possible values. This is often mapped to the driver_type value as well.

    If not specified when creating file images, this will default to .qcow2.

    If creating storage, this will be the format of the new image. If using an existing image, this overrides libvirt's format auto-detection.

     

The disk option deprecates -f/--file, -s/--file-size, --nonsparse, and --nodisks.

 

Use --disk=? to see a list of all available sub options.

 

--network <options>

-w <options>

Connect the guest to the host network. The value for <options> can take one of 4 formats:

  • bridge=BRIDGE

    Connect to a bridge device in the host called "BRIDGE". Use this option if the host has static networking config & the guest requires full outbound and inbound connectivity to/from the LAN. Also use this if live migration will be used with this guest.

  • network=NAME

    Connect to a virtual network in the host called "NAME". Virtual networks can be listed, created, deleted using the "virsh" command line tool. In an unmodified install of "libvirt" there is usually a virtual network with a name of "default". Use a virtual network if the host has dynamic networking (eg NetworkManager), or using wireless. The guest will be NATed to the LAN by whichever connection is active.

  • type=direct,source=IFACE[,source_mode=MODE]

    Direct connect to host interface IFACE using macvtap.

  • user

    Connect to the LAN using SLIRP. Only use this if running a QEMU guest as an unprivileged user. This provides a very limited form of NAT.

  • none

    Tell virt-install not to add any default network interface.

 

Use --network=? to see a list of all available sub options.

Complete details at http://libvirt.org/formatdomain.html#elementsNICS

This option deprecates -m/--mac, -b/--bridge, and --nonetworks

--noautoconsole

This stops the system from automatically trying to connect to the guest console. The default behavior is to launch virt-viewer to run a GUI console or run the virsh console command to display a text version of the console.

Example:

This will take the iso image made in the previous file and install it into the VM platform giving the name Example_VM to the FortiGate-VM instance.

virt-install --connect qemu:///system --noautoconsole --name Example_VM --memory 1024 --vcpus 1 --import --disk fortios.qcow2,size=3 --disk fgt-logs.qcow2,size=3 --disk /home/username/test/fgt-bootstrap.iso,device=cdrom,bus=ide,format=raw,cache=none --network bridge=virbr0,model=virtio

What the options are doing in the example:

--connect qemu:///system - connects the image to the QEMU platform.

--noautoconsole - prevents a console from automatically starting up after the installation is completed.

--name Example_VM - sets the name of the FortiGate-VM to Example_VM.

--memory 1024 - allocates 1024 MB (1 GB) of RAM to the VM.

--vcpus 1 - allocates 1 virtual cpu to the VM.

--import - instead of running an installation process, builds a VM around an existing VM image based on the first instance of the --disk setting.

--disk fortios.qcow2 - uses the fortios.qcow2 file to build a disk with the included content, into the VM.

--disk fgt-logs.qcow2,size=3 - Because no file with the name fgt-logs.qcow2 is found, an empty disk is created in the VM with a size of 3 GB.

--disk /home/username/test/fgt-bootstrap.iso,device=cdrom,bus=ide,format=raw,cache=none - sets up a virtual cdrom drive as if it was on an IDE bus holding a virtual CD in it with no cache and the data in RAW format.This virtual CD is based on the file fgt-bootstrap.iso. While is will work if the command is run from the folder that holds the file, you can also include the path to the file.

--network bridge=virbr0,model=virtio - connects theVM to the virtual bridge virbr0 using a virtio model virtual network adapter.

Tooltip

Before running the command, make sure that QEMU/KVM is running properly.

You should be able to start the instance by running the command:

virsh --connect qemu:///system start Example_VM

 

Resources

Cloud-init

The cloud-init service is used for customizing a prepared image of a virtual installation. The cloud-init service is build into the virtual instances of FortiGate-VM that are found on the support site so that they can be used on VM platform that support the use of the service. In order to customize the installation of a new FortiGate-VM instance the seed image from the support site just has to be combined with user data information that is customizes for each new installation.

The use of this service is supported by hypervisor platforms such as QEMU/KVM on most major Linux distributions, as well as BSD, and Hyper-V. It is also supported on a number of cloud based environments such as VMware and AWS.

The cloud-init service can be used to help install different instances based on a common seed image by assigning hostnames, adding SSH keys, and settings particular to the specific installation. Other more general customizations can be added such as the running of post install scripts.

While cloud-init is the service that is used to accomplish the customized installations of virtual machines, various other programs, depending on the platform, are used to create the customized ISOs that used to create the images that will build the FortiGate-VM.

Note

The home page for cloud-init can is at: https://cloud-init.io/

Documentation for the cloud-init program can be found at: https://cloudinit.readthedocs.io/en/latest/index.html

Steps

The basic steps of the process are:

  1. Make sure that the needed software is on the system
  2. Prepare the files to customize the seed image
  3. Collect the customizing files into a single folder
  4. Convert the folder to an ISO image
  5. Install the image into the VM platform

Installing the software

Installing Virt-install

Another required program is virt-install. Among other things, this program allows you to combine the userdata file with the seed image for the FortiGate-VM installation. In order to run virt-install, libvirt and KVM need to be running on the system.You need root privileges to run virt-install

To install virt-install on a Red Hat based system use the command:

sudo yum install libvirt libguestfs-tools virtinst

To install virt-install on a Debian based system use the command:

sudo apt install libvert-bin libguestfs-tools virtinst

You can also install virt-manager using the same methods.

There may be other methods of installing the software but these are two common methods.

Caution

Make sure that after the installation that libvirt-bin is installed and the service is running.

Verifying mkisofs is installed

Some distros like Ubuntu may have a variation of the program called genisoimage, but using the original mkisofs command should still work, as mkisofs is used as an alias for genisoimage in many of the distros.

To verify whether or not you have the utility intalled, enter the command:

mkisofs --version

 

Tooltip

If your system has genisoimage instead you may get a message along the lines of:

mkisofs 2.0.1 is not what you see here. This line is only a fake for too clever GUIs and other frontend applications. In fact, the program is:

genisoimage 1.1.11 (Linux)

Preparing the files for the customized image

Preparing the userdata file

The cloud-init service passes a script to newly created VMs, in this case FortiGate-VM. The title of the file is userdata.txt. All configuration on the FortiGate is done through the configuration file so components of the the scripts follow the syntax of the configuration file or commands being entered through the CLI.

The following example content is from a basic userdata.txt file:

#this is for fgt init config file. Can only handle fgt config.

config sys interface

edit port1

set mode dhcp

set allowaccess http https ssh ping telnet

next

end

config sys dns

set primary 8.8.8.8

unset secondary

end

config sys global

set hostname cloud-init-test

end

License file

The other file that is used to configure the customized install, contains the license key. Take the license key you receive from Fortinet and place it into a text file. This file is named 0000, without any extension.

Preparing the folder

There are no requirements for where the holding folder that will be used to create the new ISO image is placed, but there are requirements as to the folder structure within the folder. The cloud-init needs to find specific content in specific folders in order to work correctly. The folder structure should be as follows:

<holding folder>

/openstack

/content

0000

/latest

userdata.txt

It may seem counter-intuitive to use the folder name openstack in an instance where the target VM platform is not OpenStack, but a number of utilities are common to both OpenStack and KVM environments.

Converting the folder to an ISO image

Once you have your userdata.txt file andthe licence key file, you can create an ISO image containing all of the files that are used to customize the seed image of the FortiGate-VM. This is done using the mkisofs utility.

The syntax of the command is:

mkisofs [options] [-o <filename of new ISO> pathspec [pathspec...]

Some of the options are:

Option

Description

-o <filename> Sets the filename of the resulting ISO image file.

pathspec [pathspec...]

direction to the folder(s) that are to be included in the ISO image file. Separate the paths with a space.

-input-charset Input charset that defines the characters used in local file names. To get a list of valid charset names, use the command mkisofs -input-charset help. To get a 1:1 mapping, you may use default as charset name.

- R

Generate SUSP and RR records using the Rock Ridge protocol to further describe the files on the iso9660 filesystem.

- r

This is like the -R option, but file ownership and modes are set to more useful values. The uid and gid are set to zero, because they are usually only useful on the author's system, and not useful to the client. All the file read bits are set true, so that files and directories are globally readable on the client.

Example:

The iso-folder holds the data structure for the new ISO image. The /home/username/test folder contains the iso-folderfolder.The name for the new ISO image is fgt-bootstrap.iso.

cd /home/username/test

sudo mkisofs -R -r -o fgt-bootstrap.iso iso-folder

Installing the ISO in the VM platform

The following table contains some of the more common options used in setting up a FortiGate-VM image. Not all of them are required. To get a complete listing of the options, at the command prompt, type in the command virt-install --help or virt-install -h.

Option

Description

--connect <option>

This connects the VM image to a non-default VM platform. If one is not specified, libvirt will attempt to choose the most suitable default platform.

Some valid options are:

  • qemu:///system

    Creates KEM and QEMU guests run by the system. This is the most common option.

  • qem:///session

    Creates KEM and QEMU guests run as a regular user.

  • xen:///

    For connecting to Xen.

--name <name>

-n <name>

Name of the new guest virtual machine instance. This must be unique amongst all guests known to the hypervisor on the connection, including those not currently active.

To re-define an existing guest, use the virsh tool

--memory <option>

Memory to allocate for the guest, in MiB. (This deprecates the -r/--ram option.)

Sub options are available, like:

  • maxmemory
  • hugepages
  • hotplugmemorymax
  • hotplugmemoryslots
--vcpus <options>

Number of virtual cpus to configure for the guest.

If 'maxvcpus' is specified, the guest will be able to hotplug up to MAX vcpus while the guest is running, but will startup with VCPUS.

Use --vcpus=? to see a list of all available sub options.

--cdrom <options>

-c <options>

File or device used as a virtual CD-ROM device. It can be path to an ISO image, or to a CDROM device.

It can also be a URL from which to fetch/access a minimal boot ISO image. The URLs take the same format as described for the "--location" argument. If a cdrom has been specified via the "--disk" option, and neither "--cdrom" nor any other install option is specified, the "--disk" cdrom is used as the install media.

--location <options>

-l <options>

Distribution tree installation source. virt-install can recognize certain distribution trees and fetches a bootable kernel/initrd pair to launch the install.

With libvirt 0.9.4 or later, network URL installs work for remote connections. virt-install will download kernel/initrd to the local machine, and then upload the media to the remote host. This option requires the URL to be accessible by both the local and remote host.

--location allows things like --extra-args for kernel arguments, and using --initrd-inject. If you want to use those options with CDROM media, you have a few options:

* Run virt-install as root and do --location ISO

* Mount the ISO at a local directory, and do --location DIRECTORY

* Mount the ISO at a local directory, export that directory over local http, and do --location http://localhost/DIRECTORY

The "LOCATION" can take one of the following forms:

  • http://host/path

    An HTTP server location containing an installable distribution image.

  • ftp://host/path

    An FTP server location containing an installable distribution image.

  • nfs:host:/path or nfs://host/path

An NFS server location containing an installable distribution image. This requires running virt-install as root.

  • DIRECTORY

    Path to a local directory containing an installable distribution image. Note that the directory will not be accessible by the guest after initial boot, so the OS installer will need another way to access the rest of the install media.

  • ISO

    Mount the ISO and probe the directory. This requires running virt-install as root, and has the same VM access caveat as DIRECTORY.

--import Skip the OS installation process, and build a guest around an existing disk image. The device used for booting is the first device specified via "--disk" or "--filesystem".
--disk <options>

Specifies media to use as storage for the guest, with various options.

The general format of a disk string is

--disk opt1=val1,opt2=val2,...

When using multiple options, separate each option with a comma (no spaces before or after the commas).

Example options:

  • size

    size (in GiB) to use if creating new storage

    example: size=10

  • path

    A path to some storage media to use, existing or not. Existing media can be a file or block device.

    Specifying a non-existent path implies attempting to create the new storage, and will require specifying a 'size' value. Even for remote hosts, virt-install will try to use libvirt storage APIs to automatically create the given path.

    If the hypervisor supports it, path can also be a network URL, like http://example.com/some-disk.img . For network paths, they hypervisor will directly access the storage, nothing is downloaded locally.

  • format

    Disk image format. For file volumes, this can be 'raw', 'qcow2', 'vmdk', etc. See format types in http://libvirt.org/storage.html for possible values. This is often mapped to the driver_type value as well.

    If not specified when creating file images, this will default to .qcow2.

    If creating storage, this will be the format of the new image. If using an existing image, this overrides libvirt's format auto-detection.

     

The disk option deprecates -f/--file, -s/--file-size, --nonsparse, and --nodisks.

 

Use --disk=? to see a list of all available sub options.

 

--network <options>

-w <options>

Connect the guest to the host network. The value for <options> can take one of 4 formats:

  • bridge=BRIDGE

    Connect to a bridge device in the host called "BRIDGE". Use this option if the host has static networking config & the guest requires full outbound and inbound connectivity to/from the LAN. Also use this if live migration will be used with this guest.

  • network=NAME

    Connect to a virtual network in the host called "NAME". Virtual networks can be listed, created, deleted using the "virsh" command line tool. In an unmodified install of "libvirt" there is usually a virtual network with a name of "default". Use a virtual network if the host has dynamic networking (eg NetworkManager), or using wireless. The guest will be NATed to the LAN by whichever connection is active.

  • type=direct,source=IFACE[,source_mode=MODE]

    Direct connect to host interface IFACE using macvtap.

  • user

    Connect to the LAN using SLIRP. Only use this if running a QEMU guest as an unprivileged user. This provides a very limited form of NAT.

  • none

    Tell virt-install not to add any default network interface.

 

Use --network=? to see a list of all available sub options.

Complete details at http://libvirt.org/formatdomain.html#elementsNICS

This option deprecates -m/--mac, -b/--bridge, and --nonetworks

--noautoconsole

This stops the system from automatically trying to connect to the guest console. The default behavior is to launch virt-viewer to run a GUI console or run the virsh console command to display a text version of the console.

Example:

This will take the iso image made in the previous file and install it into the VM platform giving the name Example_VM to the FortiGate-VM instance.

virt-install --connect qemu:///system --noautoconsole --name Example_VM --memory 1024 --vcpus 1 --import --disk fortios.qcow2,size=3 --disk fgt-logs.qcow2,size=3 --disk /home/username/test/fgt-bootstrap.iso,device=cdrom,bus=ide,format=raw,cache=none --network bridge=virbr0,model=virtio

What the options are doing in the example:

--connect qemu:///system - connects the image to the QEMU platform.

--noautoconsole - prevents a console from automatically starting up after the installation is completed.

--name Example_VM - sets the name of the FortiGate-VM to Example_VM.

--memory 1024 - allocates 1024 MB (1 GB) of RAM to the VM.

--vcpus 1 - allocates 1 virtual cpu to the VM.

--import - instead of running an installation process, builds a VM around an existing VM image based on the first instance of the --disk setting.

--disk fortios.qcow2 - uses the fortios.qcow2 file to build a disk with the included content, into the VM.

--disk fgt-logs.qcow2,size=3 - Because no file with the name fgt-logs.qcow2 is found, an empty disk is created in the VM with a size of 3 GB.

--disk /home/username/test/fgt-bootstrap.iso,device=cdrom,bus=ide,format=raw,cache=none - sets up a virtual cdrom drive as if it was on an IDE bus holding a virtual CD in it with no cache and the data in RAW format.This virtual CD is based on the file fgt-bootstrap.iso. While is will work if the command is run from the folder that holds the file, you can also include the path to the file.

--network bridge=virbr0,model=virtio - connects theVM to the virtual bridge virbr0 using a virtio model virtual network adapter.

Tooltip

Before running the command, make sure that QEMU/KVM is running properly.

You should be able to start the instance by running the command:

virsh --connect qemu:///system start Example_VM