https://github.com/f5devcentral/f5-bigip-image-generator

Generate custom images for F5 BIG-IP.
https://github.com/f5devcentral/f5-bigip-image-generator

Last synced: 18 days ago
JSON representation

Generate custom images for F5 BIG-IP.

Host: GitHub
URL: https://github.com/f5devcentral/f5-bigip-image-generator
Owner: f5devcentral
License: apache-2.0
Created: 2019-08-20T19:57:27.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2023-06-12T18:04:56.000Z (almost 3 years ago)
Last Synced: 2025-04-11T21:02:05.691Z (12 months ago)
Language: Shell
Homepage:
Size: 483 KB
Stars: 35
Watchers: 17
Forks: 20
Open Issues: 13
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Welcome to the F5 BIG-IP Image Generator Tool

### ALERT: This tool has reached end of software development and is no longer supported with active updates. F5 will not provide software fixes (hotfixes) or consulting services for a version that has reached the EoSD milestone. For details, consult the [K5903][46] article.

You will find the following information:

* [Introduction](#introduction)
* [Prerequisites](#prerequisites)
* [Image Generator prerequisites](#image-generator-prerequisites)
* [Supported platforms and prerequisites](#supported-platforms-and-prerequisites)
* [Environment recommendations](#environment-recommendations)
* [Setup guide](#setup-guide)
* [Install image generator](#install-image-generator)
* [Run the setup script](#run-the-setup-script)
* [Build the image from the command line](#build-the-image-from-the-command-line)
* [Docker container setup](#docker-container-setup)
* [User guide](#user-guide)
* [Create config file](#create-config-file)
* [Monitor progress](#monitor-progress)
* [Locate files](#locate-files)
* [Troubleshooting guide](#troubleshooting-guide)
* [Support guide](#support-guide)
* [Known issues](#known-issues)
* [Appendix](#appendix)
* [Telemetry sample output data](#telemetry-sample-output-data)

## Introduction

The F5 Virtual Edition (VE) team developed the F5 BIG-IP Image Generator internally to do the following:

* Create custom images from the .ISO file for F5 BIG-IP VE releases or for hot-fixes that are not available on the various public cloud marketplaces.
* Provide pre-deployment file customization of BIG-IP (for example, SSH keys, trusted certificates, custom packages, and so forth).
* Automatically publish images to public cloud providers:

* [Alibaba][38] - consult the [Alibaba Quick Start Guide][26].
* [AWS][39] - consult the [AWS Quick Start Guide][6].
* [Azure][40] - consult the [Azure Quick Start Guide][7].
* [GCE ][41] - consult the [Google Quick Start Guide][8].

* Simplify deployment workflows, such as encrypting custom images in AWS (prevents launching an instance in the marketplace first).

##### SECURITY WARNING
----------------------
It is your responsibility to:

1. Secure and restrict access to the environment on which you run the VE Image Generator tool, and in your cloud environment.
2. Remove any sensitive data on the created image PRIOR to automatically publishing the image to the cloud.

---------------------------------

## Prerequisites
This section provides prerequisites for running the F5 Image Generator, creating virtual images, and for supported cloud providers.

#### Image Generator prerequisites
The following table lists system requirements for using the Image Generator to create virtualized images of the following supported BIG-IP ISO packages:

| Component | Version | Recommended System Requirements|
|---------------------------| :---------------------------------------------------------------| :------------------------------|
| F5 BIG-IP Image Generator | 1.0 | - **Memory**: 4GB memory
- **Disk space**: depends on number of images you want to create.
See following BIG-IP VE system requirements.|
| [F5 BIG-IP VE][1] | - BIG-IP 13.1.0.2+ (except Alibaba)
- BIG-IP 14.X
- BIG-IP 14.1.0.3+ (for Alibaba ONLY)
- BIG-IP 15.X | A minimum of 20GB per image
The image generator uses sparse file systems, which results in local images that are smaller than deployed images. For more information about images and deployed image sizes, see the [K14946][33] article.|
| Open Virtualization Format Tool (ovftool) | 4.3.0 | If you deploy in VMware (ESX/i Server) or AWS cloud, you must install the [ovftool][22] for creating the virtual disk. |

#### Supported platforms and prerequisites

The following table lists supported operating systems:

| Operating System | Version | F5 IGT Version
|:-------------------------------------|:--------------------------------|:-------------------------------
| Ubuntu (F5 Image Generator-validated)| 18.04 LTS operating system | 1.0+
| Ubuntu (F5 Image Generator-validated)| 20.04 LTS operating system | 1.16+
| Alpine (F5 Image Generator-validated)| 3.11.5 | 1.0-1.17
| Alpine (F5 Image Generator-validated)| 3.15.4 | 1.18+

These operating systems require a unified [setup script][2] containing the following tools package:

* Git
* Python 3.x
* Cloud provider SDK tools

The following table lists supported public and private cloud platforms as well as account setup requirements:

| Cloud Provider | Requirements
|---------------------------| :---------------------------------------------------------------|
|Alibaba | BIG-IP 14.1.0.3+ and sufficient permissions to create or describe the following resources:
- Credentials/API Keys
- SSH Keys uploaded
- Application credentials
- [OSS, Bucket storage container][29]
(See this [Alibaba article][30] for more Resource Access Manager (RAM) information.)|
| AWS | Sufficient permissions to create or describe the following resources:
- credentials/API Keys
- [S3 Bucket Storage Container][12]
- Install the [ovftool][22] for creating the virtual disk.
- IAM Role with import permissions
(See this [AWS article][3] for more VM Import Service Role information.) |
| Azure | Sufficient permissions to create or describe the following resources:
- Credentials/API Keys
- [Storage Container][11] and [storage connection strings][28]
(For more information, see this article about [creating a service principle][10].)|
| Google Cloud (GCE) | Sufficient permissions to create or describe the following resources:
- Credentials/API Keys
- Application credentials
- [Storage Container][13]
(See this [GCE article][9] for more service account information.)|

The following supported platforms require no specific configuration:

* **QCOW2** (KVM Red Hat Enterprise Linux/CentOS; OpenStack) - See [VE Setup for KVM][18] for more information.
* **VHD** (Microsoft Hyper-V) - See [VE Setup for Hyper-V][17] for more information.
* **VMware** (ESX/i Server) - See [VE Setup for vSphere][14] for more information. For advanced setup, see [creating ISO using TMOS-cloud-init][15] and [configuring user data][16].

##### Virtualization requirements
The Image Generator tool generates a virtual disk image from the BIG-IP product ISO. During the creation, you can specify a cloud provider. Doing so generates a virtual disk image, automatically uploads that disk to that cloud provider, and creates a virtual machine image. Options include:

* **Enabling virtualization** creates a virtual disk in **10-15 minutes** (RECOMMENDED).
* Disabling virtualization creates a virtual disk in 1-2 hours.

##### Tip
----------
F5 recommends running the Image Generator Tool in environments where virtualization is enabled (for example, **AWS i3.metal** instance or [GCE's KVM licensing flag for instances][25]).

Execution times differ between cloud providers, usually taking 5-20 minutes depending on the image size. The BIG-IP Image Generator will display a **warning**, if you run the script in an **insufficient** environment **without virtualization** support.

For more information about virtualization support, see [KVM Virtualization][4].

-------------------------------------------------------------------------------

### Environment recommendations
Due to several required tools/SDKs to generate images, F5 Inc. recommends using a standalone machine/environment for the BIG-IP Image Generator. F5 provides a [setup script][2] to assist in setting up that environment. The script installs Python packages in a virtual environment to isolate them from the rest of the system; however, the script also installs other tools, such as zip, directly into the base environment. These packages are not downloaded from F5 repositories, but come from the respective project repositories. It is your responsibility to verify that these packages are safe to use.

## Setup guide

This section provides steps for installing the generator tool, running the setup script, and building an image file. The setup script installs tools/SDKs required to generate images for all supported platforms, and takes several minutes to complete. During this setup process, certain services will require a restart.

### Dowload image generator source code

Do one of the following to download the BIG-IP Image Generator source code to your Ubuntu VM:

* Clone

`$ git init`

`$ git clone https://github.com/f5devcentral/f5-bigip-image-generator.git`

`$ git clone git@github.com:f5devcentral/f5-bigip-image-generator.git`

`$ cd f5-bigip-image-generator`

`$ git checkout v1.0` (Checkout the tag associated with the release version you want to install.)

* Download from HTTPS

1. Point your browser to ``https://github.com/f5devcentral/f5-bigip-image-generator``, open the branch with the tag associated with the release you want to install, click **Download**, and then select the file type (zip or tar.gz) you want to download. Or, download using curl, for example:

`curl -OL https://github.com/f5devcentral/f5-bigip-image-generator/archive/refs/tags/v1.16.zip`

2. Type the following (this example uses tar.gz file type) to extract the source code:

`unzip v1.16.zip`

`or `

`tar -xzvf v1.16.tar.gz`

`cd f5-bigip-image-generator-1.16`

### Install Image Generator running the setup script

1. To run the [setup script][2], type: `./setup-build-env`

This script installs all tools required for all supported platforms.

To reduce the footprint required for development tools that you install based on the platform for which you are building, use the supported Platform variable options. For example:

* ``./setup-build-env --qcow2``
* ``./setup-build-env --aws``
* ``./setup-build-env --vhd``

Consult the [User Guide](#create-config-file) for complete ``PLATFORM`` parameter descriptions.

Other options include:

* `--add-dev-tools` - installs additional tools used during development, such as pylint, shellcheck, and bats

2. Restart your computer, or log out, and then log back into your system.
3. To view the Image Generator operating environment type:

``./build-image --info``

This will collect information such as, installed software on the build machine.

### Build the BIG-IP image

1. To build the image, type:

`$ ./build-image -i ~/images/BIGIP-15.1.4-0.0.47.iso -p qcow2 -m ltm -b 1`

To build an image using a configuration file, see the [User Guide](#create-config-file).

### Docker container setup

Alternatively, to avoid installing programs to your environment and enable running simultaneous image-builds on the same computer, you can utilize the [F5 container on Docker Hub][34] that provides a convenient pre-built runtime with many of the tool’s package dependencies pre-installed (with the exception of VMware’s ovftool). For complete information, consult [Docker Hub][34].

## User guide

This section provides steps for creating a [config.yaml][5] file that defines frequently used settings and shared variables that the BIG-IP Image Generator will use for creating custom images, running the Image Generator tool, and then customizing log details for monitoring progress.

##### TIP

---------------------------------------------------

Before creating your configuration file for generating your image, consult the [K14946][33] article about image disk sizes for BIG-IP VE versions and template types. For example:

* LTM_1SLOT for BIG-IP VE 15.X deployed image disk size is 10 GB
* LTM for BIG-IP VE 14.X disk deployed image disk size is 37 GB
* ALL_1SLOT for BIG-IP VE 13.X deployed image disk size is 60 GB

To define the LTM and ALL templates, use the MODULES parameter in the following table, and to define the 1SLOT or 2SLOT use the BOOT_LOCATIONS parameter in the following table.

----------------------------------------------------

#### Create config file

1. Create a [config.yaml][5] for frequently used settings and shared variables. The BIG-IP Image Generator will only use the variable definitions applicable to the specified provider and ignores other variables.

2. Define the following shared parameters or set as an environment variable. Optionally, use these parameters on the command line with leading dashes (for example, `--platform`). In some cases, you can use a shorthand flag. If a parameter is defined in multiple places, then the priority in descending order is:
command line > configuration file > environment variable. To access the Image Generator help file, run `-h/--help`.

|Parameter|Flag|Required|Values|Description|
|:--------|:---|:-------|:-----|:----------|
| ADD_OVA_EULA | | No | |Full path or URL to a text-based EULA that you want added to VMware OVA images. |
|ARTIFACTS_DIR | | No | | Enter a directory (either absolute or relative path) where newly created artifacts will reside. If blank, the tool will auto-create this directory.|
|BOOT_LOCATIONS|-b|Yes|[1\2]|Number of boot locations used in the source ISO file.|
|CLOUD_IMAGE_NAME| |No|[value]|The name of the generated cloud image. The name is subject to cloud provider naming restrictions and is not guaranteed to succeed. If you provide no name, then one is generated automatically based on the detected properties of the source ISO file.|
|CONFIG_FILE|-c|No|[value]|Full path to a YAML configuration file containing a list of parameter key/value pairs used during image generation.|
|CONSOLE_DEVICES | |No|[value]|Used to identify the locally attached devices to your generated VE image. The default value ``ttyS0`` is required to build images. Start numbering your serial devices/consoles using ``ttyS1``.|
|DISABLE_SPLASH| |No|[value]|Used to disable the boot screen, which can cause automation processes to stall.|
|DISABLE_TELEMETRY| |No|[value]|Disable the telemetry feature used to collect platform and usage information for product improvement purposes. When disabled, data is stored locally for debugging purposes.|
|EHF_ISO|-e|No|[value]|Full path or URL to an engineering hotfix ISO file for installation on top of the existing ISO file.|
|EHF_ISO_SIG|-x|No|[value]|Full path or URL to an engineering hotfix ISO signature file used to validate the engineering hotfix ISO.|
|HELP|-h|No| |Print help and usage information, and then exit the program.|
|IGNORE_DOWNLOAD_URL_TLS| |No| |Ignore TSL certificate verification when downloading files.|
|IMAGE_DIR| |No|[value]|The directory where you want generated images to reside. Provide either an absolute path or a relative path. If this directory does not exist, the tool will create it.|
|HYPERVISOR_IMAGE_NAME| |No| [value]|Name of the generated non-cloud image. If blank, then a name is generated automatically, based on the detected properties of the source ISO file.|
|IMAGE_SIG_ENCRYPTION_TYPE| |No|[value]|Encryption type to use when signing images.|
|IMAGE_SIG_PRIVATE_KEY| |No|[value]|Path to private key file used to sign images.|
|IMAGE_SIG_PUBLIC_KEY| |No|[value]|Path to public key file used to verify images.|
|IMAGE_TAGS| |No|[value]|List of key value pairs to set as tags/labels for the image.|
|IMAGE_TAGS_EXCLUDE| |No| [value]|List of keys to exclude from the tags/labels for the image.|
|INFO| |No|[value]|Display image generator environment information.|
|ISO|-i|Yes|[value]|Full path or URL to a BIG-IP ISO file used as a basis for image generation.|
|ISO_SIG|-s|No|[value]|Full path or URL to an ISO signature file used to validate the ISO.|
|ISO_SIG_VERIFICATION_ENCRYPTION_TYPE| |No|[value]|Encryption type to use when signing/verifying ISO or Virtual disks|
|ISO_SIG_VERIFICATION_PUBLIC_KEY| |No|[value]|Path to public key file used to verify an ISO.|
|LOG_FILE| |No|[value]|Log filename that overrides the default log filename created in the logs directory. You can use a full path, directory, or filename. If full path, then the log file uses the full path. If directory, then the image generator creates a new log file in the specified directory. If filename, then the tool creates a log file in the logs directory using the specified filename.|
|LOG_LEVEL| |No|[CRITICAL \ ERROR \ WARNING \ INFO \ DEBUG \ TRACE]|Log level to use for the log file, indicating the lowest message severity level that can appear in the log file.|
|MODULES|-m|Yes|[all\ltm]|BIG-IP components supported by the specified image.|
|NO_UPLOAD| | No | | Create the cloud image without uploading to the cloud.|
|OUTPUT_JSON_FILE| | No | [value] | Define this parameter to produce an output json file with image build environment information (for example, image name and image ID) by providing the json filename and/or path.|
|OVA_PROP_NET_USER| | No | [value] | Adds a [block of text][36] into the .ovf file, enabling VMware to apply the mgmt IP and passwords. The script will check for the following BIG-IP versions that support IPv6: 14.1.4.1+, 15.1.3+, 16.0.1.1+, and 16.1+|
|PLATFORM|-p|Yes|[alibaba \ aws \ azure \ gce \ qcow2 \ vhd \ vmware]|The target platform for generated images.|
|REUSE| |No| |Keep\Reuse local files created by previous runs of the same [PLATFORM, MODULES, BOOT_LOCATIONS] combination.|
|UPDATE_IMAGE_FILES| |No|[value]|Files you want injected into the image. For each of the injections, REQUIRED values include **source** (file, directory, or URL) and **destination** (absolute full path), and an OPTIONAL **mode** (a string of file [chmod][32] permissions flag consisting of 1-4 octal digits for read/write/execute).|
|UPDATE_LV_SIZES| |No|[value]|Increase the sizes (MiB) of the following logical volumes (LV): appdata, config, log, shared, and var. This is a dictionary mapping the LV name to the new LV size. Define the size using an integer representing the number of MiBs (for example, "appdata":32000).|
|VERSION|-v|No| |Print version information, and then exit the program.|

3. When specifying a cloud provider, supply the following provider-specific information:

* [Alibaba][42]
* [AWS][43]
* [Azure][44] - When creating BIG-IP images in Azure, you must also [create an application][31]. Consult the [Azure Quick Start Guide][40] for more information.
* [GCE ][45]

The following platforms do not currently require platform-specific configuration:

* QCOW2 (KVM Red Hat Enterprise Linux/CentOS; OpenStack)
* VHD (Microsoft Hyper-V)
* VMware (ESX/i Server)

4. OPTIONAL: The Image Generator tool can inject additional files (for example, keys, certs, language extension (lx) packages like [Declarative Onboarding][37] startup scripts, and optionally designate file permissions into the virtual disk image to allow for image customization. You can do this using the command line; however, the syntax is simpler using the configuration file:

```
UPDATE_IMAGE_FILES:
- source: "/home/ubuntu/custom/trusted-ca.pem"
destination: "/config/ssl/ssl.crt/trusted-ca.pem"
- source: "/home/ubuntu/custom/authorized_keys"
destination: "/home/admin/.ssh/authorized_keys"
- source: "https://github.com/F5Networks/f5-declarative-onboarding/releases/download/v1.27.0/f5-declarative-onboarding-1.27.0-6.noarch.rpm"
destination: "/var/config/rest/downloads/f5-declarative-onboarding-1.27.0-6.noarch.rpm"
- source: "https://github.com/F5Networks/f5-appsvcs-extension/releases/download//v3.34.0/f5-appsvcs-3.34.0-4.noarch.rpm"
destination: "/var/config/rest/downloads/f5-appsvcs-3.34.0-4.noarch.rpm"
- source: "https://github.com/F5Networks/f5-telemetry-streaming/releases/download/v1.26.0/f5-telemetry-1.26.0-3.noarch.rpm"
destination: "/var/config/rest/downloads/f5-telemetry-1.26.0-3.noarch.rpm"
- source: "https://github.com/F5Networks/f5-bigip-runtime-init/releases/download/1.4.1/f5-bigip-runtime-init-1.4.1-1.gz.run"
destination: "/var/config/rest/downloads/f5-bigip-runtime-init-1.4.1-1.gz.run"
- source: "/home/ubuntu/custom/startup-script.sh"
destination: "/config/cloud/startup-script.sh"
mode: "0755"
- source: "/home/ubuntu/custom/startup"
destination: "/config/startup"
```

##### IMPORTANT
-----------------------
Avoid overwriting existing system related files unless directed by F5 Inc. Place these additional files in typical locations where you store customizations. For example, place files in the `/var/config/rest/downloads/` directory where they can be included in the user configuration set (UCS) file or in the `/shared` directory, so each slot can access the customizations. Otherwise, you will lose these changes during an upgrade. For more information about UCS, see the *file inclusion into UCS archives* topic on [AskF5][24].

--------------------------------

5. OPTIONAL: The default behavior of the Image Generator does NOT attempt to use previously created local artifacts, and with each subsequent generation, all files are cleaned/removed. To override the default behavior and enable reuse of local files, use the `--reuse` option. If you receive an error during file-upload to a cloud provider while using the `--reuse` option, then only the cloud portion of image generation will rerun for a subsequent image generation. Be aware that if you have already generated the virtual disk during previous runs, then using any disk-altering parameters will not be picked up on subsequent uses of the `-–reuse` variable.

**Example:**

To benefit from the `--reuse` parameter, you must run the Image Generator at least twice using the `--reuse` parameter for the same [PLATFORM, MODULES, BOOT_LOCATIONS] combination. In the first run, `--reuse` parameter will guarantee that the intermediary files are preserved. In the second run (when necessary), the `--reuse` parameter enables consumption of the intermediary files.

1. Build an image, type: `./build-image --reuse -i /var/tmp/BIGIP-15.0.0-0.0.39.iso -c config.yml -p qcow2 -m ltm -b 1 --image-tag "Name: my-custom-vm-v12.1.1" --image-tag "org: shared-services"`
2. To reuse the environment associated with the specified source image, platform, modules, and boot locations, type the exact same command used in Step 1: `./build-image --reuse -i /var/tmp/BIGIP-15.0.0-0.0.39.iso -c config.yml -p qcow2 -m ltm -b 1 --image-tag "Name: my-custom-vm-v12.1.1" --image-tag "org: shared-services"`.

For debugging purposes, this tool captures the contents of the PLATFORM, MODULES, BOOT_LOCATIONS artifacts directory in a `.snapshot.zip` file (excluding large binary files). Find this `.snapshot.zip` file in the same directory as the log file (for example, `logs/image-qcow2-ltm-1slot` for log file and `logs/image-qcow2-ltm-1slot.snapshot.zip` for the artifact files).

6. OPTIONAL: You can assign image tags to published images; however, rules for image tag definitions change depending upon the target, cloud provider ([Alibaba][26], [AWS][21], [Azure][19], and [GCE ][20]).
Currently, the Image Generator tool does not validate for each cloud provider's image ``tag:key`` and image ``tag:value`` pairing. Therefore, if you do NOT
properly define your image ``tag:key/value`` pair for the target cloud platform, then your image is created, but your image will not have the tags that
you defined. To define image tags, consult one of the following examples:

Configuration file (recommended):

```
IMAGE_TAGS:
- name: "my-custom-ami-v15.0.0"
- org: "shared-services"
- project: "alpha"
IMAGE_TAGS_EXCLUDE:
- build_source
- build_type
- version_basebuild
- version_build
- version_edition
- version_version
```

Command line:

```
–-image-tags ‘{"name":"my-custom-ami-v15.0.0"},{"org":"shared-services"},{"project":"alpha"}’
--image-tags-exclude '["build_source","build_type","version_basebuild","version_build","version_edition","version_version"]'
```

7. OPTIONAL: If you experience disk size limitations, then increase logical volume sizes for your configurations by using the UPDATE_LV_SIZES variable for the following logical volumes (ONLY):

* appdata
* config
* log
* shared
* var

For example, if you use multiple extensions on an instance that defaults to 500Mb, then you may want to increase the ``var`` LV size to 1.5GiB. Type:

Configuration file (recommended):

```
UPDATE_LV_SIZES: >-
{
"var": 1500
}
```

Command line:

```
–-update-lv-sizes '{"var":1500}'
```

##### IMPORTANT
-----------------------
You can increase the size of these five logical volumes ONLY and only at the first boot location. Also, be aware that increasing these logical volume sizes will increase the overall disk size.

-----------------------

For example, if running multiple modules, then in your configuration file add the following to update all LVs:

Configuration file (recommended):

```
UPDATE_LV_SIZES: >-
{
"appdata": 32000,
"config": 3500,
"log": 4500,
"shared": 22000,
"var": 5500
}
```

Command line:

```
-–update-lv-sizes '{"appdata":32000,"config":3500,"log":4500,"shared":22000,"var":5500}'

```

Note that these size values are examples only. To calculate the increased LV sizes for your needs, first find your base, reference LV size.

a. From either F5 Downloads or a public cloud Marketplace, launch the base BIG-IP VE image file for your environment.

b. Type:

```
lvs --units m
```

8. OPTIONAL: Onboard VMware OVA files ONLY using the ``--ova-prop-net-user`` directive. This directive uses the OVA Properties file to streamline onboarding by injecting a [block of text][36] that contains onboard network (mgmt IP) and user (password) properties into the .ovf file that resides within the .ova file. Use file injection to back the onboarding RPMs into the image, similar to **step 4** in this [User guide](#user-guide).

For example:

```
./build-image -i /var/tmp/BIGIP-15.1.1-0.0.6.iso -c config.yml -p vmware -m ltm -b 1 --ova-prop-net-user

```

9. OPTIONAL: To update the ``grub.conf`` file and bake the following changes into your generated VE image:

* **Disable splash screen** – use ``--disable-splash`` to disable the boot screen, which can stall automation processes. Add the following to your config file: ``DISABLE_SPLASH: 1``.
* **Enable serial console** – use ``console-devices ['ttyS1','tty1']`` for identifying locally-attached peripheral devices. The default value ``ttyS0`` is required to build images. Start numbering your serial devices/consoles using ``ttyS1``. Add the following to your config file, and all existing console entries are replaced with your defined console devices (use one ``console=`` for each entry):

```
CONSOLE_DEVICES:
- ttyS1
- tty1

```

### Monitor progress

1. The Image Generator will provide high-level progress information on the console. For more details, see the log file associated with the job, located in the logs directory. Log files use the following naming convention:
`image-PLATFORM-MODULES-BOOT_LOCATIONS` (for example, image-gce-ltm-1slot).
2. To adjust the log level output to the log file, use the `--log-level` parameter.

### Locate files

You can locate files in the following directories:

* **artifacts** - Artifacts created during image generation. Directory structure is based on source image, platform, modules, and boot locations.
* **docs** - Supporting documentation
* **images** - The Image Generator tool generates a virtual disk image from the BIG-IP product ISO in the default, `images` directory. Use the `IMAGE_DIR` parameter to override this default value and store images in a different directory.
* **logs** - Log files. The `LOG_FILE` parameter can be used to override this default value. Default log file name is based on platform, modules, and boot locations.
* **src** - build-image script and other source files.

## Troubleshooting guide

This section provides troubleshooting information for setting up the environment and running the Image Generator tool, as well as common issues with supported cloud providers.

**Selinux relabel error**

```
Inserting VM installation environment for 'RTM' -- elapsed time: 0:00:57
qemu-system installing RTM Image -- start time: 15:07:15
..........................................................................................
qemu-system installing RTM Image -- elapsed time: 0:07:31
qemu-system performing selinux relabeling -- start time: 15:14:46
.........................
qemu-system performing selinux relabeling -- elapsed time: 0:02:05
SELinux labeling failed or skipped. Check /home/user1/dev/ve-image-generator/src/lib/bash/../../../artifacts/BIGIP-13.1.5-0.0.32/gce/ltm_1slot/tmp.QgbFigOMVN/qemu.selinux_relabeling.log for complete logs
Wrote config to: /home/user1/dev/ve-image-generator/src/lib/bash/../../../artifacts/BIGIP-13.1.5-0.0.32/gce/ltm_1slot/build_config.json
Outputting json file has not been requested.

```

**Solution**

This error message can occur using Image Generator Tool (IGT) versions 1.14 and later, building BIG-IP VE 13.1.X images. If you experience this error, use IGT version 1.13.

**Low disk space**:

```
At least 20000 MB storage is needed. Only MB found.
```

**Solution**:

Free up local disk space, so you have more than 20GB (20000 MB) free.

**Docker error message**:

```
Temporary location for injected files: '/workdir/artifacts/BIGIP-15.1.0-0.0.31/aws/ltm_1slot/tmp.CgrVUToDbf/stage.initrd/etc/injected_files'
Collecting information about installed software on the build machine
copy 'authorized_keys' to a temporary location for '/home/admin/.ssh/authorized_keys'
Invalid URL 'authorized_keys': No schema supplied.
```

**Solution**:

You see this message when your asset files reside in a local directory, or a relative directory from where you are running the Docker command. Relocate your asset files to a Docker file directory or mount a different volume and include those files in the volume BEFORE building your image.

**Setup error message**:

The virtual environment was not created successfully because ensurepip is not
available. On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

`apt-get install python3-venv`

**Solution**:

You see this error, when you have not run the Setup Script. Run the [setup script][2].

**Environment error message**:
`qemu-system-x86_64: cannot set up guest memory 'pc.ram': Cannot allocate memory`

**Solution**:

You see this error when you run in an environment with minimal memory. Increase memory for the environment.

**Environment error message**:

```
Watchdog timer expired! (7201 seconds).
Killing 'qemu' with pid 6073!

Further explanation:
The 'qemu' process should complete within a reasonable amount of time.
If it does not, then we kill it to prevent it from blocking the build
process indefinitely. It is likely this is an intermittent issue and
the next build will complete successfully.
```

**Solution**:

Likely caused by either running in an environment that does not support virtualization or running in a lightweight environment. See [Prerequisites](#prerequisites).

**Missing packages error message**:

```
Traceback (most recent call last):
File "/home/ubuntu/ve-image-generator/src/lib/bash/../../bin/read_injected_files.py", line 22, in
from util.injected_files import read_injected_files
File "/home/ubuntu/ve-image-generator/src/lib/python/util/injected_files.py", line 24, in
import distro
```

**Solution**:

It is possible that the setup script encountered an error and did not complete, or was run as a different user. Run the setup script again, and then review the output.

**KVM permissions error message**:

```
Could not access KVM kernel module: Permission denied
qemu-system-x86_64: failed to initialize KVM: Permission denied
```

**Solutions**:

* Restart your system or log out and back in to your system.
* Check that the user is in the kvm group in:

`/etc/group`

`kvm:x:115:ubuntu`

Shows user ubuntu in the kvm group.

* Check that the permissions is correct in the following file:

`/lib/udev/rules.d/60-qemu-system-common.rules`

(`KERNEL=="kvm", GROUP="kvm", MODE="0666"`)

* Check that the following is NOT present:

`/var/run/reboot-required`

You may have run the setup script, and ignored the reboot message.

**Runtime error message**:

* Review the log file. When you encounter an error, the log file can contain more detailed information regarding the error.
* Change the log level. For troubleshooting, consider changing the log level to DEBUG or TRACE.

**AWS error message**:

`The service role does not exist or does not have sufficient permissions for the service to continue.`

**Solution**:

AWS requires an **IAM Role** with import permissions (see the [AWS User Guide][3] for more information).

**VMware and AWS error message**:

`ovftool isn't installed or missing from PATH. Please install it before trying again.`

**Solution**:

Download and install the [ovftool][22] before trying again.

## Support guide
Although the F5 BIG-IP Image Generator Tool is community-supported, the VE instances deployed from the images generated by this tool are supported by [F5 Support][23].

To report defects and security vulnerabilties, or submit enhancements and general questions open an issue within the GitHub repository.

1. In the top-right corner, expand :heavy_plus_sign: **More**, and then select **New Issues** from the list.
2. Enter a title, a description, and then click **Submit new issue**.

### Known issues
All [known issues][27] are now on the GitHub **Issues** tab for better tracking and visibility. Sort the [issues list][27] by expanding the **Label** column and selecting **Known issue**.

## Appendix
This section contains sample configuration code and output data referenced elsewhere in this document.

### Telemetry sample output data

```
{

"Operation": {
"bootLocations": "1",
"consoleDevicesInput": "tty7 console=tty12 console=ttyS0",
"disableSplash": null,
"endTime": null,
"module": "ltm",
"nestedVirtualization": "enabled",
"platform": "vhd",
"product": "BIG-IP",
"productBaseBuild": "0.0.1420",
"productBuild": "0.0.1420",
"productVersion": "16.0.0",
"result": null,
"resultSummary": "",
"startTime": "2022-07-08T17:29:09",
"updateImageFiles": "disabled",
"updateLvSizes": "disabled"
},
"additional": {
"gitHash": "5ddb6213b2c1655f570942a5d5a2fe664793873c"
},
"environment": {
"goVersion": null,
"libraries": {
"git": "git version 2.25.1",
"ssh": "OpenSSH_8.2p1 Ubuntu-4ubuntu0.5, OpenSSL 1.1.1f 31 Mar 2020"
},
"nodeVersion": null,
"pythonVersion": "3.8.10",
"pythonVersionDetailed": "3.8.10 (default, Mar 15 2022, 12:22:08) \n[GCC 9.4.0]"
},
"platform": {
"os": "Ubuntu 20.04.4 LTS"
},
"product": {
"installDate": "2020-05-10 23:37:25.355259",
"installationId": "fde0cdd8-d0d6-11e9-8307-0242ac110002",
"installedComponents": {
"alibaba": {
"aliyun-python-sdk-core": "2.13.33",
"aliyun-python-sdk-ecs": "4.23.11",
"oss2": "2.14.0"
},
"aws": {
"boto3": "1.23.10",
"moto": "3.1.14"
},
"azure": {
"azure-mgmt-compute": "26.1.0",
"azure-storage-blob": "12.11.0"
},
"gcp": {
"google-cloud-sdk": "not installed"
},
"miscPythonTools": {
"distro": "1.5.0",
"pycdlib": "1.11.0"
},
"pythonRequests": {
"requests": "2.25.0"
},
"retryPackage": {
"retry": "0.9.2"
},
"verifyingCodeTools": {
"anybadge": "not found",
"bats": "1.1.0+git104-g1c83a1b-1",
"bc": "1.07.1-2build1",
"dc": "1.07.1-2build1",
"git": "1:2.25.1-1ubuntu3.4",
"kmod": "27-1ubuntu2.1",
"parted": "3.3-4ubuntu0.20.04.1",
"pylint": "2.4.4-2",
"shellcheck": "0.7.0-2build2",
"udev": "245.4-4ubuntu3.17"
},
"yaml": {
"pyyaml": "5.4.1",
"yq": "2.12.0"
}
},
"locale": "en_US.UTF-8",
"version": "1.19"
}
}

```

#### Copyright

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at

[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.

#### Contributor License Agreement

Individuals or business entities who contribute to this project must have
completed and submitted the F5 Contributor License Agreement.

[1]: https://downloads.f5.com/esd/productlines.jsp
[2]: https://github.com/f5devcentral/f5-bigip-image-generator/blob/master/setup-build-env
[3]: https://docs.aws.amazon.com/vm-import/latest/userguide/vmimport-image-import.html
[4]: http://manpages.ubuntu.com/manpages/bionic/man1/kvm-ok.1.html
[5]: https://github.com/f5devcentral/f5-bigip-image-generator/blob/master/docs/examples/config.yml
[6]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/aws#create-image-for-aws-using-docker-container
[7]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/azure#create-image-for-azure-using-docker-container
[8]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/gce#create-image-for-gce-using-docker-container
[9]: https://cloud.google.com/iam/docs/creating-managing-service-accounts
[10]: https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest
[11]: https://docs.microsoft.com/en-us/rest/api/storageservices/create-container
[12]: https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html
[13]: https://cloud.google.com/storage/docs/creating-buckets
[14]: https://clouddocs.f5.com/cloud/public/v1/vmware/vmware_setup.html
[15]: https://github.com/f5devcentral/tmos-cloudinit/tree/master/tmos_configdrive_builder
[16]: https://github.com/f5devcentral/tmos-cloudinit
[17]: https://clouddocs.f5.com/cloud/public/v1/hyperv_index.html
[18]: https://clouddocs.f5.com/cloud/public/v1/kvm_index.html
[19]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-container-properties-metadata
[20]: https://cloud.google.com/compute/docs/labeling-resources
[21]: https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/Using_Tags.html#tag-restrictions
[22]: https://code.vmware.com/web/tool/4.3.0/ovf
[23]: https://www.f5.com/company/contact/regional-offices#product-support
[24]: https://support.f5.com/csp/article/K4422
[25]: https://cloud.google.com/compute/docs/instances/enable-nested-virtualization-vm-instances#enablenestedvirt
[26]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/alibaba#create-image-for-alibaba-using-docker-container
[27]: https://github.com/f5devcentral/f5-bigip-image-generator/issues?q=is%3Aopen+is%3Aissue+label%3A%22known+issue%22
[28]: https://docs.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string
[29]: https://www.alibabacloud.com/help/doc-detail/31885.htm
[30]: https://www.alibabacloud.com/help/doc-detail/92270.htm?spm=a2c63.p38356.b99.123.319c412aF3kxA0
[31]: https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal
[32]: http://www.filepermissions.com/articles/understanding-octal-file-permissions
[33]: https://support.f5.com/csp/article/K14946
[34]: https://hub.docker.com/r/f5devcentral/f5-bigip-image-generator
[35]: https://clouddocs.f5.com/products/extensions/f5-telemetry-streaming/latest/faq.html
[36]: https://clouddocs.f5.com/cloud/public/v1/vmware/vmware_setup.html#ova-properties-file-for-setting-management-ip-address-and-default-passwords
[37]: https://clouddocs.f5.com/products/extensions/f5-declarative-onboarding/latest/
[38]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/alibaba
[39]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/aws
[40]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/azure
[41]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/gce
[42]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/alibaba#parameter-definitions
[43]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/aws#parameter-definitions
[44]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/azure#parameter-definitions
[45]: https://github.com/f5devcentral/f5-bigip-image-generator/tree/master/docs/providers/gce#parameter-definitions
[46]: https://my.f5.com/manage/s/article/K5903

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/f5devcentral/f5-bigip-image-generator

Awesome Lists containing this project

README