Fortinet black logo

Cloud-init

Copy Link
Copy Doc ID a9b95302-6954-11ea-9384-00505692583a:767662
Download PDF

Cloud-init

You can use the cloud-init service for customizing a prepared image of a virtual installation. The cloud-init service is built into the virtual instances of FortiGate-VM that are found on the support site so that you can use them on a VM platform that supports the use of the service. To customize the installation of a new FortiGate-VM instance, you must combine the seed image from the support site with user data information customized for each new installation.

Hypervisor platforms such as QEMU/KVM, BSD, and Hyper-V support the use of this service on most major Linux distributions. A number of cloud-based environments such as VMware and AWS also support it.

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

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

Note

For more information, see the cloud-init documentation.

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 on the VM platform.

Installing the software

For instructions on installing software, you should refer to the installation instructions for your desired Linux distribution. For example, if using Red Hat Enterprise Linux, see Product Documentation for Red Hat Enterprise Linux.

You must install an environment that can run cloud-init and mkisofs.

Preparing the files for the customized image

Preparing the user_data file

The cloud-init service passes a script to newly created VMs, in this case FortiGate-VM. The title of the file is user_data. 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 user_data 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

user_data

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 user_data file and the license 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>

New guest VM instance name. This must be unique amongst all guests known to the hypervisor on the connection, including those not currently active.

To redefine 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 start up 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 libvirt: Storage Management 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.

See details at libvirt: Domain XML format - Network interfaces.

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 the VM to the virtual bridge virbr0 using a virtio model virtual network adapter.
Note

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

Cloud-init

You can use the cloud-init service for customizing a prepared image of a virtual installation. The cloud-init service is built into the virtual instances of FortiGate-VM that are found on the support site so that you can use them on a VM platform that supports the use of the service. To customize the installation of a new FortiGate-VM instance, you must combine the seed image from the support site with user data information customized for each new installation.

Hypervisor platforms such as QEMU/KVM, BSD, and Hyper-V support the use of this service on most major Linux distributions. A number of cloud-based environments such as VMware and AWS also support it.

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

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

Note

For more information, see the cloud-init documentation.

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 on the VM platform.

Installing the software

For instructions on installing software, you should refer to the installation instructions for your desired Linux distribution. For example, if using Red Hat Enterprise Linux, see Product Documentation for Red Hat Enterprise Linux.

You must install an environment that can run cloud-init and mkisofs.

Preparing the files for the customized image

Preparing the user_data file

The cloud-init service passes a script to newly created VMs, in this case FortiGate-VM. The title of the file is user_data. 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 user_data 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

user_data

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 user_data file and the license 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>

New guest VM instance name. This must be unique amongst all guests known to the hypervisor on the connection, including those not currently active.

To redefine 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 start up 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 libvirt: Storage Management 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.

See details at libvirt: Domain XML format - Network interfaces.

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 the VM to the virtual bridge virbr0 using a virtio model virtual network adapter.
Note

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