This the multi-page printable view of this section. Click here to print.
You can build an ISO from the source code and other images for Photon OS. This section describes how to build the ISO, build other images, use the cached toolchain and RPMS, and cached sources. You can use this method as an alternative to downloading a pre-built version.
For information on how to install and build a package on Photon OS from the package’s source RPM, see the Photon OS Administration Guide.
The structure of the directories on GitHub that contain the source code for Photon OS is as follows:
photon/
├── Makefile
├── README
├── Dockerfile
├── Vagrantfile
├── PUBLISHRPMS_SPECS # RPM SPEC files
├── SPECS # RPM SPEC files
├── common # Build, packaging config
├── docs # Documentation
├── build.py # Package builder
├── config.json # Package builder
├── support # Build scripts
└── tools
Before you build the ISO, verify that you have the performed the following tasks:
Installed a build operating system running the 64-bit version of Ubuntu 14.04 or later version.
Downloaded and installed the following packages for Ubuntu: bison gawk g++ createrepo python-aptdaemon genisoimage texinfo python-requests libfuse-dev libssl-dev uuid-dev libreadline-dev kpartx git bc
Downloaded and installed the following packages for Photon OS:
“rsync”
“docker-18.09.9”
“docker-py3”
“python3-pyOpenSSL”
“python3-six”
“python3-pip”
“cdrkit”
“createrepo_c”
“dosfstools”
“openssl-devel”
“python3-curses”
“zlib-devel”
“util-linux-devel”
Installed Docker
Downloaded the source code from the Photon OS repository on GitHub into $HOME/workspaces/photon.
You can build an ISO from the source code for Photon OS. This section describes how to build the ISO, use the cached toolchain and RPMS, and cached sources. You can use this method as an alternative to downloading a pre-built version.
For information on how to install and build a package on Photon OS from the package’s source RPM, see the Photon OS Administration Guide.
Perform the following steps to install the packages on Ubuntu:
Install the packages:
sudo apt-get -y install bison gawk g++ createrepo python-aptdaemon genisoimage texinfo python-requests libfuse-dev libssl-dev uuid-dev libreadline-dev kpartx git bc
Get Docker:
wget -qO- https://get.docker.com/ | sh
Install pip and docker 2.3.0
sudo apt install python3-pip
pip3 install docker==2.3.0
If you encounter an error for LOCALE when you run these commands, then export the following variables in the terminal:
export LC_ALL="en_US.UTF-8"
export LC_CTYPE="en_US.UTF-8"
The default configuration parameters are available in config.json. If you want to customize them, then the configuration information is available at the following location:
[https://github.com/vmware/photon/blob/dev/photon-build-config.txt](https://github.com/vmware/photon/blob/dev/photon-build-config.txt)
Clone`the Photon project:
git clone https://github.com/vmware/photon.git
cd $HOME/workspaces/photon
Make ISO as follows:
sudo make iso
Make Minimal ISO as follows:
sudo make minimal-iso
Make Real-Time ISO as follows:
sudo make rt-iso
Result
This command first builds all RPMs corresponding to the SPEC files in your Photon repository and then builds a bootable ISO containing those RPMs.
The RPMs thus built are stored under stage/RPMS/ directory within the repository, using the following directory hierarchy:
$HOME/workspaces/photon/stage/:
├──RPMS/:
├──noarch/*.noarch.rpm [Architecture-independent RPMs]
├──x86_64/*.x86_64.rpm [RPMs built for the x86-64 architecture]
├──aarch64/*.aarch64.rpm [RPMs built for the aarch64 (ARM64) architecture]
The ISO is created at $HOME/workspaces/photon/stage/photon.iso.
This section describes how to build the cloud images, OVA, and RPM.
For information on how to install and build a package on Photon OS from the package’s source RPM, see the Photon OS Administration Guide.
Perform the following steps to build the cloud images on Ubuntu:
Install the packages:
sudo apt-get -y install bison gawk g++ createrepo python-aptdaemon genisoimage texinfo python-requests libfuse-dev libssl-dev uuid-dev libreadline-dev kpartx git bc
Get Docker:
wget -qO- https://get.docker.com/ | sh
Install pip
sudo apt install python3-pip
pip3 install git+https://github.com/vmware/photon-os-installer.git
git clone https://github.com/vmware/photon.git
If you encounter an error for LOCALE when you run these commands, then export the following variables in the terminal:
`export LC_ALL="en_US.UTF-8"`
export LC_CTYPE="en_US.UTF-8"
Clone`the Photon project:
git clone https://github.com/vmware/photon.git
cd $HOME/workspaces/photon
Make the cloud image for AMI.
sudo make image IMG_NAME=ami
Make the cloud image for Azure.
sudo make image IMG_NAME=azure
Make the cloud image for GCE.
sudo make image IMG_NAME=gce
Result
This command first builds all RPMs corresponding to the SPEC files in your Photon repository and then builds a bootable ISO containing those RPMs.
The RPMs thus built are stored under stage/RPMS/ directory within the repository, using the following directory hierarchy:
$HOME/workspaces/photon/stage/:
├──RPMS/:
├──noarch/*.noarch.rpm [Architecture-independent RPMs]
├──x86_64/*.x86_64.rpm [RPMs built for the x86-64 architecture]
├──aarch64/*.aarch64.rpm [RPMs built for the aarch64 (ARM64) architecture]
The cloud image is created at `$HOME/workspaces/photon.
Perform the following steps to build OVA on Ubuntu:
Install the packages:
sudo apt-get -y install bison gawk g++ createrepo python-aptdaemon genisoimage texinfo python-requests libfuse-dev libssl-dev uuid-dev libreadline-dev kpartx git bc
Get Docker:
wget -qO- https://get.docker.com/ | sh
Install pip
sudo apt install python3-pip
pip3 install git+https://github.com/vmware/photon-os-installer.git
git clone https://github.com/vmware/photon.git
If you encounter an error for LOCALE when you run these commands, then export the following variables in the terminal:
export LC_ALL="en_US.UTF-8"
`export LC_CTYPE="en_US.UTF-8"`
Clone the Photon project:
git clone https://github.com/vmware/photon.git
cd $HOME/workspaces/photon
Download latest VDDK from below link:
https://my.vmware.com/web/vmware/downloads/details?downloadGroup=VDDK670&productId=742
Search for VMware-ovftool in the same site and install it.
For example:
ovftool downloaded file:
VMware-ovftool-4.3.0-13981069-lin.x86_64.bundle
Add exec permission and run it as sudo:
$ chmod +x VMware-ovftool-4.3.0-13981069-lin.x86_64.bundle && sudo ./VMware-ovftool-4.3.0-13981069-lin.x86_64.bundle --eulas-agreed --required
For VDDK, if the downloaded file is VMware-vix-disklib-6.7.0-8173251.x86_64.tar.gz, untar the downloaded tarball:
$ tar xf VMware-vix-disklib-6.7.0-8173251.x86_64.tar.gz
Navigate to extracted directory.
Move the header files to /usr/include
$ sudo mv include/*.h /usr/include
Move the shared libs to /usr/lib/vmware
$ sudo mkdir -p /usr/lib/vmware && sudo mv lib64/* /usr/lib/vmware && sudo rm /usr/lib/vmware/libstdc++.so*
Export /usr/lib/vmware library path(only for current session). Do this step every time you try to build an ova image.
$ export LD_LIBRARY_PATH=/usr/lib/vmware
Navigate to your intended Photon source repository and run the following command.
`sudo make image IMG_NAME=ova`
Make the image for OVA UEFI
sudo make image IMG_NAME=ova_uefi
Result
This command first builds all RPMs corresponding to the SPEC files in your Photon repository and then builds a bootable ISO containing those RPMs.
The RPMs thus built are stored under stage/RPMS/ directory within the repository, using the following directory hierarchy:
$HOME/workspaces/photon/stage/:
├──RPMS/:
├──noarch/*.noarch.rpm [Architecture-independent RPMs]
├──x86_64/*.x86_64.rpm [RPMs built for the x86-64 architecture]
├──aarch64/*.aarch64.rpm [RPMs built for the aarch64 (ARM64) architecture]
The cloud image is created at `$HOME/workspaces/photon.
When the necessary RPMs are available under the stage/RPMS/ directory, the commands that you use to create any Photon artifact such as, ISO or OVA will reuse those RPMs to create the specified image.
If you already have the Photon RPMs available elsewhere, and not under stage/RPMS/ in the Photon repository, you can build Photon artifacts using those cached RPMs by setting the PHOTON_CACHE_PATH variable to point to the directory containing those RPMs.
For example, if your RPMs are located under $HOME/photon-cache/, then use the following command to build an ISO:
sudo make iso PHOTON_CACHE_PATH=$HOME/photon-cache
The $HOME/photon-cache/ directory should follow the same structure as the stage/RPMS/ directory:
photon-cache/:
├──RPMS/:
├──noarch/*.noarch.rpm
├──x86_64/*.x86_64.rpm
├──aarch64/*.aarch64.rpm
To use the cached sources, run the following command:
mkdir $HOME/photon-sources
sudo make iso PHOTON_SOURCES_PATH=$HOME/photon-sources
The directory format of PHOTON_SOURCES_PATH is as follows:
photon-sources/
├──src1.tar.gz
├──src2.tar.gz
└──...
You can view build logs at the following location:
$HOME/workspaces/photon/stage/LOGS
The custom-iso tool allows you to build images as per your requirements.
Overview
Prerequisite
Preparing for Custom Image Generation
Generating a Custom Image
You can use the custom-iso tool to create images such as a custom ISO, Initrd, and RPM-OSTree. To generate an image, you must provide the necessary inputs in the form of arguments. The custom-iso tool creates images based on the inputs you provide.
You can use the following functions to generate the required images:
build-initrd generates a custom Initrd image
build-initrd generates a custom ISO image.
build-rpm-ostree-iso generates a custom RPM-OSTree ISO.
As an input to the tool, you must provide the list of all the necessary packages for the custom ISO in a JSON file. The tool only uses the minimal list of packages and their dependencies that you specify.
You can customize the following files and configurations:
initrd package listNote that when you use the Custom ISO builder to build the ISO and the Installer initrd, the ISO and initrd files are generated with the following naming conventions:
ISO: photon-<photon-release-version>.iso
Initrd: initrd.img
To generate a custom ISO, ensure that you provide the following required parameters:
build-iso, build-initrd, and build-rpm-ostree-isobuild-rpm-ostree-iso)Note: You must provide the additional repository if you want to include a package that the Photon OS official repository does not provide.
You can also provide the following optional parameters:
Initrd package list fileInstall the following prerequisite packages:
i. To install the specified packages on Photon OS, use the following command:
tdnf install -y python3-pip git tar createrepo_c binutils dosfstools cdrkit
Run following command to install photon-os-installer python library:
pip3 install git+https://github.com/vmware/photon-os-installer.git
Enable the following services before you build the custom iso/initrd: docker
i. To enable the docker service and log in to the docker account, use the following command:
systemctl start docker.service;
docker login # To avoid docker pull rate limit
Create the file containing the custom package list.
The following list shows some of the sample custom package files:
Package list json format-
{
"packages": <list-of-pkgs>,
"packages_x86_64": <x86-specific-pkgs>,
"packages_aarch64": <aarch64-specific-pkgs>
}
For more details, refer to the following link: https://github.com/vmware/photon-os-installer/blob/master./ks_config.md#packages-optional-if-packagelist_file-set
Note: packages_x86_64 and packages_aarch64 are optional keys. The packages_minimal.json file is a sample file. You can create your own JSON file with the list of custom packages that you want, and provide the directory path for the file in the command to generate the iso/initrd.
You can use the respective commands to generate the custom images for the following use cases.
Command:
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json>
Example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json
Note: you can skip the --function invocation because photon-iso-builder sets the default function to build-iso.
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> [-r <path/to/custom-repo-list>]
Example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json -r local.repo -r local2.repo
Note: In order to create your own custom repository, see the following page: Adding a New Repository
Command:
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -k <path-to-kickstart>
Example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json -k /root/custom_kickstart.json
To create a custom kickstart configuration file, see the follow page: Kickstart Configuration
Note: If the Kickstart file is provided while creating the custom ISO, boot command line parameter is not edited to install the ISO through kickstart.
To boot the ISO through the provided kickstart file, you need to create the custom ISO file using the following format:
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -f build-iso -k <path-to-kickstart> -b "ks=cdrom:/isolinux/<kickstart-file-base-name>"
Example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json -k /root/custom_kickstart.json -b "ks=cdrom:/isolinux/custom_kickstart.json"
Command:
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -f build-iso -b <extra-boot-parameter>
Example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json -b "ks=http://10.197.102.86:8000/sample_ks.cfg insecure_installation=1"
Before you generate the custom image using default installation as RPM-OStree, you need to generate ostree tar archive. Perform the following steps to generate the ostree tar archive:
Generate the ostree repo tree as directed here: Creating a Server
Create tarball of the repo tree:
Command:
tar -czf </path/to/>ostree-repo.tar.gz -C </path/to/repotree>/repo
Example: repo tree resides inside the following directory my-repo like /root/my-repo/repo
tar -zcf /root/ostree-repo.tar.gz -C /root/my-repo/repo .
Once the tar archive is generated, generate the custom image. To generate the custom image using default installation as RPM-OStree, execute the following command:
photon-iso-builder -v <photon-release-version> -o <path/to/ostree-tar-archive> -f build-rpm-ostree-iso
Example:
photon-iso-builder -v 5.0 -o /root/ostree-repo.tar.gz -f build-rpm-ostree-iso
Note: You can either provide a local path or a URL for the ostree tar archive. Custom package list json is not required for this case.
Command:
photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -a <custom-artifact-path>
Note: Custom artifact path parameter takes parent directory path as the input in which the artifact is placed.
As per the user input, artifact is placed under /root/custom/path in the following example:
photon-iso-builder -v 5.0 -p /root/packages_custom.json -a /root/custom/path
Command:
photon-iso-builder -v <photon-release-version> -c <path/to/custom-initrd-pkg-list-file> -f build-initrd
Example:
photon-iso-builder -v 5.0 -c /root/packages_custom_initrd.json -f build-initrd
The default initrd package list file is located in the following directory: https://github.com/vmware/photon/blob/master/common/data/packages_installer_initrd.json
The following command demonstrate how to generate a custome ISO through the source code:
git clone https://github.com/vmware/photon-os-installer.git
cd photon-os-installer/photon_installer
./isoBuilder -v 5.0 -p packages_minimal.json