This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation Guide

The Photon OS Installation Guide provides information about how administrators can install Photon OS.

Product version: 4.0

This documentation applies to all 4.0.x releases.

Intended Audiences

This information is intended for Photon OS administrators who install and set up Photon OS.

1 - Downloading Photon OS

Detailed instructions for obtaining Photon OS 4.0 are located at: https://github.com/vmware/photon/wiki/Downloading-Photon-OS

Download Formats

Photon OS is available in the following pre-packaged, binary formats:

FormatDescription
ISO ImageContains everything needed to install the minimal or full installation of Photon OS or the Real-Time flavor of Photon OS. The bootable ISO has a manual installer or can be used with PXE/kickstart environments for automated installations.
OVAPre-installed minimal environment, customized for VMware hypervisor environments. These customizations include a highly sanitized and optimized kernel to give improved boot and runtime performance for containers and Linux applications. Since an OVA is a complete virtual machine definition, we’ve made available a Photon OS OVA that has virtual hardware version 13 arm64, version 13, and version 11; this will allow for compatibility with several versions of VMware platforms or allow for the latest and greatest virtual hardware enhancements.
Amazon AMIPre-packaged and tested version of Photon OS with Amazon AMI and Amazon AMI arm64 packages made ready to deploy in your Amazon EC2 cloud environment. Previously, we’d published documentation on how to create an Amazon compatible instance, but, now we’ve done the work for you.
Google GCE ImagePre-packaged and tested Google GCE image that is ready to deploy in your Google Compute Engine Environment, with all modifications and package requirements for running Photon OS in GCE.
Azure VHDPre-packaged and tested Azure HD image that is ready to deploy in your Microsoft Azure Cloud, with all modifications and package requirements for running Photon OS in Azure.
Raspberry Pi ImagePre-packaged and tested Raspberry Pi Image on ARM64 architecture.

2 - Upgrading to Photon OS 4.0

You can upgrade your existing Photon OS 3.0 VMs to take advantage of the functionality enhancements in Photon OS 4.0. For details, see What’s New in Photon OS 4.0.

Photon OS 4.0 provides a seamless upgrade for Photon OS 3.0 implementations. You simply download an upgrade package, run a script, and reboot the VM. The upgrade script will update your packages and retain your 3.0 customizations in your new OS 4.0 VM.

Note: If your 3.0 VM is a full install, then you will have a 4.0 VM that represents a full install (all packages and dependencies). Upgrading a minimal installation takes less time due to fewer packages.

For each Photon OS 3.0 VM that you want to upgrade, complete the following steps:

  1. Back up all existing settings and data for the Photon OS 3.0 VM.

  2. Stop any services (for example, docker) that are currently running in the VM.

  3. Install photon-upgrade package

    # tdnf -y install photon-upgrade
    
  4. Run the upgrade script

    # photon-upgrade.sh
    
  5. Answer y to reboot the VM. The upgrade script powers down the Photon OS 3.0 VM and powers it on as a Photon OS 4.0 VM.

After the upgrade, before you deploy into production, test all previous functionality to ensure that everything works as expected.

3 - Building Images

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.

3.1 - Folder Layout

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

3.2 - Build Prerequisites

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.

3.3 - Build an ISO from the Source Code for Photon OS

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.

3.3.1 - Building the ISO

Perform the following steps to install the packages on Ubuntu:

  1. 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
    
  2. Get Docker:

    wget -qO- https://get.docker.com/ | sh
    
  3. 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"
    
  4. 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)
    
    
  5. Clone`the Photon project:

    git clone https://github.com/vmware/photon.git cd $HOME/workspaces/photon

  6. Make ISO as follows:

    sudo make iso

  7. Make Minimal ISO as follows:

    sudo make minimal-iso

  8. 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.

3.4 - Build Other Images for Photon OS

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.

3.4.1 - Building Cloud Images

Perform the following steps to build the cloud images on Ubuntu:

  1. 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
    
  2. Get Docker:

    wget -qO- https://get.docker.com/ | sh
    
  3. 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"

  1. Clone`the Photon project:

    git clone https://github.com/vmware/photon.git cd $HOME/workspaces/photon

  2. Make the cloud image for AMI.

    sudo make image IMG_NAME=ami

  3. Make the cloud image for Azure.

    sudo make image IMG_NAME=azure

  4. 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.

3.4.2 - Building OVA image

Perform the following steps to build OVA on Ubuntu:

  1. 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
    
  2. Get Docker:

    wget -qO- https://get.docker.com/ | sh
    
  3. 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"`
    
    
    
  4. Clone the Photon project:

    git clone https://github.com/vmware/photon.git
    

    cd $HOME/workspaces/photon

  5. Download latest VDDK from below link:

    https://my.vmware.com/web/vmware/downloads/details?downloadGroup=VDDK670&productId=742

  6. 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

  7. 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

  8. 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*

  1. 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

  2. Navigate to your intended Photon source repository and run the following command.

    
    `sudo make image IMG_NAME=ova`
    
    
  3. 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.

3.5 - Use the Cached Toolchain and RPMS

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

3.6 - Use Cached Sources

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
└──...

3.7 - View Build Logs

You can view build logs at the following location:

$HOME/workspaces/photon/stage/LOGS

4 - Building Package or Kernel Modules Using a Script

You can use a script to build a single Photon OS package without rebuilding all Photon OS packages. You just need a .spec specification file and sources. You place the sources and the specification files in the same folder and run the build_spec.sh script. The script performs the following steps:

  • Creates sandbox using docker.
  • Installs build tools and .spec build requirements from the Photon OS repository.
  • Runs rpmbuild.

Result: You have a native Photon OS RPM package.

The build-spec.sh script is located in the photon/tools/scripts/ folder.

Prerequisites

Before you run the build-spec.sh script, perform the following steps:

  • Ensure you have any Linux OS with docker daemon running.
  • Place the source and RPM .spec files in the same folder, that is, $WORKDIR.

Procedure

Run the script. Provide the RPM .spec file name, including absolute or relative path, as argument:

./photon/tools/scripts/build_spec.sh <$WORKDIR/rpm_spec_file.spec>

The RPMs and full build logs are generated in the $WORKDIR/stage folder.

Example

The following example runs the script with simple-module.spec as argument, where simple-module.spec is the specification file:

./photon/tools/scripts/build_spec.sh ~/photon/tools/examples/build_spec/simple-module.spec

The following are the contents of the simple-module.spec file:

Summary:        Simple Linux module
Name:           simple-module
Version:        4.18.9
Release:        5%{?dist}
License:    	GPLv2
Group:        	System Environment/Kernel
Vendor:         VMware, Inc.
Distribution: 	Photon
Source0:        module_example.tar.xz
BuildRequires:  linux-devel = 4.18.9
BuildRequires:  kmod
Requires:       linux = 4.18.9

%description
Example of building linux module for Photon OS

%prep
%setup -q -n module_example

%build
make -C `echo /usr/src/linux-headers-4.18.9*` M=`pwd` VERBOSE=1 modules %{?_smp_mflags}

%install
make -C `echo /usr/src/linux-headers-4.18.9*` M=`pwd` INSTALL_MOD_PATH=%{buildroot} modules_install
# fix permissins to generate non empty debuginfo
find %{buildroot}/lib/modules -name '*.ko' -print0 | xargs -0 chmod u+x

%post
/sbin/depmod -a

%files
%defattr(-,root,root)
/lib/modules/*

Build Logs

The following logs indicate the steps that the script performs internally:

1. Create sandbox
	Use local build template image OK
2. Prepare build environment
	Create source folder OK
	Copy sources from <HOME>/photon/tools/examples/build_spec/simple-module OK
	Install build requirements OK
3. Build
	Run rpmbuild OK
4. Get binaries
	Copy RPMS OK
	Copy SRPMS OK
5. Destroy sandbox
	Stop container OK
	Remove container OK

Build completed. RPMS are in '<HOME>/photon/tools/examples/build_spec/simple-module/stage' folder

5 - Running Photon OS on vSphere

You can use Photon OS as a virtual machine within VMware vSphere. You can download Photon OS, as an OVA or ISO file, and install the Photon OS distribution on vSphere. After you install Photon OS, you can deploy a containerized application in Docker with a single command.

Note: If you want to upgrade an existing Photon 1.0 VM, see the Upgrade to Photon OS 4.0 section.

5.1 - Prerequisites for Running Photon OS on vSphere

Resource requirements and recommendations vary depending on several factors, including the host environment (for example, VMware vSphere and VMware Fusion), the distribution file used (ISO or OVA), and the selected installation settings (for example, full or basic installation).

Before you use Photon OS within VMware vSphere, perform the following prerequisite tasks:

  1. Verify that you have the following resources:

    ResourceDescription
    VMware vSphere installedVMware web client (v6.5) for ESXi hosts (recommended)

    Note: vSphere 6 and vSphere 5.5 (these clients provide limited support; Not all features are available).

    MemoryESXi host with 2GB of free RAM (recommended)
    StorageMinimal Photon install: ESXi host with at least 512MB of free space (minimum); Full Photon install: ESXi host with at least 4GB of free space (minimum); 16GB is recommended; 16GB recommended.
    Distribution FilePhoton OS ISO or OVA file downloaded from [https://packages.vmware.com/photon/](https://packages.vmware.com/photon/).

    Note: The setup instructions in this guide use VMware vSphere 6 and the vSphere web client.

  2. Decide whether to use the OVA or ISO distribution to set up Photon OS.

    • OVA import : Because of the nature of an OVA, you’re getting a pre-installed version of Photon OS. You can choose the hardware version you want (OVA with hardware version 13 or 11). The OVA benefits from a simple import process and some kernel tuning for VMware environments. However, because it’s a pre-installed version, the set of packages that are installed are predetermined. Any additional packages that you need can be installed using tdnf.
    • ISO install : The ISO, on the other hand, allows for a more complete installation or automated installation via kickstart.

    To get Photon OS up and running quickly, use the OVA.

  3. Download Photon OS. Go to the following URL and download the latest release of Photon OS:

    https://packages.vmware.com/photon/

    For instructions, see https://github.com/vmware/photon/wiki/Downloading-Photon-OS.

    Note: For ISO installation, you must upload to a datashare that is attached to the ESXi host, or mount the file share where the ISO resides as a data store.

5.2 - Importing the OVA for Photon OS 4.0

Using the OVA is a fast and easy way to create a Photon OS VM on VMware vSphere.

After you have downloaded the OVA, log in to your vSphere environment and perform the following steps:

  1. Start the Import Process

    From the Actions pull-down menu, choose Create/Register VM.

    In the Select creation type window, choose Deploy a virtual machine from an OVF or OVA file.

    Create new virtual machine

    Choose Next.

  2. Select the OVA File

    Enter a name for the virtual machine, and select the OVA file.

    OVA file

    Choose Next.

  3. Specify the Target Datastore

    From the Select storage screen, select the target datastore for your VM.

    Target datastore

    Choose Next.

  4. Accept the License Agreement

    Read through the Photon OS License Agreement, and then choose I Agree.

    License

    Choose Next.

  5. Select Deployment Options

    Photon OS is provisioned with a maximum disk size. By default, Photon OS uses only the portion of disk space that it needs, usually much less that the entire disk size ( Thin client). If you want to pre-allocate the entire disk size (reserving it entirely for Photon OS instead), select Thick instead.

    Deployment Options

    Choose Next.

  6. Verify Deployment Settings

    Deployment settings

    Click Finish. vSphere uploads and validates your OVA. Depending on bandwidth, this operation might take a while.

    When finished, vShield powers up a new VM based on your selections.

  7. Change Login Settings

    Login prompt

    After the VM is booted, open the command window. vSphere prompts you to log in.

    Note: Because of limitations within OVA support on vSphere, it was necessary to specify a default password for the OVA option. However, all Photon OS instances that are created by importing the OVA require an immediate password change upon login. The default account credentials are:

     - Username: ``root``
     - Password: ``changeme``
    

    After you provide these credentials, vSphere prompts you to create a new password and type it a second time to verify it.

    Note: For security, Photon OS forbids common dictionary words for the root password.  

    Once logged in, you will see the shell prompt.

    Shell prompt

    Once complete, proceed to Deploying a Containerized Application in Photon OS.

  8. Export the VM as a Template (Optional)

    Consider converting this imported VM into a template (from the Actions menu, choose Export ) so that you have a master Photon OS instance that can be combined with vSphere Guest Customization to enable rapid provisioning of Photon OS instances.

5.3 - Installing the ISO Image for Photon OS 4.0

After you download the Photon OS ISO image into a folder of your choice, complete the following steps.

  1. Upload the ISO Image

    Upload the ISO image to a datastore that is attached to the host on which you’ll create the Photon OS virtual machine.

  2. Create a new VM

    Log in to your vSphere environment. In the Virtual Machines window, choose Create/Register VM.

    On the Select creation type screen, select Create a new virtual machine.

    Create new virtual machine

    Choose Next.

  3. Configure VM Settings

    Specify a VM name.

    VM name

    Specify a guest operating system.

    • For Compatibility, select ESXi 6.7.
    • For Guest OS family, select Linux.
    • For Guest OS version, select VMware Photon OS (64-bit).

    Guest operating system

    Choose Next.

  4. Select the Target Datastore

    Select the datastore where you want to store the VM.

    Target datastore

    Click Next.

  5. Customize VM Settings

    Customize the virtual machine settings.

    Settings

    For CD/DVD Drive 1, click the drop-down and select Datastore ISO file.

    In the Datastore browser, select the ISO that you want to import.

    Change other settings as applicable.

    • The recommended virtual hardware settings for your Photon VM are heavily dependent upon the container load you intend to run within Photon OS – more containers or more intensive containers will require you to adjust these settings for your application load. VMware suggests 2 vCPU, 1024MB memory, 20GB hard disk. Any unwanted devices should be removed. Be sure to mount the Photon OS ISO on the CD/DVD Drive and put a check in the box next to, Connect At Power On.
    • If you want to configure a secure boot for the Photon OS VM you created, choose the VM Options tab, expand Boot Options, and select EFI from the firmware drop-down. An EFI boot ensures that the ISO content is signed by VMware and that the entire stack is secure.

    Choose Next.

  6. Verify VM Settings

    The installer displays a summary of your selected settings.

    Summary

    Click Finish. vSphere creates the VM.

  7. Power on the VM

    Select the VM and power it on.

    Power on VM

    When you see the Photon Installer boot menu, press Enter on your keyboard to start installing.

  8. Accept the License Agreement

    Read the License Agreement and press the Enter key to accept.

    License Agreement

  9. Configure the Partition

    The installer detects one disk, which should be the 16GB volume configured as part of the virtual machine creation. Choose Auto to have the installer automatically allocate the partition, or choose Custom if you want to configure individual partitions, and then press the Enter key.

    Partition

    Note: If you choose Custom, the installer displays the following screen.

    Custom Partition

    For each custom partition, choose Create New and specify the following information:

    New Partition

    Size - Preallocated size of this partition, in MB.

    Type - One of the following options:

    • ext3 - ext3 file system
    • ext4 - ext4 file system
    • swap - swap partition

    Mountpoint - Mount point for this partition.

    Choose OK and press the Enter key. When you are done defining custom partitions, choose Next and press the Enter key.

    The installer prompts you to confirm that you want to erase the entire disk.

    Erase disk

    Choose Yes and press the Enter key.

  10. Select an Installation Option

    After partitioning the disk, the installer prompts you to select an installation option.

    Installation Option

    Each install option provides a different run-time environment, depending on your requirements.

    OptionDescription
    Photon MinimalPhoton Minimum is a very lightweight version of the container host runtime that is best suited for for devices that have limited compute and memory capabilities. There is sufficient packaging and functionality to allow most common operations around modifying existing containers, as well as being a highly performant and full-featured runtime.

    Photon DeveloperPhoton Developer includes several additional packages to enhance the authoring and packaging of containerized applications and/or system customization. Use Photon Developer for developing and packaging the application that will be run as a container, as well as authoring the container, itself. For testing and validation purposes, Photon Developer includes all components necessary to run containers.
    Photon OSTree HostThis installation profile creates a Photon OS instance that will source its packages from a central rpm-ostree server and continue to have the library and state of packages managed by the definition that is maintained on the central rpm-ostree server.
    Photon Real TimeThis profile is available only for the x86_64 architecture.

    Note: The option you choose determines the disk and memory resources required for your installation.

    Select the option you want and press the Enter key.

  11. The Network Configuration screen appears, select one of the four options to configure your network.

    Network Configuration

    1. Choose Configure network automatically and select Next to configure the network automatically.

    2. To configure network automatically with the DHCP hostname, select Configure network automatically with a DHCP hostname and select Next. Enter the DHCP Hostname and select Next. ../images/DHCP_hostname_for_your_system.png

    3. To configure the network manually, select Configure Network manually. In the window that appears, enter the IP Address, Netmask, Gateway and Nameserver and select OK. ../images/Configure_Network_Manually.png

    4. If your network interface is directly connected to the VLAN trunk port, choose YES on the Configure the network screen. Enter the VLAN ID and select Next. Configure the network.

  12. Select the Linux Kernel

    Select a Linux kernel to install.

    Linux Kernel

    • Hypervisor optimized means that any components that are not needed for running under a VMware hypervisor have been removed for faster boot times.
    • Generic means that all components are included.

    Choose Next and press the Enter key.

  13. Specify the Hostname

    The installer prompts you for a hostname and suggest a randomly generated, unique hostname that you can change if you want.

    Hostname

    Press the Enter key.

  14. Specify the System root Password

    The installer prompts you to enter the system root password.

    Note: Photon OS will not permit commonly used dictionary words to be set as a root password.

    Root password

    Type a password and press the Enter key.

    The installer prompts you to confirm your root password by typing it a second time.

    Password confirmation

    Note: If you have trouble with unintentional repeated characters in the Remote Console, follow VMware KB 196 ( http://kb.vmware.com/kb/196) for a setting to apply to the virtual machine.

    Press the Enter key. The installer proceeds to install the software. Installation times will vary based on the system hardware and installation options you selected. Most installations complete in less than one minute.

  15. Reboot the VM and Log In

    Once finished, the installer displays a confirmation message (which includes how long it took to install Photon OS) and prompts you to press a key on your keyboard to boot the new VM.

    Boot VM

    As the initial boot process begins, the installer displays the Photon splash screen, and then a login prompt.

    Login prompt

    At the login prompt, type root as the username and provide the password chosen during the installation.

    Password

You can now use your container runtime environment and deploy a containerized application.

6 - Running Photon OS on Fusion

You can use Photon OS as a virtual machine within VMware Fusion. You can download Photon OS, as an OVA or ISO file, and install the Photon OS distribution on Fusion. After you install Photon OS, you can deploy a containerized application in Docker with a single command.

Note: If you want to upgrade an existing Photon 1.0 VM, refer to the instructions in the Upgrading to Photon OS 4.0 section.

6.1 - Prerequisites for Running Photon OS on Fusion

Resource requirements and recommendations vary depending on several factors, including the host environment (for example, VMware Fusion and VMware vSphere), the distribution file used (ISO or OVA), and the selected installation settings (for example, full or basic installation).

Before you use Photon OS within Fusion, perform the following prerequisite tasks:

  1. Verify that you have the following resources:

    ResourceDescription
    VMware FusionVMware Fusion (v7.0 or higher) must be installed. The latest version (v12) is recommended.
    Memory2GB of free RAM (recommended)
    StorageMinimal Photon install : 512MB of free space (minimum); Full Photon install : 4GB of free space (minimum); 8GB recommended.
    Distribution FilePhoton OS ISO or OVA file downloaded from [https://packages.vmware.com/photon/](https://packages.vmware.com/photon/).

    Note: The setup instructions in this guide use VMware Fusion Professional version 8.5.8, as per the following screenshot.

    Fusion version

  2. Decide whether to use the OVA or ISO distribution to set up Photon OS.

    • OVA import : Because of the nature of an OVA, you’re getting a pre-installed version of Photon OS. You can choose the hardware version you want (OVA with hardware version 13 or 11). The OVA benefits from a simple import process and some kernel tuning for VMware environments. However, because it’s a pre-installed version, the set of packages that are installed are predetermined. Any additional packages that you need can be installed using tdnf.
    • ISO install : The ISO, on the other hand, allows for a more complete installation or automated installation via kickstart.

    To get Photon OS up and running quickly, use the OVA.

  3. Download Photon OS. Go to the following URL and download the latest release of Photon OS:

    https://packages.vmware.com/photon/

    For instructions, see Downloading Photon OS.

6.2 - Importing the OVA for Photon OS 4.0

Using the OVA is a fast and easy way to create a Photon OS VM on Fusion.

After you have downloaded the Photon OS OVA image (OVA with Hardware Version 11) into a folder of your choice, open VMware Fusion and perform the following steps:

  1. Start the Import Process

    From the File menu, choose Import …. Fusion prompts you to choose an existing virtual machine.

    Import process

    Choose the Choose File … button to locate and select the Photon OS OVA, then choose Continue.

    Select OVA

  2. Specify the Name and Storage Location

    Provide the name and storage location for your Photon OS VM, then choose Save.

    Name and storage location

    Review the Photon OS License Agreement, then choose Accept to start the import process.

    License

  3. Configure VM Settings

    After the OVA is imported, Fusion displays a confirmation that the import has completed and a summary of the settings for your Photon OS VM. The following screen shot is an example (your settings may vary).

    VM settings

    Important: Choose Customize Settings to change the operating system (as recognized by the hypervisor) for the newly imported VM.

    Custom settings

    Choose General.

    Click the selection box next to OS, select Linux , and then select VMware Photon 64-bit.

    Operating system

    Close the settings window. Fusion prompts you to verify that you want to change the operating system.

    Confirm settings

    Click Change. Your Photon OS VM is ready to power on.

  4. Power on the VM

    Power on the Photon OS VM. Fusion may ask you whether you want to upgrade this VM.

    Upgrade VM

    How you respond depends on which hardware version (13 or 11) that you want to use. Upgrade if you need to use devices supported only in hardware version 13. Don’t upgrade if you want to be compatible with older tools that are supported in hardware version 11.

  5. Update Login Credentials

    Login prompt

    After the VM is booted, Fusion prompts you to log in.

    Note : Because of limitations within OVA support on Fusion, it was necessary to specify a default password for the OVA option. However, all Photon OS instances that are created by importing the OVA will require an immediate password change upon login. The default account credentials are:

    • Username: root
    • Password: changeme

    After you provide these credentials, Fusion prompts you to create a new password and type it a second time to verify it. For security, Photon OS forbids common dictionary words for the root password. Once logged in, you will see the shell prompt.

Once complete, proceed to Deploying a Containerized Application in Photon OS.

6.3 - Installing the ISO Image for Photon OS 4.0

After you have downloaded the latest Photon OS ISO image into a folder of your choice, open VMware Fusion.

  1. Start the Installation Process

    From the File menu, choose New.

    Installation

    From the Select the Installation Method dialog, select Install from disc or image, and then choose Continue.

    Installation method

  2. Select the ISO Image

    Drag a disc image onto the window or choose Use another disc or disc image…, choose the ISO file you want, and then choose Continue.

    ISO image

  3. Select the Operating System

    On the Choose Operating System dialog, select Linux in the left-hand column and VMware Photon 64-bit in the right-hand column.

    Operating system

    Choose Continue.

  4. Select the Virtual Disk (Optional)

    If you are using a Fusion version that is older than Fusion 8, you might see the following dialog.

    Virtual disk

    If you see this dialog, unless you’re installing into an existing machine, choose Create a new virtual disk from the Choose a Virtual Disk dialog, and then choose Continue.

    Note: Fusion v8 and later automatically defaults to creating a new 8GB disk and formats it automatically. If you want to use an existing disk, or if you want to pre-allocate all 8GB, go into VM Settings, choose Add Device, and choose either New Hard Disk or Existing Hard Disk. Expand Advanced options and configure whether you want to pre-allocate disk space (disabled by default) or split into multiple files (enabled by default).

  5. Configure VM Settings

    Important: Before you finish creating the Photon OS Virtual Machine, we strongly recommend that you customize the virtual machine and remove any unwanted devices that are not needed for a container run-time environment.

    VM settings

    To remove unnecessary devices, choose Customize Settings.

    First, choose a name for your Virtual Machine, along with the folder into which you create the Virtual Machine (or accept the default folder).

    Custom settings

    Choose Save. The virtual machine will be created. The Settings screen allows you to customize virtual hardware for the new virtual machine. If it does not automatically appear, open Settings from the Virtual Machine menu bar.

    Settings

    You can remove (recommended) the following components that are not used by Photon OS:

    • Select Display and ensure that the Accelerate 3D Graphics option is unchecked (it should be unchecked, by default). Select Show All to return to the VM Settings.
    • Select CD/DVD (IDE) and ensure that the Connect CD/DVD Drive box is checked (it should be checked by default). Select Show All to return to the VM Settings.
    • Select Sound Card, un-check the Connect Sound Card Option, and click Remove Sound Card. Choose Remove to confirm your action. Select Show All to return to the VM Settings.
    • Select USB & Bluetooth and uncheck the Share Bluetooth devices with Linux setting. Select Show All to return to the VM Settings.
    • Select Printer and press the Remove Printer Port button in the bottom left hand corner. Choose Remove to confirm your action. Select Show All to return to the VM Settings.
    • Select Camera and press the Remove Camera button in the bottom left hand corner. Choose Remove to confirm your action. Select Show All to return to the VM Settings.
    • Select Advanced and ensure that the Pass Power Status to VM option is unchecked (it should be unchecked, by default). Select Show All, but do not close the VM Settings window.

    By default, Photon OS is configured with a disk size of 8GB. However, Photon OS uses only the portion of disk space it needs, usually much less that the entire disk size. If you want to pre-allocate the entire disk size (reserving it entirely for Photon OS instead), select Hard Disk, expand Advanced options, and check Pre-allocate disk space (by default, it is unchecked). Select Show All to return to the VM Settings.

  6. Configure a Secure Boot (Optional)

    Note: If you want to configure a secure boot for the Photon OS VM you created, edit its .vmx file and add the following line:

    firmware = “efi”

    The EFI boot ensures that the ISO content is signed by VMware and that the entire stack is secure.

    After you have made the customizations you want, close the Virtual Machine Settings window. You are now ready to boot and begin the installation process.

  7. Power On the VM

    Return to the Fusion main menu, select the Photon OS Virtual Machine, and click Start Up (you can also choose Start Up from the Virtual Machine menu).

    Fusion powers on the host and starts the installation. Within a few seconds, Fusion displays the Photon OS installer boot menu.

    Photon OS installer

    Press the Enter key on your keyboard to start installing.

    License

    Read the License Agreement and press the Enter key to accept.

  8. Configure the Partition

    The Installer will detect one disk, which should be the 8GB volume configured as part of the virtual machine creation.

    Partition

    Choose Auto to have the installer automatically allocate the partition, or choose Custom if you want to configure individual partitions, and then press the Enter key.

    Note: If you choose Custom, the installer displays the following screen.

    Custom partition

    For each custom partition, choose Create New and specify the following information:

    New partition

    Size - Preallocated size of this partition, in MB.

    Type - One of the following options:

    • ext3 - ext3 file system
    • ext4 - ext4 file system
    • swap - swap partition

    Mountpoint - Mount point for this partition.

    Choose OK and press the Enter key. When you are done defining custom partitions, choose Next and press the Enter key.

    The installer prompts you to confirm that you want to erase the entire disk.

    Disk erase

    Choose Yes and press the Enter key to accept and proceed with the installation.

  9. Select an Installation Option

    After partitioning, the installer prompts you to select one of three installation options:

    Installation options

    Each install option provides a different run-time environment. Select the option that best meets your requirements.

    OptionDescription
    Photon MinimalPhoton Minimum is a very lightweight version of the container host runtime that is best suited for container management and hosting. There is sufficient packaging and functionality to allow most common operations around modifying existing containers, as well as being a highly performant and full-featured runtime.

    Photon FullPhoton Full includes several additional packages to enhance the authoring and packaging of containerized applications and/or system customization. For simply running containers, Photon Full will be overkill. Use Photon Full for developing and packaging the application that will be run as a container, as well as authoring the container, itself. For testing and validation purposes, Photon Full will include all components necessary to run containers.
    Photon OSTree ServerThis installation profile will create the server instance that will host the filesystem tree and managed definitions for rpm-ostree managed hosts created with the "Photon OSTree Host" installation profile. Most environments should need only one Photon OSTree Server instance to manage the state of the Photon OSTree Hosts. Use Photon OSTree Server when you are establishing a new repository and management node for Photon OS hosts.

    Note: The option you choose determines the disk and memory resources required for your installation.

    Select the option you want and press the Enter key.

  10. The Network Configuration screen appears, select one of the four options to configure your network. Network Sonfiguration

    1. Choose Configure network automatically and select Next to configure the network automatically.

    2. To configure network automatically with the DHCP hostname, select Configure network automatically with a DHCP hostname and select Next. Enter the DHCP Hostname and select Next. ../images/DHCP_hostname_for_your_system.png

    3. To configure the network manually, select Configure Network manually. In the window that appears, enter the IP Address, Netmask, Gateway and Nameserver and select OK. ../images/Configure_Network_Manually.png

    4. If your network interface is directly connected to the VLAN trunk port, choose YES on the Configure the network screen. Enter the VLAN ID and select Next. Configure the network.

  11. Select the Linux Kernel

    The installer prompts you to select the Linux kernel to install:

    Linux kernel

    • Hypervisor optimized means that any components that are not needed for running under a VMware hypervisor have been removed for faster boot times.
    • Generic means that all components are included.
  12. Specify the Hostname

    The installer prompts you for a hostname and suggest a randomly generated, unique hostname that you can change if you want.

    Hostname

    Press the Enter key.

  13. Specify the System root Password

    Note: Photon OS will not permit commonly used dictionary words to be set as a root password.

    The installer prompts you to enter the system root password. Type the password, and then press the Enter key.

    Password

    Confirm the root password by typing it a second time.

    Password confirmation

    Press the Enter key. The installer proceeds to install the software. Installation times will vary based on the system hardware and installation options you selected. Most installations complete in less than one minute.

    Once finished, the installer displays a confirmation message (which includes how long it took to install Photon OS) and prompts you to press a key on your keyboard to boot the new VM.

    Confirmation

  14. Reboot the VM and Log In

    Press any key on the keyboard and the virtual machine will reboot into Photon OS.

    Reboot

    As the initial boot process begins, the installer displays the Photon splash screen, and then a login prompt.

    At the login prompt, enter root as the username and provide the password chosen during the installation.

    Password

You can now use your container runtime environment and deploy a containerized application.

7 - Running Photon OS on Workstation

You can use Photon OS as a virtual machine within VMware Workstation. You can download Photon OS, as an OVA or ISO file, and install the Photon OS distribution on vSphere. After you install Photon OS, you can deploy a containerized application in Docker with a single command.

Note: If you want to upgrade an existing Photon 1.0 VM, refer to the instructions in the Upgrading to Photon OS 4.0 section.

7.1 - Prerequisites for Running Photon OS on Workstation

Before you use Photon OS within Workstation, perform the following prerequisite tasks:

  1. Verify that you have the following resources:

    ResourceDescription
    VMware WorkstationVMware Workstation must be installed (Workstation 10 or higher). The latest version is recommended.

    Memory2GB of free RAM (recommended)
    StorageMinimal Photon install: 512MB of free space (minimum); Full Photon install: 4GB of free space (minimum); 8GB is recommended.
    Distribution FilePhoton OS ISO or OVA file downloaded from VMware (https://packages.vmware.com/photon/4.0/GA/).

    Resource requirements and recommendations vary depending on several factors, including the host environment (for example, VMware Workstation and VMware vSphere), the distribution file used (ISO or OVA), and the selected installation settings (for example, full or basic installation).

    Note: The setup instructions in this guide use VMware Workstation Professional version 12.5.7.

    Workstation version

  2. Decide whether to use the OVA or ISO distribution to set up Photon OS.

  • OVA import : Because of the nature of an OVA, you’re getting a pre-installed version of Photon OS. You can choose the hardware version you want (OVA with hardware version 13 or 11). The OVA benefits from a simple import process and some kernel tuning for VMware environments. However, because it’s a pre-installed version, the set of packages that are installed are predetermined. Any additional packages that you need can be installed using tdnf.

  • ISO install : The ISO, on the other hand, allows for a more complete installation or automated installation via kickstart.

To get Photon OS up and running quickly, use the OVA.

  1. Download Photon OS. Go to the following URL and download the latest release of Photon OS:

    https://packages.vmware.com/photon/4.0/GA/

    For instructions, see Downloading Photon OS.

7.2 - Importing the OVA for Photon OS 4.0

Using the OVA is the easiest way to create a Photon OS VM on VMware Workstation.

After you have downloaded the the OVA file (OVA with Hardware Version 11), perform the following steps:

  1. Start the Import Process

    • Double-click it to start the import process, or
    • Start VMware Workstation and, from the File menu, choose Open.

    OVA file

  2. Specify the Name and Storage Location

    Change the name and storage location, if you want.

    Name and Storage Location

    Choose Import.

    License

    Review the License Agreement and choose Accept.

  3. Configure VM Settings

    Once the OVA is imported, Workstation displays a summary of the settings for your Photon OS VM.

    Settings

    Choose Edit virtual machine settings. Workstation displays the Virtual Machine settings. You can either accept the defaults or change settings as needed.

    OVA settings

    Select the Options tab.

    Options

    Under Guest operating system, select Linux.

    For Version, click the list and select VMWare Photon 64-bit.

    Version

    Note: If you want to configure a secure boot for the Photon OS VM, select Advanced and select (check) Boot with EFI instead of BIOS. The EFI boot ensures that the ISO content is signed by VMware and that the entire stack is secure.

    EFI boot

    Choose OK.

  4. Power on the VM

    From the tab, choose Power on this virtual machine.

    Login prompt

    After the splash screen, Workstation will prompt you to log in.

  5. Update Login Credentials

    Note : Because of limitations within OVA support on Workstation, it was necessary to specify a default password for the OVA option. However, all Photon OS instances that are created by importing the OVA will require an immediate password change upon login. The default account credentials are:

    • Username: root
    • Password: changeme

    After you provide these credentials, Workstation prompts you to create a new password and type it a second time to verify it. For security, Photon OS forbids common dictionary words for the root password. Once logged in, you will see the shell prompt.

    Once complete, proceed to Deploying a Containerized Application in Photon OS.

7.3 - Installing the ISO Image for Photon OS 4.0

After you have downloaded the latest Photon OS ISO image into a folder of your choice, open VMware Workstation.

  1. Start the Installation Process

    From the File menu, choose New Virtual Machine to create a new virtual machine.

    New virtual machine

    Select Typical or Custom, and then choose Next. These instructions refer to a Typical installation.

    Typical installation

  2. Select the ISO Image

    Select Installer disc image file (iso), choose Browse and select the Photon OS ISO file.

    Photon ISO file

  3. Select the Operating System

    Choose Next. Select the Guest operating system.

    For the Guest operating system, select Linux.

    Click the Version dropdown and select VMware Photon 64-bit from the list.

    Operating System

  4. Specify the VM Name and Location

    Choose Next. Specify a virtual machine name and location.

    VM Name and Location

  5. Specify Disk Options

    Choose Next. Specify the maximum disk size and whether you want to split the virtual disk into multiple files or store it as a single file.

    Disk options

  6. Configure VM Settings

    Choose Next. Workstation displays a summary of your selections.

    Workstation settings

    Important : Before you finish creating the Photon OS Virtual Machine, we strongly recommend that you customize the virtual machine and remove any unwanted devices that are not needed for a container run-time environment. To remove unnecessary devices, choose Customize hardware.

    Customize hardware

    Consider removing the following components, which are not used by Photon OS:

    • Select Sound Card, un-tick the Connect at power on option. Confirm your action and choose Close to return to the VM Settings by .
    • Select USB Controller and ensure that the Share Bluetooth devices with the virtual machine setting is unchecked (it should be unchecked, by default) and then choose Close.
    • Select Display and ensure that the Accelerate 3D Graphics option is unchecked (it should be unchecked, by default) and then choose Close.
    • At this stage we have now made all the necessary customizations and you are ready to select the Photon OS ISO image to boot and begin the installation process.
    • Choose Finish.

    In Workstation, choose Edit virtual machine settings, select CD/DVD (IDE), and verify that Connect at power on is selected.

    CD/DVD

  7. Configure a Secure Boot (Optional)

    Note: If you want to configure a secure boot for the Photon OS VM, in Workstation, choose Edit virtual machine settings, select Options, choose Advanced, and select Boot with EFI instead of BIOS.

    Boot with EFI

    The EFI boot ensures that the ISO content is signed by VMware and that the entire stack is secure.

    Choose OK.

    ISO settings

  8. Power On the VM

    Choose Power on this virtual machine.

    When you see the Photon Installer boot menu, press Enter on your keyboard to start installing.

    Installer

    Review the license agreement.

    License agreement

    Choose Accept and press Enter.

  9. Configure the Partition

    The installer will detect one disk, which should be the 8GB volume configured as part of the virtual machine creation. Choose Auto to have the installer automatically allocate the partition, or choose Custom if you want to configure individual partitions, and then press the Enter key.

    Partition

    Note: If you choose Custom, the installer displays the following screen.

    Custom Partition

    For each custom partition, choose Create New and specify the following information:

    New Partition

    Size - Preallocated size of this partition, in MB.

    Type - One of the following options:

    • ext3 - ext3 file system
    • ext4 - ext4 file system
    • swap - swap partition

    Mountpoint - Mount point for this partition.

    Choose OK and press the Enter key. When you are done defining custom partitions, choose Next and press the Enter key.

    The installer prompts you to confirm that you want to erase the entire disk. Choose Yes and press the Enter key.

    Erase disk

  10. Select an Installation Option

    After partitioning the disk, the installer will prompt you to select an installation option.

    Installation Option

    Each installation option provides a different run-time environment, depending on your requirements.

    OptionDescription
    Photon MinimalPhoton Minimum is a very lightweight version of the container host runtime that is best suited for container management and hosting. There is sufficient packaging and functionality to allow most common operations around modifying existing containers, as well as being a highly performant and full-featured runtime.

    Photon FullPhoton Full includes several additional packages to enhance the authoring and packaging of containerized applications and/or system customization. For simply running containers, Photon Full will be overkill. Use Photon Full for developing and packaging the application that will be run as a container, as well as authoring the container, itself. For testing and validation purposes, Photon Full will include all components necessary to run containers.
    Photon OSTree ServerThis installation profile will create the server instance that will host the filesystem tree and managed definitions for rpm-ostree managed hosts created with the "Photon OSTree Host" installation profile. Most environments should need only one Photon OSTree Server instance to manage the state of the Photon OSTree Hosts. Use Photon OSTree Server when you are establishing a new repository and management node for Photon OS hosts.

    Note: The option you choose determines the disk and memory resources required for your installation.

    Select the option you want and press the Enter key.

  11. The Network Configuration screen appears, select one of the four options to configure your network. Network Sonfiguration

    1. Choose Configure network automatically and select Next to configure the network automatically.

    2. To configure network automatically with the DHCP hostname, select Configure network automatically with a DHCP hostname and select Next. Enter the DHCP Hostname and select Next. ../images/DHCP_hostname_for_your_system.png

    3. To configure the network manually, select Configure Network manually. In the window that appears, enter the IP Address, Netmask, Gateway and Nameserver and select OK. ../images/Configure_Network_Manually.png

    4. If your network interface is directly connected to the VLAN trunk port, choose YES on the Configure the network screen. Enter the VLAN ID and select Next. Configure the network.

  12. Select the Linux Kernel

    Select a Linux kernel to install.

    Linux Kernel

    • Hypervisor optimized means that any components that are not needed for running under a VMware hypervisor have been removed for faster boot times.
    • Generic means that all components are included.

    Choose Next and press the Enter key.

  13. Specify the Hostname

    The installer prompts you for a hostname and suggest a randomly generated, unique hostname that you can change if you want.

    Hostname

    Press the Enter key.

  14. Specify the System root Password

    Note : Photon OS will not permit commonly used dictionary words to be set as a root password.

    The installer prompts you to enter the system root password. Type the password and press the Enter key.

    Root password

    The installer prompts you to confirm the root password by typing it a second time.

    Password confirmation

    Press the Enter key. The installer proceeds to install the software. Installation times will vary based on the system hardware and installation options you selected. Most installations complete in less than one minute.

  15. Reboot the VM and Log In

    Once finished, the installer displays a confirmation message (which includes how long it took to install Photon OS) and prompts you to press a key on your keyboard to boot the new VM.

    Boot VM

    Press any key on the keyboard and the virtual machine will reboot into Photon OS.

    As the initial boot process begins, the installer displays the Photon splash screen, and then a login prompt.

    Login prompt

    At the login prompt, type root as the username and provide the password chosen during the installation.

    Password

You can now use your container runtime environment and deploy a containerized application.

8 - Running Photon OS on Amazon Elastic Cloud Compute

You can set up Photon OS on Amazon Web Services Elastic Cloud Compute (EC2), customize it with cloud-init, connect to it with SSH.

After you set up Photon OS, you can run a containerized application.

8.1 - Prerequisites for Running Photon OS on AWS EC2

Before you use Photon OS with Amazon Elastic Cloud Compute(AWS EC2), perform the following prerequisite tasks:

  1. Verify that you have the following resources:

    • AWS account. Working with EC2 requires an Amazon account for AWS with valid payment information. Keep in mind that, if you try the examples in this document, you will be charged by Amazon. See Setting Up with Amazon EC2.
    • Amazon tools. The following examples also assume that you have installed and configured the Amazon AWS CLI and the EC2 CLI and AMI tools, including ec2-ami-tools.

    For more information, see Installing the AWS Command Line Interface, Setting Up the Amazon EC2 Command Line Interface Tools on Linux, and Configuring AWS Command-Line Interface. Also see Setting Up the AMI Tools.

    The procedure in this section uses an Ubuntu 14.04 workstation to generate the keys and certificates that AWS requires.

  2. Download the Photon OS image for Amazon.

    VMware packages Photon OS as a cloud-ready Amazon machine image (AMI) that you can download for free from https://packages.vmware.com/photon/.

    Download the Photon OS AMI and save it on your workstation. For more information, see Downloading Photon OS.

    Note: The AMI version of Photon is a virtual appliance with the information and packages that Amazon needs to launch an instance of Photon in the cloud. To build the AMI version, VMware starts with the minimal version of Photon OS and adds the sudo and tar packages to it.

8.2 - Set Up Photon OS on EC2

To run Photon OS on EC2, you must use cloud-init with an EC2 data source. The cloud-init service configures the cloud instance of a Linux image. An instance is a virtual server in the Amazon cloud.

The examples in this section show how to generate SSH and RSA keys for your Photon instance, upload the Photon OS .ami image to the Amazon cloud, and configure it with cloud-init. In the examples, replace information with your own paths, account details, or other information from Amazon.

Perform the following steps to set up Photon OS on EC2

  1. Create a key pair.

    Generate SSH keys on, for instance, an Ubuntu workstation:

    ssh-keygen -f ~/.ssh/mykeypair
    

    The command generates a public key in the file with a .pub extension and a private key in a file with no extension. Keep the private key file and remember the name of your key pair. The name is the file name of the two files without an extension. You will need the name later to connect to the Photon instance.

    Change the mode bits of the public key pair file to protect its security. In the command, include the path to the file if you need to.

    chmod 600 mykeypair.pub
    

    Change the mode bits on your private key pair file so that only you can view it:

    chmod 400 mykeypair
    

    To import your public key pair file, but not your private key pair file, connect to the EC2 console at https://console.aws.amazon.com/ec2/ and select the region for the key pair. A key pair works only in one region, and the instance of Photon OS that will be uploaded later must be in the same region as the key pair. Select key pairs under Network & Security, and then import the public key pair file that you generated earlier.

    For more information, see Importing Your Own Key Pair to Amazon EC2.

  2. Generate a certificate.

    When you bundle up an image for EC2, Amazon requires an RSA user signing certificate. You create the certificate by using openssl to first generate a private RSA key and then to generate the RSA certificate that references the private RSA key. Amazon uses the pairing of the private key and the user signing certificate for handshake verification.

  3. On Ubuntu 14.04 or another workstation that includes openssl, run the following command to generate a private key. If you change the name of the key, keep in mind that you will need to include the name of the key in the next command, which generates the certificate.

     openssl genrsa 2048 > myprivatersakey.pem
    

    Make a note of your private key as you will need it again later.

  4. Run the following command to generate the certificate. The command prompts you to provide more information, but because you are generating a user signing certificate, not a server certificate, you can just type Enter for each prompt to leave all the fields blank.

     openssl req -new -x509 -nodes -sha256 -days 365 -key myprivatersakey.pem -outform PEM -out certificate.pem
    

    For more information, see the Create a Private Key and the Create the User Signing Certificate sections of Setting Up the AMI Tools.

  5. Upload to AWS the certificate value from the certificate.pem file that you created in the previous command. Go to the Identity and Access Management console at https://console.aws.amazon.com/iam/, navigate to the name of your user, open the Security Credentials section, click Manage Signing Certificates, and then click Upload Signing Certificate. Open certificate.pem in a text editor, copy and paste the contents of the file into the Certificate Body field, and then click Upload Signing Certificate.

    For more information, see the Upload the User Signing Certificate section of Setting Up the AMI Tools.

  6. Create a security group.

    Create a security group and set it to allow SSH, HTTP, and HTTPS connections over ports 22, 80, and 443, respectively. Connect to the EC2 command-line interface and run the following commands:

     aws ec2 create-security-group --group-name photon-sg --description "My Photon security group"
     {
         "GroupId": "sg-d027efb4"
     }
     aws ec2 authorize-security-group-ingress --group-name photon-sg --protocol tcp --port 22 --cidr 0.0.0.0/0
    

    Make a note of the GroupId that is returned by EC2 as you will need it again later.

    By using 0.0.0.0/0 for SSH ingress on Port 22, you open the port to all IP addresses–which is not a security best practice but a convenience for the examples in this article. For a production instance or other instances that are anything more than temporary machines, you must authorize only a specific IP address or range of addresses. For more information, see Authorizing Inbound Traffic for Linux Instances.

    Repeat the command to allow incoming traffic on Port 80 and on Port 443:

     aws ec2 authorize-security-group-ingress --group-name photon-sg --protocol tcp --port 80 --cidr 0.0.0.0/0
    
     aws ec2 authorize-security-group-ingress --group-name photon-sg --protocol tcp --port 443 --cidr 0.0.0.0/0
    

    Check your update:

     aws ec2 describe-security-groups --group-names photon-sg
    
  7. Extract the tarball.

    Make a directory to store the image and then extract the Photon OS image from its archive by running the following tar command. If required, change the file name to match the version you have.

     mkdir bundled
     tar -zxvf ./photon-ami.tar.gz
    
  8. Bundle the image.

    Run the ec2-bundle-image command to create an instance store-backed Linux AMI from the Photon OS image that you extracted in the previous step. The result of the ec2-bundle-image command is a manifest that describes the machine in an XML file.

    The command uses the certificate path to your PEM-encoded RSA public key certificate file, the path to your PEM-encoded RSA private key file, your EC2 user account ID; the correct architecture for Photon OS, the path to the Photon OS AMI image extracted from its tar file, and the bundled directory from the previous step.

    Replace the values of the certificate path, the private key, and the user account with your own values.

     $ ec2-bundle-image --cert certificate.pem --privatekey myprivatersakey.pem --user <EC2 account id>  --arch x86_64 --image photon-ami.raw --destination ./bundled/
    
  9. Put the bundle in a bucket.

    Make an S3 bucket, replacing <bucket-name> with the name that you want. The command creates the bucket in the region specified in your Amazon configuration file, which should be the same region in which you are using your key pair file:

     $ aws s3 mb s3://<bucket-name>
    

    Upload the bundle to the Amazon S3 cloud. The following command includes the path to the XML file containing the manifest for the Photon OS machine created during the previous step, though you might have to change the file name to match the version you have. The manifest file is typically located in the same directory as the bundle.

    The command also includes the name of the Amazon S3 bucket in which the bundle is to be stored; your AWS access key ID; and your AWS secret access key.

     $ ec2-upload-bundle --manifest ./bundled/photon-ami.manifest.xml --bucket <bucket-name> --access-key <Account Access Key> --secret-key <Account Secret key>
    
  10. Register the Image

    Run the following command to register the image. The command includes a name for the AMI, its architecture, and its virtualization type. The virtualization type for Photon OS is hvm.

     $ ec2-register <bucket-name>/photon-ami.manifest.xml --name photon-ami --architecture x86_64 --virtualization-type hvm
    

    Once the image is registered, you can launch as many new instances as you require.

  11. Run an instance of the image with Cloud-Init.

    In the below command, the user-data-file option instructs cloud-init to import the cloud-config data in user-data.txt.

    Before you run the command, change directories to the directory containing the mykeypair file and add the path to the user-data.txt.

     $ ec2-run-instances <ami-ID> --instance-type m3.medium -g photon-sg --key mykeypair --user-data-file user-data.txt
    

    The command also includes the ID of the AMI, which you can obtain by running ec2-describe-images. Replace the instance type of m3.medium and the name of key pair with your own values to be able to connect to the instance.

    The following are the contents of the user-data.txt file that cloud-init applies to the machine the first time it boots up in the cloud.

     #cloud-config
     hostname: photon-on-01
     groups:
     - cloud-admins
     - cloud-users
     users:
     - default
     - name: photonadmin
        gecos: photon test admin user
        primary-group: cloud-admins
        groups: cloud-users
        lock-passwd: false
        passwd: vmware
     - name: photonuser
        gecos: photon test user
        primary-group: cloud-users
        groups: users
        passwd: vmware
     packages:
     - vim
    
  12. Get the IP address of your image.

    Run the following command to check on the state of the instance that you launched:

     $ ec2-describe-instances
    

    Obtain the external IP address of the instance by running the following query:

     $ aws ec2 describe-instances --instance-ids <instance-id> --query 'Reservations[*].Instances[*].PublicIpAddress' --output=text
    

    Optionally, check the cloud-init output log file on EC2 at /var/log/cloud-init-output.log to see how EC2 handles the settings in the cloud-init data file.

    For more information on using cloud-init user data on EC2, see Running Commands on Your Linux Instance at Launch.

8.3 - Deploy a Containerized Application in Photon OS

Connect to the Photon instance by using SSH and to launch a web server by running it in Docker.

  1. Connect with SSH

    Connect to the instance over SSH by specifying the private key (.pem) file and the user name for the Photon machine, which is root:

     ssh -i ~/.ssh/mykeypair root@<public-ip-address-of-instance>
    

    For complete instructions, see Connecting to Your Linux Instance Using SSH.

  2. Run Docker

    On the minimal version of Photon OS, the docker engine is enabled and running by default, which you can see by running the following command:

     systemctl status docker
    
  3. Start the web server

    Note: Please make sure that the proper security policies have been enabled on the Amazon AWS side to enable traffic to port 80 on the VM.

    Since Docker is running, you can run an application in a container–for example, the Nginx Web Server. This example uses the popular open source web server Nginx. The Nginx application has a customized VMware package that the Docker engine can download directly from the Docker Hub.

    To pull Nginx from its Docker Hub and start it, run the following command:

    docker run -p 80:80 vmwarecna/nginx
    

    The Nginx web server should be bound to the public DNS value for the instance of Photon OS, that is, the same address with which you connected over SSH.

  4. Test the web server

    On your local workstation, open a web browser and go to the the public address of the Photon OS instance running Docker. The following screen should appear, showing that the web server is active:

    Nginx

    Stop the Docker container by typing Ctrl+c in the SSH console through which you are connected to EC2.

You can now run other containerized applications from the Docker Hub or your own containerized application on Photon OS in the Amazon cloud.

8.4 - Launch the Web Server with Cloud-Init

To eliminate the manual effort of running Docker, you can add docker run and its arguments to the cloud-init user data file by using runcmd:

#cloud-config
hostname: photon-on-01
groups:
- cloud-admins
- cloud-users
users:
- default
- name: photonadmin
   gecos: photon test admin user
   primary-group: cloud-admins
   groups: cloud-users
   lock-passwd: false
   passwd: vmware
- name: photonuser
   gecos: photon test user
   primary-group: cloud-users
   groups: users
   passwd: vmware
packages:
- vim
runcmd:
- docker run -p 80:80 vmwarecna/nginx

To try this addition, run another instance with the new cloud-init data source and then get the public IP address of the instance to check that the Nginx web server is running.

8.5 - Terminate the AMI Instance

Because Amazon charges you while the instance is running, you must shut it down when you have finished using it.

  1. Get the ID of the AMI so you can terminate it:
$ ec2-describe-instances
  1. Terminate the Photon OS instance by running the following command:
$ ec2-terminate-instances <instance-id>

Replace the placeholder with the ID that the ec2-describe-images command returned. If you ran a second instance of Photon OS with the cloud-init file that runs docker, terminate that instance as well.

9 - Running Photon OS on Microsoft Azure

You can use Photon OS as a run-time environment for Linux containers on Microsoft Azure. You can set up and run the cloud-ready version of Photon OS as an instance of a virtual machine in the Azure cloud. Once Photon OS is running, you can deploy a containerized application in Docker.

Note: These instructions apply to Photon OS 2.0 and 3.0. There is no Photon OS 1.0 distribution image for Microsoft Azure.

9.1 - Prerequisites for Running Photon OS on Azure

Before you use Photon OS with Microsoft Azure, perform the following prerequisite tasks:

  1. Verify that you have a Microsoft Azure account. To create an account, see https://azure.microsoft.com

  2. Install the latest version of Azure CLI. See Install Azure CLI and Get started with Azure CLI .

  3. Verify that that you have a pair of SSH public and private keys.

  4. Download and extract the Photon OS VHD file.

    VMware packages Photon OS as an Azure-ready virtual hard disk (VHD file) that you can download for free from the VMware Photon Packages site. This VHD file is a virtual appliance with the information and packages that Azure needs to launch an instance of Photon in the cloud. After you have downloaded the distribution archive, extract the VHD file from it. You will later need to upload this VHD file to Azure, where it will be stored in an Azure storage account. For more information, see Downloading Photon OS.

9.2 - Set Up Azure Storage and Uploading the VHD

You can use either the Azure Portal or the Azure CLI to set up your Azure storage space, upload the Photon OS VHD file, and create the Photon OS VM.

Setting Up Using the Azure Portal

You can use the Azure portal to set up Photon OS 4.0 in the Azure cloud. The following instructions are brief. Refer to the Azure documentation for details.

  1. Log in to the Azure portal at http://portal.azure.com.
  2. Create a resource group. In the toolbar, choose Resource Groups, click +Add , fill in the resource group fields, and choose Create.
  3. Create a storage account. In the toolbar, choose Storage Accounts, click +Add , fill in the storage account fields (and the resource group you just created), and choose Create.
  4. Select the storage account.
  5. Scroll down the storage account control bar, click Containers (below BLOB SERVICE), click +Container , fill in the container fields, and choose Create.
  6. Select the container you just created.
  7. Click Upload and upload the Photon OS VHD image file to this container.
  8. Once the VHD file is uploaded, refer to the Azure documentation for instructions on how to create and manage your Photon OS VM.

Setting Up Using the Azure CLI

You can use the Azure CLI to set up Photon OS.

Note: Except where overridden with parameter values, these commands create objects with default settings.

  1. Create a resource group.

    From the Azure CLI, create a resource group.

    az group create \
     --name &lt;your_resource_group&gt; \
     --location westus
    
  2. Create a storage account

    Create a storage account associated with this resource group.

    az storage account create \
        --resource-group &lt;your_resource_group&gt; \
        --location westus \
        --name &lt;your_account_name&gt; \
        --kind Storage \
        --sku Standard_LRS
    
  3. List the Keys for the Storage Account

    Retrieve the keys associated with your newly created storage account.

    az storage account keys list \
        --resource-group &lt;your_resource_group&gt; \
        --account-name &lt;your_account_name&gt;
    
  4. Create the Storage Container

    Create a storage container associated with your newly created storage account.

    Note: The sample create.sh script, described below, does this for you programmatically.

    az storage container create \
        --account-name &lt;your_account_name&gt; \
        --name &lt;your_container_name&gt;
    
  5. Verify Your Setup in the Azure Portal

    1. Log into the Azure portal using your account credentials.
    2. From the left toolbar, click Storage Accounts. You should see your storage accounts.
    3. Select the storage account.
    4. Scroll down the storage account control bar and click Containers (below BLOB SERVICE). You should see the container you created.
  6. Upload the Photon OS Distribution to Your Storage Container

    The Photon OS distribution for Azure is 16GB. You can download it locally or to a mounted, shared location.

    az storage blob upload \
        --account-name &lt;your_account_name&gt; \
        --account-key &lt;your_account_key&gt; \
        --container-name &lt;your_container_name&gt; \
        --type page \
        --file &lt;vhd_path&gt; \
        --name &lt;vm_name&gt;.vhd
    

Example Setup Script

You can use the following script (create.sh) to upload your VHD file programmatically and create the VM. Before you run it, specify the following settings:

  • resource_group name
  • account_name
  • account_key (public or private)
  • container_name
  • public_key_file
  • vhd_path and and vm_name of the Photon OS VHD distribution file

The following script returns the complete IP address of the newly created VM.

#!/bin/bash
vhd_path=$1
vm_name=$2
export PATH=$PATH:/root/azure_new/bin/az
echo PATH=$PATH
resource_group=&quot;&quot;
account_name=&quot;&quot;
account_key=&quot;&quot;
container_name=&quot;mydisks&quot;
url=&quot;https://${account_name}.blob.core.windows.net/${container_name}/${vm_name}.vhd&quot;
public_key_file=&quot;/root/azure_new/jenkins.pub&quot;
echo &quot;########################&quot;
echo &quot;#   Create container   #&quot;
echo &quot;########################&quot;
/root/azure_new/bin/az storage container create --account-name ${account_name} --name ${container_name}
echo &quot;##################&quot;
echo &quot;#   Upload vhd   #&quot;
echo &quot;##################&quot;
/root/azure_new/bin/az storage blob upload --account-name ${account_name} \
    --account-key ${account_key} \
    --container-name ${container_name} \
    --type page \
    --file ${vhd_path} \
    --name ${vm_name}.vhd
echo &quot;##################&quot;
echo &quot;#   Create vm    #&quot;
echo &quot;##################&quot;
echo &quot;az vm create --resource-group ${resource_group} --location westus --name ${vm_name} --storage-account ${account_name} --os-type linux --admin-username michellew --ssh-key-value ${public_key_file} --image ${url} --use-unmanaged-disk ... ...&quot;
/root/azure_new/bin/az vm create --resource-group ${resource_group} --location westus --name ${vm_name} --storage-account ${account_name} --os-type linux --admin-username michellew --ssh-key-value ${public_key_file} --image ${url} --use-unmanaged-disk

9.3 - Remove Photon OS From Azure

You can use the following delete.sh script to programmatically and silently remove the VM instance, VHD file, and container.

Consider deleting idle VMs so that you are not charged when not in use.

Before you run it, specify the following settings:

  • resource_group name (from step 1, above)
  • account_name (from step 2, above)
  • account_key (public or private) (from step 3, above)
  • container_name (from step 4, above)
  • public_key_file
  • vm_name of the Photon OS VHD distribution file

delete.sh

#!/bin/bash
vm_name=$1
resource_group=&quot;&quot;
account_name=&quot;&quot;
account_key=&quot;&quot;
container_name=&quot;mydisks&quot;
url=&quot;https://${account_name}.blob.core.windows.net/${container_name}/${vm_name}.vhd&quot;
public_key_file=&quot;/root/azure_new/jenkins.pub&quot;
exit_code=0
echo &quot;##################&quot;
echo &quot;#   Delete vm    #&quot;
echo &quot;##################&quot;
echo &quot;az vm list  --resource-group ${resource_group} ... ...&quot;
/root/azure_new/bin/az vm list  --resource-group ${resource_group}
echo &quot;az vm delete --resource-group ${resource_group} --name ${vm_name} --yes ... ...&quot;
/root/azure_new/bin/az vm delete --resource-group ${resource_group} --name ${vm_name} --yes
if [$? -ne 0];then
   exit_code=1
fi
echo &quot;az vm list  --resource-group ${resource_group} ... ...&quot;
/root/azure_new/bin/az vm list  --resource-group ${resource_group}
echo &quot;##############$####&quot;
echo &quot;#   Delete vhd    #&quot;
echo &quot;###############$###&quot;
echo &quot;az storage blob list --account-name ${account_name} --container-name ${container_name} ... ...&quot;
/root/azure_new/bin/az storage blob list --account-name ${account_name} --container-name ${container_name}
echo &quot;az storage blob delete --account-name ${account_name} --container-name ${container_name} --name ${vm_name}.vhd ... ...&quot;
/root/azure_new/bin/az storage blob delete --account-name ${account_name} --container-name ${container_name} --name ${vm_name}.vhd
if [$? -ne 0];then
   exit_code=1
fi
echo &quot;az storage blob list --account-name ${account_name} --container-name ${container_name} ... ...&quot;
/root/azure_new/bin/az storage blob list --account-name ${account_name} --container-name ${container_name}
echo &quot;########################&quot;
echo &quot;#   Delete container   #&quot;
echo &quot;########################&quot;
/root/azure_new/bin/az storage container delete --account-name ${account_name} --name ${container_name}
/root/azure_new/bin/az storage container delete --account-name ${account_name} --name vhds
exit ${exit_code}

You can now proceed to Deploying a Containerized Application in Photon OS.

10 - Running Photon OS on Google Compute Engine

You can use Photon OS as a virtual machine on Google Compute Engine (GCE). You can download Photon OS, as an OVA or ISO file, and install the Photon OS distribution on vSphere. After you install Photon OS, you can deploy a containerized application in Docker with a single command.

10.1 - Prerequisites for Running Photon OS on GCE

Before you use Photon OS within GCE, verify that you have the following resources:

  1. Google Compute Engine account
  2. GCE tools
  3. Photon OS Image

Google Compute Engine Account

Working with GCE requires a Google Compute Engine account with valid payment information. Keep in mind that, if you try the examples in this document, you will be charged by Google. The GCE-ready version of Photon OS is free to use.

GCE Tools

GCE is a service that lets you run virtual machines on Google’s infrastructure. You can customize the virtual machine as much as you want, and you can even install your own custom operating system image. Or, you can adopt one of the public images provided by Google. For any operating system to work with GCE, it must match Google’s infrastructure needs. Google provides tools that VM instances require to work correctly on GCE:

  • Google startup scripts: You can provide some startup script to configure your instances at startup.
  • Google Daemon: Google Daemon creates new accounts and configures ssh to accept public keys using the metadata server.
  • Google Cloud SDK: Command line tools to manage your images, instances and other objects on GCE.

Perform the following tasks to make Photon OS work on GCE:

  1. Install Google Compute Engine Image packages
  2. Install Google Cloud SDK
  3. Change GPT partition table to MBR
  4. Update the Grub config for new MBR and serial console output
  5. Update ssh configuration
  6. Delete ssh host keys
  7. Set the time zone to UTC
  8. Use the Google NTP server
  9. Delete the hostname file.
  10. Add Google hosts /etc/hosts
  11. Set MTU to 1460. SSH will not work without it.
  12. Create /etc/ssh/sshd_not_to_be_run with just the contents “GOOGLE\n”.

For more information see Importing Boot Disk Images to Compute Engine.

For information about upgrading the Photon OS Linux kernel see Upgrading the Kernel Version Requires Grub Changes for AWS and GCE Images

Photon OS Image

VMware recommends that administrators use the Photon OS image for Google Compute Engine (GCE) to create Photon OS instances on GCE. Photon OS bundles the Google startup scripts, daemon, and cloud SDK into a GCE-ready image that has been modified to meet the configuration requirements of GCE. You can download the Photon OS image for GCE from the following URL: https://packages.vmware.com/photon/4.0/GA/gce/

For instructions, see Downloading Photon OS.

Optionally you can customize Photon OS to work with GCE.

Creating Photon image for GCE

Perform the following tasks:

  1. Prepare Photon Disk

    1. Install Photon Minimal on Fusion/Workstation and install some required packages.
    mount /dev/cdrom /media/cdrom
    tdnf install python2-libs ntp sudo wget tar which gptfdisk sed findutils grep gzip -y
    
  2. Convert GPT to MBR and update Grub

    Photon installer installs GPT partition table by default but GCE only accepts an MBR (msdos) type partition table. So, you must convert GPT to MBR and update grub. Use the following commands to update the grub:

    # Change partition table to MBR from GPT
    sgdisk -m 1:2 /dev/sda
    grub2-install /dev/sda
    
    # Enable serial console on grub for GCE.
    cat << EOF >> /etc/default/grub
    GRUB_CMDLINE_LINUX="console=ttyS0,38400n8"
    GRUB_TERMINAL=serial
    GRUB_SERIAL_COMMAND="serial --speed=38400 --unit=0 --word=8 --parity=no --stop=1"
    EOF
    
    # Create new grub.cfg based on the settings in /etc/default/grub
    grub2-mkconfig -o /boot/grub2/grub.cfg
    
  3. Install Google Cloud SDK and GCE Packages

    tdnf install -y google-compute-engine google-compute-engine-services
    cp /usr/lib/systemd/system/google* /lib/systemd/system/
    cd /lib/systemd/system/multi-user.target.wants/
    
    # Create links in multi-user.target to auto-start these scripts and services.
    for i in ../google*; do  ln -s $i `basename $i`; done
    
    cd /tmp/; wget https://dl.google.com/dl/cloudsdk/release/google-cloud-sdk.tar.gz
    tar -xf google-cloud-sdk.tar.gz
    cd google-cloud-sdk
    ./install.sh
    
  4. Update /etc/hosts file with GCE values as follows:

    echo "169.254.169.254 metadata.google.internal metadata" >> /etc/hosts
    
  5. Remove all servers from ntp.conf and add Google’s ntp server.

    sed -i -e "/server/d" /etc/ntp.conf
    cat /etc/ntp.conf
    echo "server 169.254.169.254" >> /etc/ntp.conf
    # Create ntpd.service to auto starting ntp server.
    cat << EOF >> /lib/systemd/system/ntpd.service
    [Unit]
    Description=Network Time Service
    After=network.target nss-lookup.target
    
    [Service]
    Type=forking
    PrivateTmp=true
    ExecStart=/usr/sbin/ntpd -g -u ntp:ntp
    Restart=always
    
    [Install]
    WantedBy=multi-user.target
    EOF
    
    # Add link in multi-user.target.wants to auto start this service.
    cd /lib/systemd/system/multi-user.target.wants/
    ln -s ../ntpd.service ntpd.service
    
  6. Set UTC timezone

    ln -sf /usr/share/zoneinfo/UTC /etc/localtime
    
  7. Update /etc/resolv.conf

    echo "nameserver 8.8.8.8" >> /etc/resolv.conf
    
  8. Remove ssh host keys and add script to regenerate them at boot time.

    rm /etc/ssh/ssh_host_*
    # Depending on the installation, you may need to purge the following keys
    rm /etc/ssh/ssh_host_rsa_key*
    rm /etc/ssh/ssh_host_dsa_key*
    rm /etc/ssh/ssh_host_ecdsa_key*
    
    sed -i -e "/exit 0/d" /etc/rc.local
    echo "[ -f /etc/ssh/ssh_host_key ] && echo 'Keys found.' || ssh-keygen -A" >> /etc/rc.local
    echo "exit 0" >> /etc/rc.local
    printf "GOOGLE\n" > /etc/ssh/sshd_not_to_be_run
    
    # Edit sshd_config and ssh_config as per instructions on [this link](https://cloud.google.com/compute/docs/tutorials/building-images).
    
  9. Change MTU to 1460 for network interface.

     # Create a startup service in systemd that will change MTU and then exit
    
    cat << EOF >> /lib/systemd/system/eth0.service
    [Unit]
    Description=Network interface initialization
    After=local-fs.target network-online.target network.target
    Wants=local-fs.target network-online.target network.target
    
    [Service]
    ExecStart=/bin/ifconfig eth0 mtu 1460 up
    Type=oneshot
    
    [Install]
    WantedBy=multi-user.target
    EOF
    # Make this service auto-start at boot.
    cd /lib/systemd/system/multi-user.target.wants/
    ln -s ../eth0.service eth0.service
    
  10. Pack and upload to GCE.

    Shut down the Photon VM and copy its disk to THE tmp folder.

    # You will need to install Google Cloud SDK on host machine to upload the image and play with GCE.
    
    cp Virtual\ Machines.localized/photon.vmwarevm/Virtual\ Disk.vmdk /tmp/disk.vmdk
    cd /tmp
    # GCE needs disk to be named as disk.raw with raw format.
    qemu-img convert -f vmdk -O raw disk.vmdk disk.raw
    
    # ONLY GNU tar will work to create acceptable tar.gz file for GCE. MAC's default tar is BSDTar which will not work. 
    # On Mac OS X ensure that you have gtar "GNU Tar" installed. exmaple: gtar -Szcf photon.tar.gz disk.raw 
    
    gtar -Szcf photon.tar.gz disk.raw 
    
    # Upload
    gsutil cp photon.tar.gz gs://photon-bucket
    
    # Create image
    gcloud compute --project "<project name>" images create "photon-beta-vYYYYMMDD" --description "Photon Beta" --source-uri https://storage.googleapis.com/photon-bucket/photon032315.tar.gz
    
    # Create instance on GCE of photon image
    gcloud compute --project "photon" instances create "photon" --zone "us-central1-f" --machine-type "n1-standard-1" --network "default" --maintenance-policy "MIGRATE" --scopes "https://www.googleapis.com/auth/devstorage.read_only" "https://www.googleapis.com/auth/logging.write" --image "https://www.googleapis.com/compute/v1/projects/photon/global/images/photon" --boot-disk-type "pd-standard" --boot-disk-device-name "photon"
    
    

10.2 - Installing Photon OS on Google Compute Engine

After you download the Photon OS image for GCE, log into GCE and install Photon OS.

Perform the following steps:

  1. Create a New Bucket

    Create a new bucket to store your Photon OS image for GCE.

    gce1

  2. Upload the Photon OS Image

    While viewing the bucket that created, click the Upload files button, navigate to your Photon OS image and click the Choose button.

    When the upload finishes, you can see the Photon OS compressed image in the file list for the bucket that you created.

    gce2

  3. Create a New Image

    To create a new image, click on Images in the Compute category in the left panel and then click on the New Image button.

    Enter a name for the image in the Name field and change the Source to Cloud Storage file using the pull-down menu. Then, in the Cloud Storage file field, enter the bucket name and filename as the path to the Photon OS image for GCE. In this example, where the bucket was named photon_storage, the path is as follows:

     `photon_storage/photon-gce-2.0-tar.gz`
    

    The new image form autopopulates the gs:// file path prefix.*

    Click the Create button to create your image. You must be able to see the Images catalog and your Photon OS image at the top of the list.

  4. Create a New Instance

    To create an instance, check the box next to the Photon OS image and click the Create Instance button.

    On the Create a new instance form, provide a name for this instance, confirm the zone into which this instance is to be deployed and, before clicking Create, check the Allow HTTP traffic and Allow HTTPS traffic options.

    Note: The firewall rules in this example are optional. You can configure the ports according to your requirements.

    gce4

    When the instance is created you will be returned to your list of VM instances. If you click on the instance, the status page for the instance will allow you to SSH into your Photon OS environment using the SSH button at the top of the panel.

    At this point, your instance is running and you are ready to start the Docker engine and run a container workload. For more information, see Deploying a Containerized Application in Photon OS.

11 - Running Photon OS on Raspberry Pi

You can use Photon OS as a virtual machine on Raspberry Pi (RPi). You can download Photon OS and install the Photon OS distribution on vSphere.

11.1 - Prerequisites for Running Photon OS on Raspberry Pi

Before you use Photon OS within RPi, perform the following prerequisite tasks:

  1. Verify that you have the following resources:

    ResourceDescription
    Raspberry Pi 3Raspberry Pi 3 Model B or Model B+ board. This will serve as the target of the installation.
    Raspberry Pi 4Raspberry Pi 4 Model B or Model B+ board. This will serve as the target of the installation.
    Host computer

    A computer equipped with the following:

    1. An SD card reader.

    2. Software utilities to flash an image onto an SD-card (details and instructions provided below).

    Distribution FilePhoton OS RPi image downloaded from URL

    Note: Photon OS RPi image is available only from Photon 3.0 onwards.

    1. Download Photon OS.

      To install Photon OS on a Raspberry Pi, you must download the Photon OS RPi image, which is distributed as a compressed raw disk image with the file extension .raw.xz.

      Note: You cannot use the Photon ISO to install on RPi.

      Go to the following URL and download the latest release of Photon OS image for RPi: https://packages.vmware.com/photon/4.0/GA/rpi/rpi.tar.xz.

      For instructions, see Downloading Photon OS.

11.2 - Installing Photon OS on Raspberry Pi

You can get Photon OS up and running on an RPi board, by flashing the Photon RPi image onto the board’s SD card.

Flash Photon OS on Raspberry Pi

After you have downloaded the Photon RPi image with the file extension *.raw.xz, decompress the file to *.raw and then you can choose one of the methods below to flash it onto the RPi SD card.

  1. Flash Photon to RPi using Etcher
  2. Flash Photon to RPi using Linux CLI

Flash Photon to RPi using Etcher

  1. Install Etcher https://etcher.io/, which is a utility to flash SD cards attached to your host computer.
  2. Plug the RPi SD card into your host computer’s SD card reader.
  3. Perform the following steps on the Etcher GUI: Select image -> Select drive -> Flash, by selecting the Photon OS RPi as image and the RPi SD card as drive.

Flash Photon to RPi using Linux CLI

  1. If you have Linux running on your host computer, install the xz package, which provides the xz compression utility and related tools, from your distribution package manager.

  2. Plug the RPi’s SD card into your host computer’s SD card reader.

  3. Identify the device file under /dev that refers to the RPi SD card. For example, /dev/sdc. This file path is used to flash the Photon image onto the RPi in the next step.

    Note: Make sure that you are flashing to the device file that refers to your RPi3 SD card. Running the below command with an incorrect device file will overwrite that device without warning and might result in a corrupted disk. The device file ‘/dev/sdc` is an example and might not be the device file in your case.

  4. Run the following command to flash Photon onto the RPi SD card:

    xzcat <photon-rpi4-image.raw.xz> | sudo dd of=/dev/sdc bs=4M conv=fsync

Boot Photon OS on Raspberry Pi

After you flash Photon OS successfully onto the RPi SD card, eject the card from your host computer and plug it back into the RPi board.

When you power on Raspberry Pi , it boots with Photon OS.

After the splash screen, Photon OS prompts you to log in.

Update login credentials

The Photon OS RPi image is configured with a default password. However, all Photon OS instances that are created using this image will require an immediate password change upon login. The default account credentials are:

  • Username: root
  • Password: changeme

After you provide these credentials, Photon OS prompts you to create a new password and type it a second time to verify it. Photon OS does not allow common dictionary words for the root password. When you are logged in, you will see the shell prompt.

You can now run tdnf list to view all the ARM packages that you can install on Photon OS.

11.3 - Enabling Raspberry Pi Interfaces using Device Tree

Photon OS RPI images from Photon 4.0 has Device Tree Overlay support. And these images have compiled Overlays to enable/disable Rpi Interface. Perform the following:

SPI Interface: Execute following commands to enable SPI Interface:

mkdir /sys/kernel/config/device-tree/overlays/

cat /boot/efi/overlays/rpi-enable-spi0.dtbo > /sys/kernel/config/device-tree/overlays/spi/dtbo

Audio Interface: Execute following commands to enable Audio Interface:

mkdir  /sys/kernel/config/device-tree/overlays/audio

cat /boot/efi/overlays/rpi-enable-audio.dtbo >  /sys/kernel/config/device-tree/overlays/audio/dtbo

Note: Ensure that the linux-drivers-sound rpm is installed.

I2C Interface: Execute following command to enable I2C Interface:

modprobe i2c-dev

#Customizing Device Tree Overlay

Photon OS also provides Device Tree Compilers (i.e. dtc), to compile Customised Device Tree Overlays. Execute following command to install dtc on Photon OS:

tdnf install dtc

Execute following command to compile the overlay:

dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts

For more information about format of Device Tree Overlay, see https://www.kernel.org/doc/Documentation/devicetree/overlay-notes.txt

12 - Deploying a Containerized Application in Photon OS

Now that you have your container runtime environment up and running, you can easily deploy a containerized application. For this example, you will deploy the popular open source Web Server Nginx. The Nginx application has a customized VMware package that is published as a dockerfile and can be downloaded, directly, through the Docker module from the Docker Hub.

  1. Run Docker

    To run Docker from the command prompt, enter the following command, which initializes the docker engine:

     systemctl start docker
    

    To ensure Docker daemon service runs on every subsequent VM reboot, enter the following command:

     systemctl enable docker
    
  2. Run the Nginx Web Server

    Now the Docker daemon service is running, it is a simple task to “pull” and start the Nginx Web Server container from Docker Hub. To do this, type the following command:

     docker run -d -p 80:80 vmwarecna/nginx
    

    This pulls the Nginx Web Server files and appropriate dependent container filesystem layers required for this containerized application to run.

    Docker run

    After the docker run process completes, you return to the command prompt. You now have a fully active website up and running in a container!

  3. Test the Web Server

    To test that your Web Server is active, run the ifconfig command to get the IP address of the Photon OS Virtual Machine.

    IP address

    The output displays a list of adapters that are connected to the virtual machine. Typically, the web server daemon will be bound on eth0.

    Start a browser on your host machine and enter the IP address of your Photon OS Virtual Machine. You should see a screen similar to the following example as confirmation that your web server is active.

    Docker confirmation

    You can now run any other containerized application from Docker Hub or your own containerized application within Photon OS.

13 - Compatible Cloud Images

The Vmware Photon Packages website contains the following cloud-ready images of Photon OS:

  1. GCE - Google Compute Engine

  2. AMI - Amazon Machine Image

  3. OVA

Because the cloud-ready images of Photon OS are built to be compatible with their corresponding cloud platform or format, you typically do not need to build a cloud image, you can just go to the VMware Packages repo and download the image for the platform that you are working on.

If, however, you want to build your own cloud image, perhaps because you seek to customize the code, see the next section on how to build cloud images.

How to build cloud images

sudo make cloud-image IMG_NAME=image-name

image-name: gce/ami/azure/ova

The output of the build process produces the following file formats:

GCE - A tar file consisting of disk.raw as the raw disk file

AMI - A raw disk file

OVA - An ova file (vmdk + ovf)

If you want, you can build all the cloud images by running the following command:

sudo make cloud-image-all 

How to create running instances in the cloud

The following sections contain some high-level instructions on how to create instances of Photon OS in the Google Compute Engine (GCE) and Amazon Elastic Cloud Compute (EC2). For more information, see the Amazon or Google cloud documentation.

GCE

The tar file can be uploaded to Google’s cloud storage and an instance can be created after creating an image from the tar file. You will need the Google Cloud SDK on your host machine to upload the image and create instances.

####Install Google cloud SDK on host machine

curl https://sdk.cloud.google.com | bash

####Upload the tar file

gsutil cp photon-gce.tar.gz gs://bucket-name

####Create image

gcloud compute --project project-id images create image-name --description description --source-uri https://storage.googleapis.com/bucket-name/photon-gce.tar.gz

####Create instance of GCE

gcloud compute --project project-id instances create instance-name --zone "us-central1-f" --machine-type "n1-standard-1" other-options

(You can also create instances from the Google developer console.)

For more information, see Running a Photon OS Machine on GCE.

AWS EC2

Install the AWS CLI and EC2 CLI tools.

####Bundle the image

ec2-bundle-image -c cert.pem -k private-key.pem -u $AWS_USER_ID --arch x86_64 --image photon-ami.raw --destination directory-name

####Upload the bundle

ec2-upload-bundle --manifest directory-name/photon-ami.raw.manifest.xml --bucket bucket-name --access-key $AWS_ACCESS_KEY --secret-key $AWS_SECRET_KEY

####Register the AMI

ec2-register bucket-name/photon-ami.raw.manifest.xml --name name --architecture x86_64 --virtualization-type hvm

You can now launch instances using the AWS console.

For more information, see Customizing a Photon OS Machine on EC2.

###OVA

The OVA image uses an optimized version of the 4.4.8 Linux kernel. Two ova files are generated from the build: photon-ova.ova, which is the full version of Photon OS, and photon-custom.ova, which is the minimal version of Photon OS. The password for photon-ova.ova should be changed using guest customization options when you upload it to VMware vCenter. Photon-custom.ova comes with the default password set to changeme; you must change it the first time you log in.

OVA Prerequisites

VDDK 6.0

To utilize the VDDK libraries the following procedure may be used, this extracts the libraries and temporarily exports them to the LD_LIBRARY_PATH for the current session. (tested on Ubuntu 1404 & 1604) If you wish to make this permanent and system-wide then you may want to create a config file in /etc/ld.so.conf.d/.

tar -zxf VMware-vix-disklib-6.0.2-3566099.x86_64.tar.gz
cp -r vmware-vix-disklib-distrib/include/* /usr/include/
mkdir /usr/lib/vmware
cp -a ~/vmware-vix-disklib-distrib/lib64/* /usr/lib/vmware/
rm /usr/lib/vmware/libstdc++.so.6
export LD_LIBRARY_PATH=/usr/lib/vmware

OVFTOOL

OVF Tool should be downloaded and installed on the host.

sh VMware-ovftool-4.1.0-2459827-lin.x86_64.bundle --eulas-agreed --required