Photon OS Documentation

• 1: Quick Start Links
• 2: What is New in Photon OS 5
• 3: Overview
• 3.1: Introduction to Photon OS
• 3.2: Flavours
• 4: Installation Guide
• 4.1: Downloading Photon OS
• 4.2: Upgrading Photon OS 4.0 system to Photon OS 5.0
• 4.3: Building Images
• 4.3.1: Folder Layout
• 4.3.2: Build Prerequisites
• 4.3.3: Build an ISO from the Source Code for Photon OS
• 4.3.3.1: Building the ISO
• 4.3.4: Build Other Images for Photon OS
• 4.3.4.1: Building Cloud Images
• 4.3.4.2: Building OVA image
• 4.3.5: Use the Cached Toolchain and RPMS
• 4.3.6: Use Cached Sources
• 4.3.7: View Build Logs
• 4.3.8: Build a Custom ISO from the Source Code of Photon OS Installer
• 4.4: Building Package or Kernel Modules Using a Script
• 4.4.1: Hello World Kernel Module
• 4.4.2: Hello World Binary
• 4.4.3: Manage a Dependent package
• 4.4.4: Include a patch file
• 4.4.5: Refer an External Source
• 4.5: Running Photon OS on vSphere
• 4.5.1: Prerequisites for Running Photon OS on vSphere
• 4.5.2: Importing the OVA for Photon OS
• 4.5.3: Installing the ISO Image for Photon OS
• 4.6: Running Photon OS on Fusion
• 4.6.1: Prerequisites for Running Photon OS on Fusion
• 4.6.2: Importing the OVA for Photon OS
• 4.6.3: Installing the ISO Image for Photon OS
• 4.7: Running Photon OS on Workstation
• 4.7.1: Prerequisites for Running Photon OS on Workstation
• 4.7.2: Importing the OVA for Photon OS
• 4.7.3: Installing the ISO Image for Photon OS
• 4.8: Running Photon OS on Amazon Elastic Cloud Compute
• 4.8.1: Prerequisites for Running Photon OS on AWS EC2
• 4.8.2: Set Up Photon OS on EC2
• 4.8.3: Deploy a Containerized Application in Photon OS
• 4.8.4: Launch the Web Server with Cloud-Init
• 4.8.5: Terminate the AMI Instance
• 4.9: Running Photon OS on Microsoft Azure
• 4.9.1: Prerequisites for Running Photon OS on Azure
• 4.9.2: Set Up Azure Storage and Uploading the VHD
• 4.9.3: Remove Photon OS From Azure
• 4.10: Running Photon OS on Google Compute Engine
• 4.10.1: Prerequisites for Running Photon OS on GCE
• 4.10.2: Installing Photon OS on Google Compute Engine
• 4.11: Running Photon OS on Raspberry Pi
• 4.11.1: Prerequisites for Running Photon OS on Raspberry Pi
• 4.11.2: Installing Photon OS on Raspberry Pi
• 4.11.3: Enabling Raspberry Pi Interfaces using Device Tree
• 4.12: Deploying a Containerized Application in Photon OS
• 4.13: Compatible Cloud Images
• 5: Administration Guide
• 5.1: Photon OS Packages
• 5.1.1: Examining the Packages in the SPECS Directory on Github
• 5.1.2: Looking at the Differences Between the Minimal and the Full Version
• 5.1.3: The Root Account and the 'sudo' and 'su' Commands
• 5.1.4: Examining Signed Packages
• 5.1.5: Photon OS Package Repositories
• 5.1.6: Building a Package from a Source RPM
• 5.1.7: Compiling C++ Code on the Minimal Version of Photon OS
• 5.2: Package Management in Photon OS with 'tdnf'
• 5.2.1: Introduction to 'tdnf'
• 5.2.2: Configuration Files and Repositories
• 5.2.3: Adding a New Repository
• 5.2.4: Mount the Photon ISO Image for the Photon-ISO Repository
• 5.2.5: Adding the Dev Repository to Get New Packages from the GitHub Dev Branch
• 5.2.6: tdnf-automatic
• 5.2.7: Install Packages from CLI
• 5.2.8: SSL Options
• 5.2.9: Standard Syntax for tdnf Commands
• 5.2.9.1: tdnf Commands
• 5.2.9.2: tdnf Command Options
• 5.2.10: Configuration Options
• 5.3: Managing Services with 'systemd'
• 5.3.1: Viewing Services
• 5.3.2: Controlling Services
• 5.3.3: Creating a Startup Service
• 5.3.4: Disabling the Photon OS httpd.service
• 5.3.5: Installing Sendmail
• 5.3.6: Auditing System Events with auditd
• 5.3.7: Analyzing systemd Logs with journalctl
• 5.3.8: Migrating Scripts to systemd
• 5.4: Configure Wireless Networking
• 5.5: Managing the Network Configuration
• 5.5.1: Commands to Manage Network Service
• 5.5.2: Using the Network Configuration Manager
• 5.5.3: Use 'ip' and 'ss' Commands
• 5.5.4: Configuring Network Interfaces
• 5.5.5: Setting a Static IP Address
• 5.5.6: Turning Off DHCP
• 5.5.7: Adding a DNS Server
• 5.5.8: Setting Up Networking for Multiple NICs
• 5.5.8.1: Combining DHCP and Static IP Addresses with IPv4 and IPv6
• 5.5.9: Clearing the Machine ID of a Cloned Instance for DHCP
• 5.5.10: Using Predictable Network Interface Names
• 5.5.11: Inspecting the Status of Network Links with 'networkctl'
• 5.5.12: Turning On Network Debugging
• 5.5.13: Installing packages for 'tcpdump' and 'netcat'
• 5.5.14: Mounting a Network File System
• 5.5.15: Configuring a Secondary Network Interface using Cloud-Network
• 5.5.16: Using Network Event Broker
• 5.5.17: Configuring a Network Using Network Configuration Manager
• 5.6: Prioritize eth0 Route Over WLAN
• 5.7: Configuring Photon Real-Time Operating System for Real-Time Applications
• 5.8: Containers
• 5.8.1: Docker Containers
• 5.8.2: Docker Rootless Support
• 5.8.3: Kubernetes
• 5.8.4: Support for distributed builds using Kubernetes
• 5.9: Changing the Locale
• 5.10: Cloud-Init on Photon OS
• 5.10.1: Cloud-Init Overview
• 5.10.2: Deploy Photon OS With 'cloud-init'
• 5.10.3: Customizing Guest OS using Cloud-Init
• 5.10.4: Creating a Stand-Alone Photon Machine With cloud-init
• 5.10.5: Customizing a Photon OS Machine on EC2
• 5.10.6: Running a Photon OS Machine on GCE
• 5.11: Security Policy
• 5.11.1: Default Firewall Settings
• 5.11.2: Default Permissions and umask
• 5.11.3: Disabling TLS 1.0 to Improve Transport Layer Security
• 5.12: Support for zstd Compression
• 5.13: Photon RPM OSTree: a simple guide
• 5.13.1: Introduction
• 5.13.2: Installing a host against default server repository
• 5.13.3: Concepts in Action
• 5.13.4: Querying for Commit File and Package Metadata
• 5.13.5: Host Updating Operations
• 5.13.6: Creating a Server
• 5.13.7: Installing a Photon RPM-OStree host against a custom server repository
• 5.13.8: Automatic Updates
• 5.13.9: File Oriented Server Operations
• 5.13.10: Package Oriented Server Operations
• 5.13.11: Remotes
• 5.13.12: Running container applications between bootable images
• 5.13.13: Install or rebase to Photon OS
• 5.14: Support for SELinux
• 5.15: pmd-nextgen Overview
• 5.15.1: Features
• 5.15.2: Installing photon-mgmtd
• 5.15.3: Configuration
• 5.15.4: photon-mgmtd API
• 5.15.4.1: Service Management
• 5.15.4.2: System Management
• 5.15.4.3: Network Management
• 5.15.4.4: User, Group, and Host Management
• 5.15.4.5: Package Management
• 5.15.4.6: Firewall nftables Management
• 5.15.4.7: Process Details and Configuration Management
• 5.15.5: Writing a Plugin
• 5.16: Photon OS Installer Overview
• 6: User Guide
• 6.1: Setting Up Network PXE Boot
• 6.2: Kickstart Support in Photon OS
• 6.3: Packer Examples for Photon OS
• 6.4: Kubernetes on Photon OS
• 6.4.1: Prerequisites
• 6.4.2: Running Kubernetes on Photon OS
• 6.4.2.1: System Information
• 6.4.2.2: Prepare the Hosts
• 6.4.2.3: Configure Kubernetes Services on the Master
• 6.4.2.4: Configure the Kubernetes services on Node
• 6.4.3: Kubernetes-Kubeadm Cluster on Photon OS
• 6.4.3.1: Configuring a Master Node
• 6.4.3.2: Configure a Worker Node
• 6.4.3.3: Run a Hello-World Application
• 6.5: Photon NFS Utilities for Mounting Remote File Systems
• 6.6: Seamless Update with A/B Partition System
• 6.6.1: Configuring A/B Partition System
• 6.6.2: Executing Update and Rollback Using A/B Partition System
• 6.6.3: Commands for Operations
• 7: Command-Line Reference
• 7.1: Command-line Interfaces
• 7.1.1: Photon Network Config Manager Command-line Interface (nmctl)
• 7.1.1.1: Configuring WireGuard using Network Configuration Manager
• 7.1.1.2: Configure SR-IOV using Network Configuration Manager
• 7.1.2: Photon Real-Time Operating System Command-line Interface
• 8: Troubleshooting Guide
• 8.1: Introduction
• 8.1.1: Systemd and TDNF
• 8.1.2: The Root Account and the `sudo` and `su` Commands
• 8.1.3: Checking the Version and Build Number
• 8.1.4: General Best Practices
• 8.1.5: Photon OS Logs
• 8.1.6: Troubleshooting Progression
• 8.2: Solutions to Common Problems
• 8.2.1: Boot in Emergency Mode
• 8.2.2: Resetting a Lost Root Password
• 8.2.3: Fixing Permissions on Network Config Files
• 8.2.4: Permitting Root Login with SSH
• 8.2.5: Fixing Sendmail
• 8.3: Photon OS General Troubleshooting
• 8.3.1: Photon Code
• 8.3.2: Package Management
• 8.3.3: Network Configuration
• 8.3.4: Cloud-init
• 8.3.5: Open-vm-tools/Vmtoolsd
• 8.4: Troubleshooting Tools
• 8.4.1: Common Tools
• 8.4.2: Troubleshooting Tools Installed by Default
• 8.4.3: Installing Tools from Repositories
• 8.4.4: Linux Troubleshooting Tools
• 8.5: Systemd
• 8.5.1: Enabling 'systemd' Debug Shell During Boot
• 8.5.2: Troubleshooting Services With 'systemctl'
• 8.5.3: Analyzing System Logs with 'journalctl'
• 8.5.4: Inspecting Services with 'systemd-analyze'
• 8.5.5: Inspecting Services with 'systemd-analyze'
• 8.6: Network Troubleshooting
• 8.6.1: Managing the Network Configuration
• 8.6.2: Inspecting IP Addresses
• 8.6.3: Inspecting the Status of Network Links with 'networkctl'
• 8.6.4: Network Debugging
• 8.6.5: Checking Firewall Rules
• 8.6.6: Inspect Network Settings with 'netmgr'
• 8.7: File System Troubleshooting
• 8.7.1: Checking Disk Space
• 8.7.2: Adding a Disk and Partitioning It
• 8.7.3: Expanding Disk Partition
• 8.7.4: List Disk Partitions with 'fdisk'
• 8.7.5: File System Consistency Check Tool
• 8.7.6: Fixing File System Errors When fsck Fails
• 8.8: Troubleshooting Packages
• 8.9: Kernel Problems and Boot and Login Errors
• 8.9.1: Kernel Overview
• 8.9.2: Boot Process Overview
• 8.9.3: Blank Screen on Reboot
• 8.9.4: Investigating Unexpected Behavior
• 8.9.5: Investigating the Guest Kernel
• 8.9.6: Kernel Log Replication with VProbes
• 8.9.7: Linux Kernel
• 8.10: Performance Issues
• 8.10.1: General Performance Guidelines
• 8.10.2: Throughput Performance
• 8.11: Photon 4.0 to Photon 5.0 Migration and PostgreSQL Upgrade
• 8.12: Photon OS Installation Issue
• 9: Security Advisories

1 - Quick Start Links

If you want to start using Photon OS straight away, see the following topics:

• Overview
• Downloading Photon OS
• Build an ISO from the source code for Photon OS

2 - What is New in Photon OS 5

Photon OS 5.0 provides enhancements in Network Configuration Manager, PMD-nextgen, Container Runtime Security, Linux Real-Time Kernel, and TDNF Features. The release introduces the Photon OS Container Builder tool. This release of Photon OS also supports XFS and BTRFS filesystems, Control Group V2, ARM64 on Linux-esx kernel, PostgreSQL. It contains installer improvements and critical updates to the OSS packages including Linux kernel version updates. This topic summarizes what’s new and different in Photon OS 5.0.

New Features

• Enhancements in Network Configuration Manager: You can now use Network Configuration Manager to perform the following tasks:

  • Configure multiple routes and addresses section
  • Configure WireGuard
  • Configure SR-IOV
  • Create NetDev, VLAN, VXLAN, Bridge, Bond, VETH (Virtual Ethernet), MacVLAN/MacVTap, IPvlan/IPvtap, tunnels (IPIP, SIT, GRE, VTI)
  • Create, configure, and remove virtual network devices
  • Generate more flexible netplan like network configuration from a YAML file

  You can run query or configure the following parameters of network devices:

  • Alias, Description, MTUBytes, WakeOnLan, WakeOnLanPassword, Port, BitsPerSecond, Duplex and Advertise
  • Offload parameters and other features
  • MACAddressPolicy or MACAddress
  • NamePolicy or Name
  • AlternativeNamesPolicy or AlternativeName
  • Pending packets receive a buffer
  • Queue size
  • Flow control
  • GSO
  • Channels
  • Coalesce
  • Coalesced frames
  • Coalesce packet rate

• PMD-Nextgen Enhancement: The capabilities to configure the following options are added to pmd-nextgen:

  • Configure system hostname
  • Configure network sriov
  • Configure Tun
  • Configure Tap
  • Configure TLS

• Network-event-broker: Network-event-broker now supports emitting network data in JSON format.

• Photon OS Container Builder: The cntrctl tool in Photon OS 5.0 allows you to build a lightweight Photon OS container.

• Kernel-Version Update: The following Kernel flavors are updated to kernel version 6.1.10 in Photon OS:

  • Linux
  • Linux-esx
  • Linux-secure
  • Linux-rt

• Support for New Filesystems: Support is added for the following filesystems in Photon OS:

  • XFS: With the support of the XFS filesystem, you can implement an environment that requires high performance, and scalability for data-intensive tasks.
  • BTRFS: You can use the BTRFS filesystem for high performance, better reliability, and efficient data storage capabilities.

• Support for Control Group V2: cgroup v2 is now available in Photon OS. With cgroup v2, you get improved resource management capabilities, a unified hierarchy scheme, and a safer sub-tree delegation to containers. Features like Pressure Stall Information and rootless containers in cgroup v2 ensure better management and security capabilities of the control groups.

• Support for Kernel Live Patching: With Kernel Live Patching, an administrator can patch a running kernel without rebooting.

• Enhanced Container Runtime Security: To improve the runtime security of the containers, the following enhancements are added to Photon OS:

  • Support for SELinux policy: You can now enable and configure the SELinux policy to manage access to files, directories, and other system resources. This drastically reduces the risk of a security breach.
  • Support for rootless containers: Photon OS supports rootless containers. An unprivileged user can now create and manage containers. Since unprivileged users do not have root privileges on the host machine, it prevents any security threat to the host machine.

• Improved Linux Real-Time Kernel: The linux-rt kernel flavor comes with improvements such as low-latency optimizations, stability enhancements, and debugging enhancements. Linux-rt now also supports the Intel Sapphire Rapids CPUs including the Telco-specific 5G ISA.

• Support for ARM64: Support for ARM64 is now available for the linux-esx kernel in Photon OS.

• PostgreSQL versions: The following PostgreSQL versions are supported on Photon OS:

  • PostgreSQL 13
  • PostgreSQL 14
  • PostgreSQL 15

• TDNF Feature Enhancements: The metalink functionality in tdnf is now available as a plugin. In tdnf, support is added for the following:

  • history (list, rollback, undo and redo)
  • mark command
  • checking the available cache size of a download
  • multiple base URLs
  • --skip-broken option
  • --alldeps option when downloading
  • --testonly option
  • --nodeps option for --downloadonly
  • --source and --builddeps options
  • dnf_check_update_compat config file option
  • support for tsflags=nodocs
  • --repofromdir option
  • --arch option to repoquery
  • Configuration tool: Set of commands to change tdnf’s configuration files and repository files.

• OVA Updates: UEFI OVA is built with hardware version 15.

Installer and Build System Updates

• Support Pre-install script in photon installer
• A tool is now available to generate a custom initial RAM disk (initrd)
• A tool is now available to generate a custom installer ISO
• A tool is now available to generate a custom RPM-OSTree ISO
• Support is added for the following features in Kickstart:
  • sizepercent: specifies the size of the partition in percent of the total disk space.
  • repos: Specifies the RPM repositories to install the RPMs.
• Support for A/B Partition System: Photon OS 5.0 supports seamless updates and rollback with the A/B storage partition system.
• Kickstart Network Configuration: Improved flexibility for network configuration that allows multiple interfaces and facilitates better handling of the VLAN interfaces.

Package Updates:

The following OS packages are updated:

• Linux kernel 6.1.10
• Gcc : 12.2
• Glibc 2.36
• Systemd 253
• Python3 3.11
• Openjdk : 11 and 17
• Openssl : 3.0.8
• Cloud-init: 23.1.1
• Rubygem: 3.1.2
• Perl: 5.36
• Kubernetes 1.26.1
• Go 1.20.2

Notes

The following OS packages are removed in this release.

• Photon Management Daemon (PMD)
• lightwave
• likewise-open
• openjdk8
• fcgi
• libnss-ato
• tiptop
• ndsend
• ulogd
• lightstep-tracer-cpp
• json_spirit
• cgroup-utils
• c-rest-engine
• dcerpc
• gssapi-unix
• python3-PyPAM
• python3-backports_abc
• sshfs

3 - Overview

Overview of Photon OS provides an introduction to Photon OS, its versions, and distinguishing features.

Product version: 5.0

This documentation applies to all 5.0.x releases.

Intended Audiences

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

3.1 - Introduction to Photon OS

Photon OS, is an open-source minimalist Linux operating system from VMware that is optimized for cloud computing platforms, VMware vSphere deployments, and applications native to the cloud.

Photon OS is a Linux container host optimized for vSphere and cloud-computing platforms such as Amazon Elastic Compute and Google Compute Engine. As a lightweight and extensible operating system, Photon OS works with the most common container formats, including Docker, Rocket, and Garden. Photon OS includes a yum-compatible, package-based lifecycle management system called tdnf.

When used with development tools and environments such as VMware Fusion, VMware Workstation, and production runtime environments (vSphere), Photon OS lets you seamlessly migrate container-based applications from development to production. With a small footprint and fast boot and run times, Photon OS is optimized for cloud computing and cloud applications.

3.2 - Flavours

Photon OS consists of a minimal version, a full version, RPM OSTree, and Photon Real-Time Operating System.

• The minimal version of Photon OS is lightweight container host runtime environment that is suited to managing and hosting containers. The minimal version contains just enough packaging and functionality to manage and modify containers while remaining a fast runtime environment. The minimal version is ready to work with appliances.

• The Developer version of Photon OS includes additional packages to help you customize the system and create containerized applications. For running containers, the developer version is excessive. The developer version helps you create, develop, test, and package an application that runs a container.

• OSTree is a tool to manage bootable, immutable, versioned filesystem trees. Unlike traditional package managers like rpm or dpkg that know how to install, uninstall, configure packages, OSTree has no knowledge of the relationship between files. But when you add rpm capabilities on top of OSTree, it becomes RPM-OSTree, meaning a filetree replication system that is also package-aware.

• Photon OS features a kernel flavor called linux-rt to support low-latency real time applications. linux-rt is based on the Linux kernel PREEMPT_RT patchset that turns Linux into a hard real time operating system. In addition to the real time kernel itself, Photon OS 5.0 supports several userspace packages such as tuned, tuna, stalld, and others, that are useful to configure the operating system for real time workloads. The linux-rt kernel and the associated userspace packages together are referred to as Photon Real Time (RT).
  In Photon OS 5.0, the linux-rt kernel flavor comes with the following improvements:

  • Low-latency Optimizations: Low-latency is achieved with the following feature enhancements:

    • Guest Timer Advancement feature in linux-rt mitigates the cost of timer virtualization on ESXi. This makes Photon RT on ESXi and bare-metal indistinguishable in terms of the cyclictest benchmark results.
    • Enhancements to tuned and trace-cmd packages to reduce OS jitter to real-time workloads.

  • Stability Enhancements: Enhanced stability is achieved with the following improvements:

    • stalld version is updated to 1.17.1, which brings in several improvements to the effectiveness and efficiency of stalld in resolving kernel thread starvation.
    • Updated stalld configuration file with more effective and field-proven defaults.

  • Debugging Enhancements:: Debugging enhancements are achieved with the following improvements:

    • To aid with latency tuning and debugging, osnoise and timerlat latency tracers are enabled in the linux-rt kernel.
    • Enabled Kernel’s hung-task detector in tuned real-time profile’s configuration.

  • Hardware Enablement: Support is added for Intel Sapphire Rapids CPUs, including its Telco-specific 5G ISA.

  • Driver Updates: Updated out-of-tree Intel network drivers to the following versions:

    • i40e – v2.22.18
    • iavf – v4.8.2
    • ice – v1.11.14

4 - Installation Guide

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

Product version: 5.0

This documentation applies to all 5.0.x releases.

Intended Audiences

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

4.1 - Downloading Photon OS

Detailed instructions for obtaining Photon OS 5.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:

Format	Description
ISO Image	Contains 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.
OVA	Pre-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 AMI	Pre-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 Image	Pre-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 VHD	Pre-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 Image	Pre-packaged and tested Raspberry Pi Image on ARM64 architecture.

4.2 - Upgrading Photon OS 4.0 system to Photon OS 5.0

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

The photon-upgrade package provides a seamless upgrade for Photon OS. To use the package, you need to perform the following steps:

1. Install the photon-upgrade package on the Photon OS 4.0 system.
2. Run the following script:

   /bin/photon-upgrade.sh
   

3. Follow the interactions with that script.

Please note that the script also supports a non-interactive invocation using the --assume-yes option. The --help option of the photon-upgrade.sh script provides online help.

The photon-upgrade.sh script updates packages to the latest available versions in Photon OS 5.0. Also, the upgrade retains your 4.0 customizations in your new Photon OS 5.0 system.

Note: If your 4.0 VM is a full install, then you will have a 5.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 4.0 VM that you want to upgrade, complete the following steps:

1. Back up all existing settings and data for the Photon 4.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 --upgrade-os
   

5. Answer y to reboot the VM. The upgrade script powers down the Photon OS 4.0 VM and powers it on as a Photon OS 5.0 VM.

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

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

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

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

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

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

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

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

3. Clone`the Photon project:

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

4. Make the cloud image for AMI.

   sudo make image IMG_NAME=ami

5. Make the cloud image for Azure.

   sudo make image IMG_NAME=azure

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

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

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

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

   
   `sudo make image IMG_NAME=ova`
   

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

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

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

4.3.7 - View Build Logs

You can view build logs at the following location:

$HOME/workspaces/photon/stage/LOGS

4.3.8 - Build a Custom ISO from the Source Code of Photon OS Installer

The custom-iso tool allows you to build images as per your requirements.

Overview
Prerequisite
Preparing for Custom Image Generation
Generating a Custom Image

Overview

You can use the custom-iso tool to create images such as a custom ISO, Initrd, and RPM-OSTree. To generate an image, you must provide the necessary inputs in the form of arguments. The custom-iso tool creates images based on the inputs you provide.

You can use the following functions to generate the required images:

• build-initrd generates a custom Initrd image

• build-initrd generates a custom ISO image.

• build-rpm-ostree-iso generates a custom RPM-OSTree ISO.

As an input to the tool, you must provide the list of all the necessary packages for the custom ISO in a JSON file. The tool only uses the minimal list of packages and their dependencies that you specify.

You can customize the following files and configurations:

• List of packages to install
• Kickstart file
• Boot command line
• Repo to download the packages
• Installer initrd package list
• Custom ostree tar archive

Note that when you use the Custom ISO builder to build the ISO and the Installer initrd, the ISO and initrd files are generated with the following naming conventions:

• ISO: photon-<photon-release-version>.iso

• Initrd: initrd.img

Prerequisite

To generate a custom ISO, ensure that you provide the following required parameters:

• List of custom packages in JSON format
• Photon Release Version
• Generating Function: For example, build-iso, build-initrd, and build-rpm-ostree-iso
• Path to OSTree tar archive (required only if function is set to build-rpm-ostree-iso)

Note: You must provide the additional repository if you want to include a package that the Photon OS official repository does not provide.

You can also provide the following optional parameters:

• Custom Kickstart file
• Additional repositories
• Boot command line parameters
• Custom Initrd package list file
• Artifact path

Preparing for Custom Image Generation

1. Install the following prerequisite packages:

   • python3-pip
   • git
   • tar
   • createrepo_c
   • binutils
   • dosfstools
   • cdrkit
   • docker

   i. To install the specified packages on Photon OS, use the following command:

   tdnf install -y python3-pip git tar createrepo_c binutils dosfstools cdrkit
   

2. Run following command to install photon-os-installer python library:

   pip3 install git+https://github.com/vmware/photon-os-installer.git
   

3. Enable the following services before you build the custom iso/initrd: docker

   i. To enable the docker service and log in to the docker account, use the following command:

   systemctl start docker.service;
   docker login # To avoid docker pull rate limit
   

4. Create the file containing the custom package list.

   The following list shows some of the sample custom package files:

   • Sample custom package file for an ISO: packages_minimal.json
   • Sample initrd package list file: packages_installer_initrd.json

   Package list json format-

   {
   "packages": <list-of-pkgs>,
   "packages_x86_64": <x86-specific-pkgs>,
   "packages_aarch64": <aarch64-specific-pkgs>
   }
   

For more details, refer to the following link: https://github.com/vmware/photon-os-installer/blob/master./ks_config.md#packages-optional-if-packagelist_file-set

Note: packages_x86_64 and packages_aarch64 are optional keys. The packages_minimal.json file is a sample file. You can create your own JSON file with the list of custom packages that you want, and provide the directory path for the file in the command to generate the iso/initrd.

Generating a Custom Image

You can use the respective commands to generate the custom images for the following use cases.

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json>

photon-iso-builder -v 5.0 -p /root/packages_custom.json

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> [-r <path/to/custom-repo-list>]

photon-iso-builder -v 5.0 -p /root/packages_custom.json -r local.repo -r local2.repo

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -k <path-to-kickstart>

photon-iso-builder -v 5.0 -p /root/packages_custom.json -k /root/custom_kickstart.json

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -f build-iso -k <path-to-kickstart> -b "ks=cdrom:/isolinux/<kickstart-file-base-name>"

photon-iso-builder -v 5.0 -p /root/packages_custom.json -k /root/custom_kickstart.json -b "ks=cdrom:/isolinux/custom_kickstart.json"

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -f build-iso -b <extra-boot-parameter>

photon-iso-builder -v 5.0 -p /root/packages_custom.json -b "ks=http://10.197.102.86:8000/sample_ks.cfg insecure_installation=1"

	tar -czf </path/to/>ostree-repo.tar.gz -C </path/to/repotree>/repo

	tar -zcf /root/ostree-repo.tar.gz -C /root/my-repo/repo .

photon-iso-builder -v <photon-release-version> -o <path/to/ostree-tar-archive> -f build-rpm-ostree-iso

photon-iso-builder -v 5.0 -o /root/ostree-repo.tar.gz -f build-rpm-ostree-iso

photon-iso-builder -v <photon-release-version> -p <path/to/custom-package-list-json> -a <custom-artifact-path>

photon-iso-builder -v 5.0 -p /root/packages_custom.json -a /root/custom/path

photon-iso-builder -v <photon-release-version> -c <path/to/custom-initrd-pkg-list-file> -f build-initrd

photon-iso-builder -v 5.0 -c /root/packages_custom_initrd.json -f build-initrd

Generating custom ISO through source code:

The following command demonstrate how to generate a custome ISO through the source code:

git clone https://github.com/vmware/photon-os-installer.git
cd photon-os-installer/photon_installer
./isoBuilder -v 5.0 -p packages_minimal.json

4.4 - Building Package or Kernel Modules Using a Script

You can use a script to build a single Photon OS package without the need to setup a complete Photon build workspace. You just need a .spec specification file and the source files. You can place the source files and the specification files in the same folder, or provide a URL for the source file location, and then 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
• Procedure

Prerequisites

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

• Ensure you have any Linux OS with a docker daemon running.
• Place the source and RPM .spec files in the same folder or provide a URL for the source files.

Procedure

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

./photon/tools/scripts/build_spec.sh <path-to-rpm_spec_file.spec> [$STAGEDIR]

You can specify the staging directory ($STAGEDIR) where you want to store the generated RPM files and build logs. If you do not specify a staging directory, the generated output files are stored in the directory that contains the spec file.

The following topics show examples to build packages based on various use cases.

4.4.1 - Hello World Kernel Module

This example shows how to build a package that provides a hello world kernel module. To build the package, you need to run the script with hello-world.spec as an argument, where hello-world.spec is the RPM specification file.

You can find the source file at the following location:

https://github.com/vmware/photon/tree/<BRANCH>/tools/examples/build_spec/kernel_module_example/hello-world.tar.gz	

To generate the output in the spec-file folder, run the following command:

./photon/tools/scripts/build_spec.sh ./photon/tools/examples/build_spec/kernel_module_example/hello-world.spec

The following are the contents of the hello-world.spec file:

%define linux_esx_ver 6.1.10

Summary:        Hello World Linux module
Name:           hello-world
Version:        1.0
Release:        1%{?dist}
License:        GPLv2
Group:          System Environment/Kernel
Vendor:         VMware, Inc.
Distribution:   Photon
Source0:        hello-world.tar.gz
BuildRequires:  linux-esx-devel = %{linux_esx_ver}
BuildRequires:  kmod
Requires:       linux-esx = %{linux_esx_ver}

%description
Example of building linux module for Photon OS

%prep
%autosetup -n hello-world

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

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

%ldconfig_scriptlets

%post
/sbin/depmod -a

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

Build Logs

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

0. Build Script Version: 1.1
1. Create sandbox
        Use local build template image OK
2. Prepare build environment
        Create source folder OK
        Copy sources from ./photon/tools/examples/build_spec/kernel_module_example OK
        install createrepo OK
        createrepo  OK
        Create local repo in sandbox OK
        makecache OK
3. Build Binary and Source Package
        Run rpmbuild OK 
        Delete SOURCES OK
4. Destroy sandbox 
        Stop container OK
        Remove container OK
Build completed. RPMS are in './photon/tools/examples/build_spec/kernel_module_example/stage' folder

Verification

You can verify the generated output with the following commands:

• Command to install the RPM:

rpm -ivh ./photon/tools/examples/build_spec/kernel_module_example/stage/RPMS/x86_64/hello-world-1.0-1.ph5.x86_64.rpm

• Command to install the kernel module:

modprobe hello-world

• Command to verify the installed kernel module:

dmesg | grep "Hello World"

4.4.2 - Hello World Binary

This example shows how to build a package that provides a hello world binary. To build the package, you need to run the script with hello-world-user1.spec as an argument, where hello-world-user1.spec is the RPM specification file.

You can find the source file at the following location:

https://github.com/vmware/photon/tree/<BRANCH>/tools/examples/build_spec/user_package_example/hello-world-user1.tar.gz

To generate the output in a staging directory, run the following command:

./photon/tools/scripts/build_spec.sh ./photon/tools/examples/build_spec/user_package_example/hello-world-user1.spec $STAGEDIR

The following are the contents of the hello-world-user1.spec file:

% Summary:      Hello World User Package
Name:           hello-world-user1
Version:        1.0
Release:        1%{?dist}
License:        GPLv2
Group:          System Environment/Kernel
Vendor:         VMware, Inc.
Distribution:   Photon
Source0:        hello-world-user1.tar.gz

%description
Example of building User Package for Photon OS

%prep
%autosetup -n hello-world-user1

%build
make %{?_smp_mflags}

%install
make %{?_smp_mflags} install DESTDIR=%{buildroot}

%ldconfig_scriptlets

%files
%defattr(-,root,root)
/usr/bin/*

Build Logs

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

0. Build Script Version: 1.1
1. Create sandbox
        Use local build template image OK
2. Prepare build environment
        Create source folder OK
        Copy sources from ./photon/tools/examples/build_spec/user_package_example OK
        install createrepo OK
        createrepo  OK
        Create local repo in sandbox OK
        makecache OK
        Install build requirements OK
3. Build Binary and Source Package
        Run rpmbuild OK
        Delete SOURCES OK
4. Destroy sandbox
        Stop container OK
        Remove container OK
Build completed. RPMS are in '$STAGEDIR' folder

Verification

You can verify the generated output with the following commands:

• Command to install the RPM:

rpm -ivh $STAGEDIR/RPMS/x86_64/hello-world-user-1.0-1.ph5.x86_64.rpm

• Command to verify the installed user package (execute the installed binary of the user package):

root@photon-aab77099dca0root [ ~ ]# /usr/bin/hello-world-user
     Hello World

4.4.3 - Manage a Dependent package

This example shows how to build a dependent package. To build the package, you need to run the script with hello-world-user.spec as an argument, where hello-world-user.spec depends on the RPM build from hello-world-user1.spec (hello-world-user -> hello-world-user1)

You can find the source file at the following location:

https://github.com/vmware/photon/tree/<BRANCH>/tools/examples/build_spec/user_package_example/hello-world-user.tar.gz

To generate the output in a staging directory, run the following command:

./photon/tools/scripts/build_spec.sh ./photon/tools/examples/build_spec/user_package_example/hello-world-user.spec $STAGEDIR

The following are the contents of the hello-world-user.spec file:

Summary:        Hello World User Package
Name:           hello-world-user
Version:        1.0
Release:        1%{?dist}
License:        GPLv2
Group:          System Environment/Kernel
Vendor:         VMware, Inc.
Distribution:   Photon
Source0:        hello-world-user.tar.gz
BuildRequires:  hello-world-user1
BuildRequires:  git
Requires:       hello-world-user1

%description
Example of building User Package for Photon OS

%prep
%autosetup -n hello-world-user

%build
make %{?_smp_mflags}

%install
pwd
make %{?_smp_mflags} install DESTDIR=%{buildroot}

%ldconfig_scriptlets

%files
%defattr(-,root,root)
/usr/bin/*

Build Logs

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

0. Build Script Version: 1.1
1. Create sandbox
        Use local build template image OK
2. Prepare build environment
        Create source folder OK
        Copy sources from ./photon/tools/examples/build_spec/user_package_example OK
        install createrepo OK
        createrepo  OK
        Create local repo in sandbox OK
        makecache OK
        Install build requirements OK
3. Build Binary and Source Package
        Run rpmbuild OK
        Delete SOURCES OK
4. Destroy sandbox
        Stop container OK
        Remove container OK
Build completed. RPMS are in '$STAGEDIR' folder.

4.4.4 - Include a patch file

This example shows how to build a package with a patch file. To build the package, you need to run the script with python-M2Crypto.spec as an argument, where python-M2Crypto.spec is the RPM specification file.

You can find the patch file at the following location:

https://github.com/vmware/photon/tree/<BRANCH>/tools/examples/build_spec/user_package_example/0001-openssl-3.0.0-support.patch

To generate the output in the spec-file folder, run the following command:

./photon/tools/scripts/build_spec.sh ./photon/tools/examples/build_spec/user_package_example/python-M2Crypto.spec

The following are the contents of the python-M2Crypto.spec file:

Name:           python3-M2Crypto
Version:        0.36.0
Release:        1%{?dist}
Summary:        Crypto and SSL toolkit for Python
Group:          Development/Languages/Python
License:        MIT
URL:            https://pypi.python.org/pypi/M2Crypto/0.26.0
Source0:        https://pypi.python.org/packages/11/29/0b075f51c38df4649a24ecff9ead1ffc57b164710821048e3d997f1363b9/M2Crypto-%{version}.tar.gz
Vendor:         VMware, Inc.
Distribution:   Photon

BuildRequires:  openssl
BuildRequires:  openssl-devel
BuildRequires:  python3-devel
BuildRequires:  python3-setuptools
BuildRequires:  python3-typing
BuildRequires:  swig
BuildRequires:  python3-xml
Requires:       python3-typing
Requires:       python3
Requires:       openssl
Patch0:         0001-openssl-3.0.0-support.patch

%description
M2Crypto is a crypto and SSL toolkit for Python featuring the following:

RSA, DSA, DH, HMACs, message digests, symmetric ciphers (including
AES). SSL functionality to implement clients and servers. HTTPS
extensions to Python's httplib, urllib, and xmlrpclib. Unforgeable
HMAC'ing AuthCookies for web session management. FTP/TLS client and
server. S/MIME. ZServerSSL: A HTTPS server for Zope. ZSmime: An S/MIME
messenger for Zope.

%prep
# Using autosetup is not feasible
%setup -q -n M2Crypto-%{version}
%patch0 -p1

%build
CFLAGS="%{optflags}" python3 setup.py build --openssl=/usr/include --bundledlls

%install
rm -rf %{buildroot}
python3 setup.py install --prefix=%{_prefix} --root=%{buildroot}

%files
%defattr(-,root,root)
%{python3_sitelib}/*

Build Logs

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

0. Build Script Version: 1.1
1. Create sandbox
        Use local build template image OK
2. Prepare build environment
        Create source folder OK
        Copy sources from ./photon/tools/examples/build_spec/user_package_example OK
        Download M2Crypto-0.36.0.tar.gz OK
        install createrepo OK
        createrepo  OK
        Create local repo in sandbox OK
        makecache OK
        Install build requirements OK
3. Build Binary and Source Package
        Run rpmbuild OK
        Delete SOURCES OK
4. Destroy sandbox
        Stop container OK
        Remove container OK
Build completed. RPMS are in './photon/tools/examples/build_spec/user_package_example/stage' folder

4.4.5 - Refer an External Source

This example shows how to build a package that downloads the source files from an external website like GitHub. To build the package, you need to run the script with libdrm.spec as an argument, where libdrm.spec is the RPM specification file.

./photon/tools/scripts/build_spec.sh ./photon/tools/examples/build_spec/user_package_example/libdrm.spec

The following are the contents of the libdrm.spec file:

Summary:        user space library for accessing the DRM.
Name:           libdrm
Version:        2.4.110
Release:        1%{?dist}
License:        MIT
URL:            http://dri.freedesktop.org/
Group:          System Environment/Libraries
Vendor:         VMware, Inc.
Distribution:   Photon

Source0:        https://dri.freedesktop.org/libdrm/%{name}-%{version}.tar.xz

BuildRequires:  meson
BuildRequires:  libpciaccess-devel
Requires:       libpciaccess
Provides:       pkgconfig(libdrm)

%description
libdrm provides a user space library for accessing the DRM, direct rendering manager, on operating systems that support the ioctl interface. libdrm is a low-level library, typically used by graphics drivers such as the Mesa DRI drivers, the X drivers, libva and similar projects.

%package        devel
Summary:        Header and development files
Requires:       %{name} = %{version}-%{release}

%description    devel
libdrm provides a user space library for accessing the DRM, direct rendering manager, on operating systems that support the ioctl interface. libdrm is a low-level library, typically used by graphics drivers such as the Mesa DRI drivers, the X drivers, libva and similar projects.

%prep
%autosetup -p1

%build
CONFIGURE_OPTS=(
        -Dintel=false
        -Dradeon=false
        -Damdgpu=true
        -Dnouveau=false
        -Dvmwgfx=false
        -Dlibkms=false
)

%meson "${CONFIGURE_OPTS[@]}"
meson --prefix=%{_prefix} build

%install
DESTDIR=%{buildroot}/ ninja -C build install

%ldconfig_scriptlets

%files
%defattr(-,root,root)
%{_libdir}/lib*
%{_datadir}/libdrm/*

%files devel
%defattr(-,root,root)
%{_includedir}/*
%{_libdir}/pkgconfig*

Build Logs

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

0. Build Script Version: 1.1
1. Create sandbox
        Use local build template image OK
2. Prepare build environment
        Create source folder OK
        Copy sources from ./photon/tools/examples/build_spec/user_package_example OK
        Download libdrm-2.4.110.tar.xz OK
        install createrepo OK
        createrepo  OK
        Create local repo in sandbox OK
        makecache OK
        Install build requirements OK
3. Build Binary and Source Package
        Run rpmbuild OK
        Delete SOURCES OK
4. Destroy sandbox
        Stop container OK
        Remove container OK
Build completed. RPMS are in './photon/tools/examples/build_spec/user_package_example/stage' folder

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

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

   Resource	Description
   VMware vSphere installed	VMware 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).
   Memory	ESXi host with 2GB of free RAM (recommended)
   Storage	Minimal 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 File	Photon 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.

4.5.2 - Importing the OVA for Photon OS

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.

   

   Choose Next.

2. Select the OVA File

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

   

   Choose Next.

3. Specify the Target Datastore

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

   

   Choose Next.

4. Accept the License Agreement

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

   

   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.

   

   Choose Next.

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

   

   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.

   

   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.

4.5.3 - Installing the ISO Image for Photon OS

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.

   

   Choose Next.

3. Configure VM Settings

   Specify a 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).

   

   Choose Next.

4. Select the Target Datastore

   Select the datastore where you want to store the VM.

   

   Click Next.

5. Customize VM Settings

   Customize the virtual machine 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.

   

   Click Finish. vSphere creates the VM.

7. Power on the VM

   Select the VM and power it on.

   

   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.

   

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.

   

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

   

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

   

   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.

10. Select an Installation Option

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

    

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

    Option	Description
    Photon Minimal	Photon 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 Developer	Photon 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 Host	This 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 Time	This 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.

    

    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.

    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.

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

12. Select the Linux Kernel

    Select a Linux kernel to install.

    

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

    

    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.

    

    Type a password and press the Enter key.

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

    

    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.

    

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

    

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

    

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

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

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

   Resource	Description
   VMware Fusion	VMware Fusion (v7.0 or higher) must be installed. The latest version (v12) is recommended.
   Memory	2GB of free RAM (recommended)
   Storage	Minimal Photon install : 512MB of free space (minimum); Full Photon install : 4GB of free space (minimum); 8GB recommended.
   Distribution File	Photon 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.

   

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.

4.6.2 - Importing the OVA for Photon OS

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

   

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

   

2. Specify the Name and Storage Location

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

   

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

   

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

   

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

   

   Choose General.

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

   

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

   

   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.

   

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

5. Update Login Credentials

   

   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.

4.6.3 - Installing the ISO Image for Photon OS

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.

   

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

   

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.

   

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.

   

   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.

   

   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.

   

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

   

   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.

   

   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.

   

   Press the Enter key on your keyboard to start installing.

   

   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.

   

   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.

   

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

   

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

   

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

   Option	Description
   Photon Minimal	Photon 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 Full	Photon 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 Server	This 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.

    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.

    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.

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

11. Select the Linux Kernel

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

    

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

    

    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.

    

    Confirm the root password by typing it a second time.

    

    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.

    

14. Reboot the VM and Log In

    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.

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

    

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

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

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

   Resource	Description
   VMware Workstation	VMware Workstation must be installed (Workstation 10 or higher). The latest version is recommended.
   Memory	2GB of free RAM (recommended)
   Storage	Minimal Photon install: 512MB of free space (minimum); Full Photon install: 4GB of free space (minimum); 8GB is recommended.
   Distribution File	Photon OS ISO or OVA file downloaded from VMware (https://packages.vmware.com/photon/5.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.

   

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/5.0/GA/

   For instructions, see Downloading Photon OS.

4.7.2 - Importing the OVA for Photon OS

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.

   

2. Specify the Name and Storage Location

   Change the name and storage location, if you want.

   

   Choose Import.

   

   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.

   

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

   

   Select the Options tab.

   

   Under Guest operating system, select Linux.

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

   

   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.

   

   Choose OK.

4. Power on the VM

   From the tab, choose Power on this virtual machine.

   

   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.

4.7.3 - Installing the ISO Image for Photon OS

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.

   

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

   

2. Select the ISO Image

   Select Installer disc image file (iso), choose Browse and select the Photon OS 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.

   

4. Specify the VM Name and Location

   Choose Next. Specify a virtual machine 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.

   

6. Configure VM Settings

   Choose Next. Workstation displays a summary of your selections.

   

   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.

   

   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.

   

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.

   

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

   Choose OK.

   

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.

   

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

   

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

   

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

   

   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.

   

10. Select an Installation Option

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

    

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

    Option	Description
    Photon Minimal	Photon 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 Full	Photon 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 Server	This 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.

    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.

    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.

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

12. Select the Linux Kernel

    Select a Linux kernel to install.

    

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

    

    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.

    

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

    

    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.

    

    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.

    

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

    

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

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

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

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

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

   

   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.

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

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

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

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

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

4.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 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 <your_resource_group> \
    --location westus
   

2. Create a storage account

   Create a storage account associated with this resource group.

   az storage account create \
       --resource-group <your_resource_group> \
       --location westus \
       --name <your_account_name> \
       --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 <your_resource_group> \
       --account-name <your_account_name>
   

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 <your_account_name> \
       --name <your_container_name>
   

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 <your_account_name> \
       --account-key <your_account_key> \
       --container-name <your_container_name> \
       --type page \
       --file <vhd_path> \
       --name <vm_name>.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=""
account_name=""
account_key=""
container_name="mydisks"
url="https://${account_name}.blob.core.windows.net/${container_name}/${vm_name}.vhd"
public_key_file="/root/azure_new/jenkins.pub"
echo "########################"
echo "#   Create container   #"
echo "########################"
/root/azure_new/bin/az storage container create --account-name ${account_name} --name ${container_name}
echo "##################"
echo "#   Upload vhd   #"
echo "##################"
/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 "##################"
echo "#   Create vm    #"
echo "##################"
echo "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 ... ..."
/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

4.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=""
account_name=""
account_key=""
container_name="mydisks"
url="https://${account_name}.blob.core.windows.net/${container_name}/${vm_name}.vhd"
public_key_file="/root/azure_new/jenkins.pub"
exit_code=0
echo "##################"
echo "#   Delete vm    #"
echo "##################"
echo "az vm list  --resource-group ${resource_group} ... ..."
/root/azure_new/bin/az vm list  --resource-group ${resource_group}
echo "az vm delete --resource-group ${resource_group} --name ${vm_name} --yes ... ..."
/root/azure_new/bin/az vm delete --resource-group ${resource_group} --name ${vm_name} --yes
if [$? -ne 0];then
   exit_code=1
fi
echo "az vm list  --resource-group ${resource_group} ... ..."
/root/azure_new/bin/az vm list  --resource-group ${resource_group}
echo "##############$####"
echo "#   Delete vhd    #"
echo "###############$###"
echo "az storage blob list --account-name ${account_name} --container-name ${container_name} ... ..."
/root/azure_new/bin/az storage blob list --account-name ${account_name} --container-name ${container_name}
echo "az storage blob delete --account-name ${account_name} --container-name ${container_name} --name ${vm_name}.vhd ... ..."
/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 "az storage blob list --account-name ${account_name} --container-name ${container_name} ... ..."
/root/azure_new/bin/az storage blob list --account-name ${account_name} --container-name ${container_name}
echo "########################"
echo "#   Delete container   #"
echo "########################"
/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.

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

4.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/5.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./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"
    

4.10.2 - Installing Photon OS on Google Compute Engine

You can use either the Google Cloud Platform or the gcloud CLI to upload the Photon OS GCE tar file to the bucket, and create the Image & Photon OS VM instance.

Setting Up Using the Google Cloud Platform

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.

   

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.

   

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.

   

   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.

Setting Up Using the gcloud CLI

​ Example Setup Script:
​ You can use the following script (create.sh) to upload your tar file programmatically to the bucket and create the VM. ​

#!/bin/bash
timestamp=$(date +%s)
export PATH=$PATH:/root/gce/google-cloud-sdk/bin
​
# get branch name in order to determine the machine type.
GCE_VM_NAME=$2
branch=`echo ${GCE_VM_NAME} | cut -d '-' -f 1`
​
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
GCE_USERNAME=<gce_username>
GCE_BUCKET=<gs://bucket-name>
​
if [ $# -lt 2 ]
then
  echo "Usage is: create.sh <path_to_gce_image.tar.gz> <vm_name> [(optional) <user-data-file-path>]";
  exit;
fi
​
echo "Uploading gce tar.gz to gce bucket...."
/root/gce/google-cloud-sdk/bin/gsutil cp ${1} $GCE_BUCKET/photon-gce-${timestamp}.tar.gz
if [ ! "$?" -eq 0 ]; then
    echo "Failed: couldn't upload to gce bucket"
    exit 1
fi
​
echo "GCE tar.gz uploaded successfully, proceeding with image creation"
gcloud compute images create ${2}-image --source-uri $GCE_BUCKET/photon-gce-${timestamp}.tar.gz
if [ ! "$?" -eq 0 ]; then
    echo "Failed: couldn't create image successfully"
    exit 1
fi
​
echo "GCE image created successfully. Proceeding with instance creation"
if [[ ( "${branch}" != "one" ) && ( "${branch}" != "two" ) ]];then
    machine_type="n1-standard-1"
else
    machine_type="n1-standard-2"
fi
echo branch=$branch
echo machine_type=$machine_type
​
if [ $# -gt 2 ]
then
    gcloud compute instances create ${2} --machine-type ${machine_type} --image ${2}-image --metadata-from-file=user-data=${3}
else
    gcloud compute instances create ${2} --machine-type ${machine_type} --image ${2}-image
fi
if [ ! "$?" -eq 0 ]; then
    echo "Failed: couldn't create instance successfully"
    exit 1
fi
echo "Photon Instance created successfully on GCE"
​
externalip="$(gcloud compute instances list ${2} --format='value(networkInterfaces[].accessConfigs[].natIP)')"
echo $externalip
GCE_VM_IP=$externalip
echo GCE_VM_IP=$GCE_VM_IP

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

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

   Resource	Description
   Raspberry Pi 3	Raspberry Pi 3 Model B or Model B+ board. This will serve as the target of the installation.
   Raspberry Pi 4	Raspberry 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 File	Photon 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/5.0/GA/rpi/rpi.tar.xz.

      For instructions, see Downloading Photon OS.

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

4.11.3 - Enabling Raspberry Pi Interfaces using Device Tree

Photon OS RPI images from Photon OS 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

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

   

   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.

   

   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.

   

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

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

5 - Administration Guide

The Photon OS Administration Guide describes the fundamentals of administering Photon OS.

The Administration Guide covers the basics of managing packages, controlling services with systemd, setting up networking, initializing Photon OS with cloud-init, running Docker containers, and working with other technologies, such as Kubernetes.

Product version: 5.0

This documentation applies to all 5.0.x releases.

Intended Audiences

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

5.1 - Photon OS Packages

The design of Photon OS simplifies life-cycle management and improves the security of packages. Photon reduces the burden and complexity of managing clusters of Linux machines by providing curated package repositories and by securing packages with GPG signatures.

Photon OS is available in a variety of pre-built packages in binary formats.

5.1.1 - Examining the Packages in the SPECS Directory on Github

The SPECS directory of the GitHub website for Photon OS contains all the packages that can appear in Photon OS repositories. The following is the path to the SPECS directory:

https://github.com/vmware/photon/tree/master/SPECS

To see the version of a package, in the SPECS directory, click the name of the subdirectory of the package that you want to examine, and then click the .spec filename in the subdirectory.

For example, python3.spec appears as follows::

%global VER 3.11
%global with_gdb_hooks 1

Summary:        A high-level scripting language
Name:           python3
Version:        3.11.0
Release:        6%{?dist}
License:        PSF
URL:            http://www.python.org
Group:          System Environment/Programming
Vendor:         VMware, Inc.
Distribution:   Photon

5.1.2 - Looking at the Differences Between the Minimal and the Full Version

The minimal version of Photon OS contains around 50 packages. As it is installed, the number of packages increases to nearly 100 to fulfill dependencies. The full version of Photon OS adds several hundred packages to those in the minimal version to deliver a more fully featured operating system.

You can view a list of the packages that appear in the minimal version by examining the following file:

https://github.com/vmware/photon/blob/master/common/data/packages_minimal.json

You can view a list of the packages that appear in the full (aka “developer”) version by examining the following file:

https://github.com/vmware/photon/blob/master/common/data/packages_full.json

If the minimal or the developer version of Photon OS does not contain a package that you want, you can install it with tdnf, which appears in both the minimal and full versions of Photon OS by default. In the full version of Photon OS, you can also install packages by using yum.

One notable difference between the two versions of Photon OS pertains to OpenJDK, the package that contains not only the Java runtime environment (openjre) but also the Java compiler (javac). The OpenJDK package appears in the full but not the minimal version of Photon OS.

To add support for Java programs to the minimal version of Photon OS, install the Java packages and their dependencies by using the following command:

```console
tdnf install openjdk
Installing:
openjre 	x86_64    1.8.0.92-1.ph1    95.09 M
openjdk 	x86_64    1.8.0.92-1.ph1    37.63 M
```

NOTE: openjdk and openjre are available as openjdk8 and openjre8 in Photon OS 3.0 and later.

For more information about tdnf, see Tiny DNF for Package Management

5.1.3 - The Root Account and the 'sudo' and 'su' Commands

The Photon OS Administration Guide assumes that you are logged in to Photon OS with the root account and running commands as root.

On the minimal version, you must install sudo with tdnf if you want to use it. As an alternative to installing sudo, to run commands that require root privileges you can switch users as needed with the su command.

5.1.4 - Examining Signed Packages

Photon OS signs its packages and repositories with GPG signatures to enhance security. The GPG signature uses keyed-hash authentication method codes, typically the SHA1 algorithm and an RSA Data Security, Inc. MD5 Message Digest Algorithm, to simultaneously verify the integrity of a package. A keyed-hash message authentication code combines a cryptographic hash function with a secret cryptographic key.

In Photon OS, GPG signature verification automatically takes place when you install or update a package with the default package manager, tdnf. The default setting in the tdnf configuration file for checking the GPG is set to 1 for true:

cat /etc/tdnf/tdnf.conf
[main]
gpgcheck=1
installonly_limit=3
clean_requirements_on_remove=true
repodir=/etc/yum.repos.d
cachedir=/var/cache/tdnf

On Photon OS, you can view the key with which VMware signs packages by running the following command:

rpm -qa gpg-pubkey*

The command returns the GPG public key:

gpg-pubkey-66fd4949-4803fe57
gpg-pubkey-8a6a826d-596882ca

Once you have the name of the key, you can view information about the key with the rpm -qi command, as the following abridged output demonstrates:

rpm -qi gpg-pubkey-66fd4949-4803fe57
Name        : gpg-pubkey
    Version     : 66fd4949
    Release     : 4803fe57
    Architecture: (none)
    Install Date: Thu Jun 16 11:51:39 2016
    Group       : Public Keys
    Size        : 0
    License     : pubkey
    Signature   : (none)
    Source RPM  : (none)
    Build Date  : Tue Apr 15 01:01:11 2008
    Build Host  : localhost
    Relocations : (not relocatable)
    Packager    : VMware, Inc. -- Linux Packaging Key -- <linux-packages@vmware.com>
    Summary     : gpg(VMware, Inc. -- Linux Packaging Key -- <linux-packages@vmware.                        com>)
    Description :
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: rpm-4.11.2 (NSS-3)
    mI0ESAP+VwEEAMZylR8dOijUPNn3He3GdgM/kOXEhn3uQl+sRMNJUDm1qebi2D5b ...

rpm -qi gpg-pubkey-8a6a826d-596882ca
Name        : gpg-pubkey
Version     : 8a6a826d
Release     : 596882ca
Architecture: (none)
Install Date: Tue 18 Apr 2023 10:17:59 AM UTC
Group       : Public Keys
Size        : 0
License     : pubkey
Signature   : (none)
Source RPM  : (none)
Build Date  : Fri 14 Jul 2017 08:37:30 AM UTC
Build Host  : localhost
Packager    : VMware, Inc. (Linux Packaging Key) <linux-packages@vmware.com>
Summary     : VMware, Inc. (Linux Packaging Key) <linux-packages@vmware.com> public key
Description :
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: rpm-4.18.0

mQINBFlogsoBEACylcZdKvVdq+XZZ5oXyV7+Wk4wYo9ALIy5Y/TlQ7YoJndF3A6d
j3KXLFZ3xLMYuktUwqEiVN24s2loAG3kcS5c8bb7LxiZMFoEfo8bUm8mcfcPKCdy
ZgE0TNwYejn6w9tuEOLtewVtFaP3FrCjzZz2VMXi5c9sNxmIxfrBuuDZP8MLoDKr
fv4Zzif2K6J4nRMBY2t8SSj8Z4zDUCLQ36wYlD2slONdmX8Ufd86rt/ZJ156xsCX
2UgTb62uUVESlWfsuMhv5CBO2JEbbnMBjfZdI5qplwEt54kq34PzP6fRCa8yrLR8
FlZsAQO32A0SDNUWHphDP3d2W64XtttjRJPsWv16IXss1YwyjUd1CBYDpefXvzW2
h8Ca6HDgLRG0eoVZdY8gx1geF64wuGjSA+4gnjTaMeLQSBfeAzm6Pe4eB6bEc/iX
NiZY9KlA1orRcuHxXIzjsHR5f1JCK0Fgl76aNzxnztuU0uRSLZRxUMUpszCOyqy9
ufsbMeklbKtobfVqRulQEJwCXHL99t+Ln14L3PgXKeLqaj/LReIqWlWiFtm6Zgyf
a45z8lf8Z3lRK+orrNJ8fVJr/8T9O/vgpbwwqEZ2bflzqXcUPyWnMl6Cu8SNbtwK
orvZ1bwNkz5T9myW+6pXcr9sB/IiNmyfTS1rXqwUlRN60vwD+a52MpnCGwARAQAB
tD5WTXdhcmUsIEluYy4gKExpbnV4IFBhY2thZ2luZyBLZXkpIDxsaW51eC1wYWNr
YWdlc0B2bXdhcmUuY29tPokCNgQTAQIAIAUCWWiCygIbAwYLCQgHAwIEFQIIAwQW
AgMBAh4BAheAAAoJEHXACeqKaoJtIYIP/3y2+xIZ3ZArdhH6NR3ilMPGSVoe1M2+
10XlL9wydgXPdKrq8IZUNg5/VBEjpOZML82aD9VRkMXI6XdbrdRw+5G2D5ZOtWRp
ha8KPuFxax2YuB8ifRgcrgR0kq4v+p3XHaT88UQxk/gDpJVOMJaLhyn8KNBPVkPq
zJ3IXC/A/rWv6rbDAnyyt20GpCqWuoCJCQDMCbBItyaL42OWY3yk3WlfFOjQU1Sq
zIYCCJGM87rNHpwErHDIanFu0gXCarFB6uRT9ixgyJqg7dtPAyBdydxo0JesH0Fc
t30NYkRiqqeSz6ImWlcvDHZkiDXNvP0D9utyOPQDoIaX+G0gCnf+UpHTgc0eGc6U
+aHIyHMK7Du+cfTXL8W5LAbSw7pTPSPc/sZal1ijDvk1lyMhT6kZ22v2IXYadosp
eA7+9ykSk3Iy9qhjUTQ+qG/KMgUTMVqWUp6IEze80892w3yNFi8tEvdRzORbOHuP
IhyoLek4vQj+ziDm4C1ARrYk8AiW40ioRJuT73DF8RhuzD8hBt1tH6mjeIANz8Lf
1big996JofkxU2eN99MnhUeBxFrOCPef7y9h0rM7UqZHDo1HGxCZxd12COyspWkG
WsFN4VrLxkXhPfa8jc5TBY5e1632JoL+VuWFjKd0CddgtSm2bqfX355BQi6+eJ4A
kJ3L8QRJSNeY
=ogBe
-----END PGP PUBLIC KEY BLOCK-----

#

If you have one of the RPMs from Photon OS on another Linux system, such as Ubuntu, you can use SHA and the RSA Data Security, Inc. MD5 Message Digest Algorithm for the package to verify that it has not been tampered with:

rpm -K GConf-3.2.6-1.ph5.src.rpm
GConf-3.2.6-1.ph5.src.rpm: digests signatures OK

You can view the SHA1 digest and the RSA Data Security, Inc. MD5 Message Digest Algorithm by running the following command:

rpm -Kv GConf-3.2.6-1.ph5.src.rpm
GConf-3.2.6-1.ph5.src.rpm:
    Header V3 RSA/SHA256 Signature, key ID 66fd4949: OK
    Header SHA256 digest: OK
    Header SHA1 digest: OK
    Payload SHA256 digest: OK
    V3 RSA/SHA256 Signature, key ID 66fd4949: OK
    MD5 digest: OK
#

The above examples show that the Kubernetes package has not been tampered with.

5.1.5 - Photon OS Package Repositories

The default installation of Photon OS includes yum-compatible repositories and the repository on the Photon OS ISO when it is available on a CD-ROM drive:

# ls -l /etc/yum.repos.d/
total 24
-rw-r--r-- 1 root root 313 Apr 17 13:19 photon-debuginfo.repo
-rw-r--r-- 1 root root 238 Apr 17 13:19 photon-iso.repo
-rw-r--r-- 1 root root 299 Apr 17 13:19 photon-release.repo
-rw-r--r-- 1 root root 303 Apr 17 13:19 photon.repo
-rw-r--r-- 1 root root 331 Apr 17 13:19 photon-srpms.repo
-rw-r--r-- 1 root root 305 Apr 19 06:00 photon-updates.repo

The Photon ISO repository (photon-iso.repo) contains the installation packages for Photon OS. All the packages that Photon builds and publishes reside in the RPMs directory of the ISO when it is mounted. The RPMs directory contains metadata that lets it act as a yum repository. Mounting the ISO gives you all the packages corresponding to a Photon OS build. If, however, you built Photon OS yourself from the source code, the packages correspond only to your build, though they will typically be the latest. In contrast, the ISO that you obtain from the VMware Photon Packages web site contains only the packages that are in the ISO at the point of publication. As a result, the packages may no longer match those on in the ISO, because they are updated more frequently.

The Photon repository (photon.repo) contains all the rpms released for a particular Photon release. This repository is disabled by default but can be enabled in case the end user wants to install an older version of an rpm.

The Photon Updates repository (photon-updates.repo) contains the latest versions of all the rpms for a particular Photon release. This repository is updated with the new rpm releases. This repository is enabled by default.

The Photon debuginfo repository (photon-debuginfo.repo) contains the debuginfo rpms which can be installed for debugging coredumps or issues. This repository is disabled by default.

The Photon release repository (photon-release.repo) contains the rpms snapped at the major release time. This repository is not updated after GA. This repository is disabled by default.

The Photon SRPM repository (photon-srpms.repo) contains all the source rpms for a particular Photon release. This can be used to extract the source which was used to build the rpm. This repository is disabled by default.

5.1.6 - Building a Package from a Source RPM

This section describes how to install and build a package on the full version of Photon OS from the package’s source RPM. Obtain the source RPMs that Photon OS uses from the VMWare Packages repository: packages.vmware.com/photon

Prerequisites

• To build a package from its source RPM, or SRPM, Photon OS requires the following packages:

  • rpmbuild. This package is installed by default on the full version of Photon OS, so you should not have to install it.

  • gcc. This package is also installed by default on the full version of Photon OS, so you should not have to install it.

  • make, Cmake, automake, or another make package, depending on the package you are trying to install and build from its source RPM. Cmake is installed by default on Photon OS.

    You can install other make packages by using tdnf or yum.

• A local unprivileged user account other than the root account. You should build RPMs as an unprivileged user. Do not build a package as root becau–building an RPM with the root account might damage your system.

• Take a snapshot of your virtual machine before building the package if you are building a package on a virtual machine running Photon OS in VMware vSphere, VMware Workstation, or VMware Fusion.

Procedure

VMware recommends that you install and build packages from their source RPMs on the full version of Photon OS. Do not use the minimal version to work with source RPMs.

Perform the following steps to install and build an example package- sed from its source RPM on Photon OS with an unprivileged account.

1. check whether rpmbuild is installed by running the following command:

   rpmbuild --version
   

   If it is not installed, install it by running the following command as root:

   tdnf install rpm-build
   

2. Create the directories for building RPMs under your local user account home directory and not under root:

   mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
   

3. Create a .rpmmacros file under your home directory and override the default location of the RPM building tree with the new one. This command overwrites an existing .rpmmacros file. Before running the following command, make sure you do not already have a .rpmmacros file. If a .rpmmacros file exists, back it up under a new name in case you want to restore it later.

   echo '%_topdir %(echo $HOME)/rpmbuild' > ~/.rpmmacros
   

4. Place the source RPM file that you want to install and build in the /tmp directory.

5. Install the source file, run the following command with your unprivileged user account, replacing the sed example source RPM with the name of the one that you want to install:

   rpm -i /tmp/sed-4.2.2-2.ph1.src.rpm
   

   The above command unpacks the source RPM and places its .spec file in your ~/rpmbuild/SPECS directory. In the next step, the rpmbuild tool uses the .spec file to build the RPM.

6. Build the RPM, run the following commands with your unprivileged user account. Replace the sed.spec example file with the name of the .spec file that you want to build.

   cd ~/rpmbuild/SPECS
   rpmbuild -ba sed.spec
   

   If successful, the rpmbuild -ba command builds the RPM and generates an RPM package file in your ~/rpmbuild/RPMS/x86_64 directory. For example:

   ls RPMS/x86_64/
   sed-4.2.2-2.x86_64.rpm  sed-debuginfo-4.2.2-2.x86_64.rpm  sed-lang-4.2.2-2.x86_64.rpm
   

   The rpmbuild command also generates a new SRPM file and saves it in your ~/rpmbuild/SRPMS directory. For example:

   ls SRPMS/
   sed-4.2.2-2.src.rpm
   

   If the rpmbuild command is unsuccessful with an error that it cannot find a library, you must install the RPMs for the library that your source RPM depends on before you can successfully build your source RPM. Iterate through installing the libraries that your source RPM relies on until you can successfully build it.

7. To install the RPM, run the following command with your unprivileged user account:

   rpm -i RPMS/x86_64/sed-4.2.2-2.x86_64.rpm
   

5.1.7 - Compiling C++ Code on the Minimal Version of Photon OS

As a minimalist Linux run-time environment, the minimal version of Photon OS lacks the packages that you need to compile the code for a C++ program. For example, without the requisite packages, trying to compile the file containing the following code with the gcc command will generate errors:

#include <stdio.h>
int main()
{
return 0;
}

The errors appear as follows:

gcc test.c
-bash: gcc: command not found
tdnf install gcc -y
gcc test.c
test.c:1:19: fatal error: stdio.h: No such file or directory
compilation terminated.

To enable the minimal version of Photon OS to preprocess, compile, assemble, and link C++ code, you must install the following packages as root with tdnf:

• gcc
• glibc-devel
• binutils

To install the packages, use the following the tdnf command:

tdnf install gcc glibc-devel binutils

5.2 - Package Management in Photon OS with 'tdnf'

Photon OS manages packages with an open source, yum-compatible package manager called tdnf, for Tiny Dandified Yum. Tdnf keeps the operating system as small as possible while preserving yum’s robust package-management capabilities.

5.2.1 - Introduction to 'tdnf'

On Photon OS, tdnf is the default package manager for installing new packages. It is a C implementation of the DNF package manager without Python dependencies.

Tdnf appears in the minimal and full versions of Photon OS.

Tdnf implements a subset of the dnf commands as listed in the dnf guide.

5.2.2 - Configuration Files and Repositories

The main configuration files reside in /etc/tdnf/tdnf.conf. The configuration file appears as follows:

cat /etc/tdnf/tdnf.conf
[main]
gpgcheck=1
installonly_limit=3
clean_requirements_on_remove=true
repodir=/etc/yum.repos.d
cachedir=/var/cache/tdnf

The cache files for data and metadata reside in /var/cache/tdnf.

The following repositories appear in /etc/yum.repos.d/ with .repo file extensions:

ls /etc/yum.repos.d/
photon-extras.repo
photon-iso.repo
photon-updates.repo
photon.repo 

You can list the the repositories by using the tdnf repolist command. Tdnf filters the results with enabled, disabled, and all. Running the command without specifying an argument returns the enabled repositories:

tdnf repolist
repo id             repo name                               status
photon-updates      VMware Photon Linux 2.0(x86_64)Updates  enabled
photon-extras       VMware Photon Extras 2.0(x86_64)        enabled
photon              VMware Photon Linux 2.0(x86_64)         enabled

The photon-iso.repo, however, does not appear in the list of repositories because it is unavailable on the virtual machine from which these examples are taken. The photon-iso.repo is the default repository and it points to /media/cdrom. The photon-iso.repo appears as follows:

cat /etc/yum.repos.d/photon-iso.repo
[photon-iso]
name=VMWare Photon Linux 2.0(x86_64)
baseurl=file:///mnt/cdrom/RPMS
gpgkey=file:///etc/pki/rpm-gpg/VMWARE-RPM-GPG-KEY
gpgcheck=1
enabled=0
skip_if_unavailable=True

The local cache is populated with data from the repository:

ls -l /var/cache/tdnf/photon
total 8
drwxr-xr-x 2 root root 4096 May 18 22:52 repodata
d-wxr----t 3 root root 4096 May  3 22:51 rpms

You can clear the cache to help troubleshoot a problem, but doing so might slow the performance of tdnf until the cache becomes repopulated with data. To clear the cache, use the following command:

tdnf clean all
Cleaning repos: photon photon-extras photon-updates lightwave
Cleaning up everything

The command purges the repository data from the cache:

ls -l /var/cache/tdnf/photon
total 4
d-wxr----t 3 root root 4096 May  3 22:51 rpms

5.2.3 - Adding a New Repository

On Photon OS, you can add a new repository from which tdnf installs packages. To add a new repository, you create a repository configuration file with a .repo extension and place it in /etc/yum.repos.d. The repository can be on either the Internet or a local server containing your in-house applications.

Be careful if you add a repository that is on the Internet. Installing packages from untrusted or unverified sources might put the security, stability, or compatibility of your system at risk. It might also make your system harder to maintain.

On Photon OS, the existing repositories appear in the /etc/yum.repos.d directory:

ls /etc/yum.repos.d/
photon-extras.repo
photon-iso.repo
photon-updates.repo
photon.repo 

To view the format and information that a new repository configuration file should contain, see one of the .repo files. The following is an example:

[photon-release]
name=VMware Photon Linux $releasever ($basearch)
baseurl=https://packages.vmware.com/photon/$releasever/photon_release_$releasever_$basearch
gpgkey=file:///etc/pki/rpm-gpg/VMWARE-RPM-GPG-KEY
gpgcheck=1
enabled=1
skip_if_unavailable=True

You can configure multiple repositories in one repository configuration file. Configuration for each of the repositories must have a separate section and ID.

The repository settings details are as follows:

• The minimal information needed to establish a repository is an ID and human-readable name of the repository and its base URL. The ID, which appears in square brackets, must be one word that is unique among the system’s repositories; `.

• The username setting specifies a username for the repository, if required.

• The password setting sets a password for the repository, if required.

• The baseurl is a URL for the repository’s repodata directory. For a repository on a local server that can be accessed directly or mounted as a file system, the base URL can be a file referenced by file://. Example:

  baseurl=file:///server/repo/

  You can also use the following protocols: http: https: ftp: ftps: file: You can add multiple URLs separated by commas. If download fails for one URL, the next URL is used. The URL can contain the variables $releasever and $basearch, which refers to the current release of the distribution (for example, 5.0) and the architecture (for example, x86_64 or aarch64).

• You can use the metalink file to set hashes and priorities for URLs. To use the metalink feature, the tdnf-metalink plugin must be installed and loaded. A sample metalink file is as follows:

  cat metalink

  <?xml version="1.0" encoding="utf-8"?>
  
  <metalink version="3.0" xmlns="http://www.metalinker.org/" type="dynamic" pubdate="Wed, 05 Feb 2020 08:14:56 GMT" generator="mirrormanager" xmlns:mm0="http://fedorahosted.org/mirrormanager">
  
   <files>
  
    <file name="repomd.xml">
  
     <size>2035</size>
  
     <verification>
  
  <hash type="sha1">478437547dac9f5a73fe905d2ed2a0a5b153ef46</hash>
  
  <hash type="sha512">6c6fbfba288ec90905a8d2220a0bfd2a50e835b7faaefedb6978df6ca59c5bce25cc1ddd33023e305b20bcffc702ee2bd61d0855f4f1b2fd7c8f5109e428a764</hash>
  
     </verification>
  
     <resources maxconnections="1">
  
  <url protocol="http" type="http" location="IN" preference=“100”>https://packages.vmware.com/photon/3.0/photon_updates_3.0_x86_64/repodata/repomd.xml</url>
  
     </resources>
  
    </file>
  
   </files>
  
  </metalink>
  

  In the metalink file, provide the preference for each url, so tdnf first tries to sync the repository data from the mirror which has the highest preference. If it fails for any reason, tdnf will use the next mirror URL.

  Note: Ensure that the shasum for respomd.xml in all the mirrors should be same.

• The metadata_expire setting specifies the expiry time limit for the downloaded metadata in seconds. After the set limit expires, metadata is refreshed on the next action that requires them. The default value is 172800 seconds.

• The priority setting specifies the priority of the repositories.

• The gpgcheck setting specifies whether to check the GPG signature. The default value is true. If you enable this setting, set the gpgkey.

• The repo_gpgcheck setting allows tdnf to verify the signature of a repository metadata before downloading the repository artifacts. When repo_gpgcheck is set to 1 in the tdnf.conf file, all repositories are checked for the metadata signatures. The default value is 0. To use the repo_gpgcheck feature, the tdnf repogpgcheck plugin must be installed and enabled. If a repository has repo_gpgcheck enabled,a repomd.xml.asc file is downloaded and the API equivalent of gpg --verify repomd.xml.asc repomd.xml is done. If repomd.xml.asc is missing, repository is deactivated. If repomd.xml.asc fails to verify, the repository is deactivated. The public key for verification must be manually installed for the initial implementation.

  Note: Ensure that you have installed libgcrypt for this implementation.

• The gpgkey setting furnishes the URL for the repository’s ASCII-armored GPG key file. tdnf uses the GPG key to verify a package if its key has not been imported into the RPM database.

  The repository configuration also supports public keys that are remote for the gpgkey option. So, the URLs starting with http, https, or ftp can be used for gpgkey.

  For example: gpgkey=http://build-squid.eng.vmware.com/build/mts/release/bora-16633979/publish/packages/keys/vmware.asc

• You can use the enabled setting to enable the repository. The default value is false. You can override this setting with --disablerepo, --enablerepo, and --repoid options on the command line.

• The skip_if_unavailable setting instructs tdnf to continue running if the repository goes offline.

• The retries setting in the repository configuration specifies the number of retries when downloading a file throws an error. The default is 10.

• The timeout setting specifies the number of seconds that a download is allowed to take or 0 for no limit. Note that this is an absolute value and may interrupt large file downloads.

• The minrate setting specifies the limit below which if the download rate falls, tdnf aborts the download. The default value is 0 (no limit).

• The maxrate setting specifies the maximum download rate (throttle). The default value is 0 (no limit).

• You can use the skip metadata download settings to skip the download of metadata files for repositories with a lot of packages. When you skip the download of the metadata files, it improves the download time of the packages and the processing time of refreshing the cache.

  The following list describes the benefits and drawbacks of the skip metadata settings:

  • skip_md_filelists: The skip_md_filelists=1 setting deactivates the download of the complete list of files in all packages. The setting improves the download and processing time but affects the repoquery queries for files. The default value is 0.

  • skip_md_other: The skip_md_other=1 setting deactivates the download of miscellaneous data like the changelog data of packages. The setting improves the download and processing time but affects the repoquery queries for changelogs. The default value is 0.

  • skip_md_updateinfo: The skip_md_updateinfo=1 setting deactivates the download of the update info data. The setting improves the download and processing time but affects the output of the updateinfo command. The default value is 0.

• Other options and variables can appear in the repository file. The variables that are used with some of the options can reduce future changes to the repository configuration files. There are variables to replace the value of the version of the package and to replace the base architecture. For more information, see the man page for yum.conf on the full version of Photon OS: man yum.conf

The following is an example of how to add a new repository for a local server that tdnf polls for packages:

cat > /etc/yum.repos.d/apps.repo << "EOF"
[localapps]
name=Local In-House Applications(x86_64)
baseurl=file:///appserver/apps
enabled=1
skip_if_unavailable=True
EOF

Because this new repository resides on a local server, make sure the Photon OS machine can connect to it by mounting it.

After establishing a new repository, you must run the following command to update the cached binary metadata for the repositories that tdnf polls:

tdnf makecache
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)Updates'
Refreshing metadata for: 'VMware Photon Extras 1.0(x86_64)'
Refreshing metadata for: 'Local In-House Applications(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)'
Metadata cache created.

You can also specify the SSL Certificate details in the following settings:

• sslcacert: Use a string value.
• sslclientcert: Use a string value.
• sslclientkey: Use a string value.
• sslverify: Specify whether to perform the SSL verification. The default value is true.

5.2.4 - Mount the Photon ISO Image for the Photon-ISO Repository

Photon OS comes with a preconfigured repository called photon-iso that resides in \etc\yum.repos.d. If you receive an access error message when working with the photon-iso repository, it is probably because you do not have the Photon OS ISO mounted. Mount the ISO and the run the following command to update the metadata for all known repositories, including photon-iso:

mount /dev/cdrom /media/cdrom
tdnf makecache

Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)Updates'
Refreshing metadata for: 'VMware Photon Extras 1.0(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)'
Metadata cache created.

5.2.5 - Adding the Dev Repository to Get New Packages from the GitHub Dev Branch

To try out new packages or the latest versions of existing packages as they are merged into the dev branch of the Photon OS GitHub site, add the dev repository to your repository list.

Perform th following steps:

1. On your Photon OS machine, run the following command as root to create a repository configuration file named photon-dev.repo, place it in /etc/yum.repos.d, and concatenate the repository information into the file:

cat > /etc/yum.repos.d/photon-dev.repo << "EOF" 
    [photon-dev]
    name=VMware Photon Linux Dev(x86_64)
    baseurl=https://packages.vmware.com/photon/dev/photon_dev_$basearch
    gpgkey=file:///etc/pki/rpm-gpg/VMWARE-RPM-GPG-KEY
    gpgcheck=1
    enabled=1
    skip_if_unavailable=True
    EOF
    .

2. After establishing a new repository, run the following command to update the cached binary metadata for the repositories that tdnf polls:

tdnf makecache

5.2.6 - tdnf-automatic

tdnf-automatic is an alternative Command Line Interface (CLI) to tdnf upgrade/tdnf update with specific features so that it is suitable to be executed automatically and regularly from systemd timers, cron jobs, and so on.

The operation of the tool is usually controlled by the configuration file or the function-specific timer units. The command only accepts a single optional argument pointing to the config file, and some control arguments intended for use by the services that back the timer units. If no configuration file is passed from the command line,then /etc/tdnf/automatic.conf is used.

The tool synchronizes package metadata as needed and then checks for the updates available for the given system and then either exits or shows available updates or downloads and installs the packages.

The outcome of the operation is then reported through stdio.

The systemd timer unit tdnf-automatic.timer behaves as the configuration file specifies whether to download and apply updates. Some other timer units are provided which override the configuration file with some standard behaviors:

* tdnf-automatic-notifyonly

* tdnf-automatic-install

Irrespective of the configuration file settings, the first only notifies of available updates. The second one downloads and installs the updates.

Run tdnf-automatic

You can select one that most closely fits your needs, customize /etc/tdnf/automatic.conf for any specific behaviors, and enable the timer unit.

For example: systemctl enable –now tdnf-automatic-notifyonly.timer

Configuration file format

The configuration file is separated into two sections. This basically gives info on what can be put in /etc/tdnf/automatic.conf. ‘automatic.conf’ is a configuration INI file.

Format

tdnf-automatic help:

tdnf-automatic [{-c|--conf config-file}(optional)] [{-i|--install}] [{-n|--notify}] [{-h|--help}] [{-v|--version}]



-c, --conftdnf-automatic configuration file (Optional argument)

-i, --installOverride automatic.conf apply_updates and install updates

-n, --notifyShow available updates

-h, --helpShow this help message

-v, --versionShow tdnf-automatic version information

Commands

To set the mode of the operation of the program:

• apply_updates (boolean, default: no) Whether packages comprising the available updates should be applied by tdnf-automatic.timer, i.e. installed via RPM. Note that the other timer units override this setting.

• show_updates (boolean, default: yes) To just receive updates use tdnf-automatic-notifyonly.timer

• network_online_timeout (time in seconds, default: 60) Maximum time tdnf-automatic will wait until the system is online. 0 means that network availability detection will be skipped.

• random_sleep (time in seconds, default: 0) Maximum random delay before downloading. Note that, by default, the systemd timers also apply a random delay of up to 1 hour.

• upgrade_type (either one of all or security. default: all) Looks at the kind of upgrades. all signals looking for all available updates. security indicates only those with an issued security advisory.

• tdnf_conf (string, default: /etc/tdnf/tdnf.conf) Configurations to override default tdnf configuration.

Reports

To select how the results should be reported:

• emit_to_stdio (boolean, default: yes) Report the results through stdio. If no, no report will be shown.

• system_name (string, default: hostname of the given system) How the system is called in the reports.

• emit_to_file (string, absolute path of file) If we want to capture the logs in a file

5.2.7 - Install Packages from CLI

You can install the packages from the command line. The package can be a file or a URL. The dependencies are installed automatically.

For example:

• Using a URL:

    tdnf install https://packages.vmware.com/photon/5.0/photon_release_5.0_x86_64/x86_64/open-vm-tools-11.2.5-1.ph5.x86_64.rpm
  
    open-vm-tools-11.2.5-1.ph5.x86_64.rpm 763014   100%
  
    Installing:
  
    attrx86_642.4.48-1.ph5  photon  88.65k 90778
  
    nss x86_643.57-2.ph5photon  1.69M 1768005
  
    ...
  
    open-vm-tools   x86_6411.2.5-1.ph5  @cmdline2.65M 2779392
  
  
    Total installed size:  91.57M 96019175
  
  
    Upgrading:
  
    nss-libsx86_643.57-2.ph5photon  2.48M 2601790
  
    util-linux-libs x86_642.36-2.ph5photon752.75k 770816
  
    pcre-libs   x86_648.44-2.ph5photon275.60k 282216
  
  
  
    Total installed size:   3.49M 3654822
  
    Is this ok [y/N]: 
  

• Using a file:

    tdnf install ../lsof-4.91-1.ph5.x86_64.rpm 
  
  
    Installing:
  
    libtirpcx86_641.2.6-1.ph5   photon193.56k 198209
  
    lsofx86_644.91-1.ph5@cmdline  196.10k 200810
  
    Total installed size: 389.67k 399019

5.2.8 - SSL Options

Photon OS offers support for the SSL Options.

You can set the following SSL options in the repository configuration file:

• sslverify When downloading using https, this option helps to verify the SSL certificate of the server. You can set it to 0 or 1. The default is 1.

• sslcacert You can use this option to set the path to a certificate file to verify the server.

• sslclientcert You can use this option to set the path to a client certificate file.

• sslclientkey You can set this path to the client key file.

5.2.9 - Standard Syntax for tdnf Commands

The standard syntax for tdnf commands is the same as that for DNF and is as follows:

tdnf [options] <command> [<arguments>...]

You can view help information by using the following commands:

tdnf --help
tdnf -h

5.2.9.1 - tdnf Commands

autoremove [pkg-spec]: This command removes a package with its dependencies. This is similar to the erase/remove command. You can use this command to remove the packages that are no longer needed regardless of the clean_requirements_on_remove option.

autoremove without any arguments removes all automatically installed packages that are no longer required.

check: Checks for problems in installed and available packages for all enabled repositories. The command has no arguments. You can use --enablerepo and --disablerepo to control the repos used. Supported in Photon OS 2.0 (only).

check-local: This command resolves dependencies by using the local RPMs to help check RPMs for quality assurance before publishing them. To check RPMs with this command, you must create a local directory and place your RPMs in it. The command, which includes no options, takes the path to the local directory containing the RPMs as its argument. The command does not recursively parse directories. It checks the RPMs only in the directory that you specify. For example, after creating a directory named /tmp/myrpms and placing your RPMs in it, you can run the following command to check them:

tdnf check-local /tmp/myrpms
Checking all packages from: /tmp/myrpms
Found 10 packages
Check completed without issues

check-update: This command checks for updates to packages. It takes no arguments. The tdnf list updates command performs the same function. Here is an example of the check update command:

tdnf check-update
rpm-devel.x86_64 	4.11.2-8.ph1 	photon
yum.noarch      	3.4.3-3.ph1 	photon

clean: This command cleans up temporary files, data, and metadata. It takes the argument all. Example:

tdnf clean all
Cleaning repos: photon photon-extras photon-updates
Cleaning up everything

You can use this command to clean all configured repositories.

You can also use the following sub-commands or arguments to clean specific files:

metadata: This sub-command cleans up downloaded metadata from the repositories.

dbcache: This sub-command cleans up metadata generated from libsolv

packages: This sub-command removes downloaded packages from the cache.

keys: This sub-command removes downloaded keys from the cache.

expire-cache: This sub-command removes the cache expiry marker. This triggers a download of metadata on the next action that needs them.

distro-sync: This command synchronizes the machine’s RPMs with the latest version of all the packages in the repository. The following is an abridged example:

tdnf distro-sync

Upgrading:
zookeeper                             x86_64        3.4.8-2.ph1               3.38 M
yum                                   noarch        3.4.3-3.ph1               4.18 M

Total installed size: 113.01 M

Reinstalling:
zlib-devel                            x86_64        1.2.8-2.ph1             244.25 k
zlib                                  x86_64        1.2.8-2.ph1             103.93 k
yum-metadata-parser                   x86_64        1.1.4-1.ph1              57.10 k

Total installed size: 1.75 G

Obsoleting:
tftp                                  x86_64        5.2-3.ph1                32.99 k

Total installed size: 32.99 k
Is this ok [y/N]:

downgrade: This command downgrades the package that you specify as an argument to the next lower package version. The following is an example:

tdnf downgrade boost
Downgrading:
boost                                 x86_64        1.56.0-2.ph1              8.20 M
Total installed size: 8.20 M
Is this ok [y/N]:y
Downloading:
boost                                  2591470    100%
Testing transaction
Running transaction
Complete!

To downgrade to a version lower than the next one, you must specify it by name, epoch, version, and release, all properly hyphenated. The following is an example:

tdnf downgrade boost-1.56.0-2.ph1 

erase: This command removes the package that you specify as an argument.

To remove a package, run the following command:

tdnf erase pkgname

The following is an example:

tdnf erase vim
Removing:
vim                                   x86_64        7.4-4.ph1                 1.94 M
Total installed size: 1.94 M
Is this ok [y/N]:

You can also erase multiple packages:

tdnf erase docker cloud-init

When you remove a package, by default, tdnf does not remove the dependencies that are no longer used if tdnf installed them as dependencies. To remove the dependencies, modify the clean_requirements_on_remove option in the /etc/tdnf/tdnf.conf file to true, or use the autoremove command.

history: This command allows you to record every transaction (commands that install, update, or remove packages) in a database. You can roll back the transactions to a past state, or undo or redo a range of transactions.

There are five sub-commands or arguments that you can use with the history command:

history init/update: The sub-commands init or update initializes the history database. It is recommended that you use these commands right after tdnf is installed. If the database is not already initialized, any altering commands such as install or erase initializes the database.

If the database is already initialized, the commands have no effect unless an application such as an RPM command adds or removes any packages after the last recorded transaction.

history list: This command lists the history of transactions. Note that this result is similar when you use the history command without an argument or sub-command.

The following example shows the use of the command:

# tdnf history
ID   cmd line                                 date/time             +added / -removed
   1 (set)                                    Thu May 05 2022 19:14 +152 / -0
   2 -y install less                          Thu May 05 2022 19:14 +1 / -0
   3 -y install lsof                          Thu May 05 2022 19:18 +2 / -0

You can specify the following options for this sub-command:

• --info: Use this option to list a more detailed history that includes added or removed packages.
• --reverse Use this option to list the history in reverse order.
• --from <id> and --to <id>: Use this option to list a range of transactions. You can specify the transaction IDs of the range in this option.

The following example shows how to use the options:

# tdnf history --info --from 2 --to 3
ID   cmd line                                 date/time             +added / -removed
   2 -y install less                          Thu May 05 2022 19:14 +1 / -0
added: less-551-2.ph4.aarch64

   3 -y install lsof                          Thu May 05 2022 19:18 +2 / -0
added: libtirpc-1.2.6-2.ph4.aarch64, lsof-4.91-1.ph4.aarch64

history rollback –to trans_id: This command allows you to revert to a previous state. You must specify the ID of the desired state with the --to parameter.

Example:

# tdnf history rollback --to 49

Upgrading:
curl-devel                               aarch64              7.82.0-3.ph4                photon-updates       885.16k 906404
curl                                     aarch64              7.82.0-3.ph4                photon-updates       256.73k 262896
...

Total installed size:   3.52M 3688748
Is this ok [y/N]: y

Downloading:
curl-devel                              793306 100%
curl                                    148725 100%
...
Testing transaction
Running transaction
Installing/Updating: rpm-libs-4.16.1.3-9.ph4.aarch64
Installing/Updating: rpm-4.16.1.3-9.ph4.aarch64
...
Complete!

history undo –from trans_id [–to trans_id]: You can use this command to undo a transaction. The parameter --from is mandatory, and the specified transaction in the parameter is reversed. Optionally, you can specify a range with the parameter --to to reverse all the specified transactions. Note that the range you specify is inclusive. For example, if you specify the range as 2 to 4, the transactions in 2, 3, and 4 are reversed.

history redo –from trans_id [–to trans_id]: You can use this command to redo a transaction. The parameter --from is mandatory, and the specified transaction in the parameter is redone. Optionally, you can specify a range with the parameter --to to redo all the specified transactions. The range you specify in the parameters is inclusive.

NOTE

Deltas: When you make changes using history commands, the changes are resolved based on the total deltas between the start and the target states. For each range of transactions, the intermediate states are irrelevant. For example, in a range of transactions where one transaction installs a package and the last one removes the package, the final installed state of the package remains the same from start to end.

Unresolved Packages: If a package is not found, tdnf fails with an error message. For instance, when you roll back to a state before an update, the system might not find all the required installation packages in the repository. In such a case, you can enable the additional repositories to successfully revert.

Example:

The following example shows how the tdnf fails with an error message for the unavilable packages:

# tdnf history rollback --to 1
The following packages could not be resolved:

curl-libs-7.82.0-1.ph4.aarch64
rpm-libs-4.16.1.3-7.ph4.aarch64
...

The package(s) may have been moved out of the enabled repositories since the
last time they were installed. You may be able to resolve this by enabling
additional repositories.
Error(1011) : No matching packages

The following example shows how you can enable the repository to resolve the issue:

tdnf --enablerepo=photon history rollback --to 1

Downgrading:
curl-devel                               aarch64              7.82.0-1.ph4                photon               885.16k 906404
rpm-build                                aarch64              4.16.1.3-7.ph4              photon               434.00k 444418
...

Total installed size:   4.26M 4463905

Removing:
wget                                     aarch64              1.21.3-1.ph4                @System                3.02M 3168291
tdnf-test-cleanreq-required              aarch64              1.0.1-3                     @System                    0.00b 0
lsof                                     aarch64              4.91-1.ph4                  @System              202.36k 207218
libtirpc                                 aarch64              1.2.6-2.ph4                 @System              193.33k 197970
gdb                                      aarch64              10.1-2.ph4                  @System               12.60M 13214814

Total installed size:  16.01M 16788293
Is this ok [y/N]: 

Transactions outside tdnf: tdnf keeps track of the transactions it performs. However, other tools such as rpm can also add or remove packages. While performing the next transaction, if tdnf detects transactions performed by other tools, it records such transactions as pseudo transactions.

Example:

# tdnf history --info --from 49 --to 49
ID   cmd line                                 date/time.            +added / -removed
  49 (unknown)                                Thu May 05 2022 23:38 +1 / -0
added: gdb-10.1-2.ph4.aarch64

Dependencies: The undo and redo actions might need to install additional depedencies apart from the previously existing packages. For example, when you redo a transaction that installs a single package which was earlier removed along with its depedencies, the command also attempts to install the dependecies.

Note that this is not an issue for the rollback command because the entire set of packages is restored assuming that the dependecies are also satisfied at the state.

info: This command displays information about packages. It can take the name of a package. Or it can take one of the following arguments: all, available, installed, extras, obsoletes, recent, upgrades. The following are examples:

tdnf info ruby
tdnf info obsoletes
tdnf info upgrades

install: This command takes the name of a package as its argument. It then installs the package and its dependencies.

To install a package, run the following command:

tdnf install pkgname

The following are examples:

tdnf install kubernetes

You can also install multiple packages:

tdnf install python-curses lsof audit gettext chkconfig ntsysv bindutils 
	 wget gawk irqbalance lvm2 cifs-utils c-ares distrib-compat

list: This command lists the packages of the package that you specify as the argument. The command can take one of the following arguments: all, available, installed, extras, obsoletes, recent, upgrades.

tdnf list updates

The list of packages might be long. To more easily view it, you can concatenate it into a text file, and then open the text file in a text editor:

tdnf list all > pkgs.txt
vi pkgs.txt

To list enabled repositories, run the following command:

tdnf repolist

makecache: This command updates the cached binary metadata for all known repositories. The following is an example:

tdnf makecache
Refreshing metadata for: 'VMware Lightwave 1.0(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)Updates'
Refreshing metadata for: 'VMware Photon Extras 1.0(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)'
Metadata cache created.

mark install|remove pkg_spec: Mark one or more packages as auto installed (remove) or unmark as auto installed (install), which means it is user-installed. This is used to determine if this package gets removed on autoinstall.

provides: This command finds the packages that provide the package that you supply as an argument. The following is an example:

tdnf provides docker
docker-1.11.0-1.ph1.x86_64 : Docker
Repo     : photon
docker-1.11.0-1.ph1.x86_64 : Docker
Repo     : @System

reinstall: This command reinstalls the packages that you specify. If some packages are unavailable or not installed, the command fails. The following is an example:

tdnf reinstall docker kubernetes

Reinstalling:
kubernetes                            x86_64        1.1.8-1.ph1             152.95 M
docker                                x86_64        1.11.0-1.ph1             57.20 M

Total installed size: 210.15 M

repoquery [args]: The repoquery command allows you to query packages from the repositories and installed packages with different criteria and output options. It can take multiple package specifications as arguments.

Example:

$ tdnf repoquery vim 
vim-8.2.4925-1.ph4.aarch64
vim-8.2.1361-1.ph4.aarch64

$ tdnf repoquery vim*
vim-8.2.4925-1.ph4.aarch64
vim-8.2.1361-1.ph4.aarch64
vim-extra-8.2.4925-1.ph4.aarch64
vim-extra-8.2.1361-1.ph4.aarch64

$ tdnf repoquery --installed vim
vim-8.2.4925-1.ph4.aarch64

$ tdnf repoquery --requires vim
ld-linux-aarch64.so.1()(64bit)
ld-linux-aarch64.so.1(GLIBC_2.17)(64bit)
libc.so.6(GLIBC_2.17)(64bit)
...

The following groups of options are available for repoquery:

• select option: Use this option to filter the list of packages. You can use the following parameters with the select option:

  • --available: Use this parameter to show available packages in the repositories.

  • --duplicates: Use this parameter to show duplicate installed packages.

  • --extras: Use this parameter to show the packages that are installed but not in any repositories.

  • --file file: Use this parameter to show packages that contain the specified files.

  • --installed: Use this parameter to show the installed packages.

  • --userinstalled: Use this parameter to show the user-installed packages.

  • --whatdepends, --whatenhances, --whatobsoletes, --whatprovides, --whatrecommends, whatrequires, --whatsuggests, --whatsupplements capability: Use these parameters to show packages that have the specified dependency on capability.

    Example:

    $ tdnf repoquery --whatrequires vim
    minimal-0.1-6.ph4.aarch64
    vim-extra-8.2.4925-1.ph4.aarch64
    minimal-0.1-4.ph4.aarch64
    

• query option: Use this option to control what you want the command to display. The query option lists the selected packages by default. You can use the following parameters to get the required output:

  • --list: Use this parameter to list all files of the selected packages.
  • --depends, --enhances, --obsoletes, --provides, --recommends, requires, requires-pre, --suggests, --supplements: Use these parameters to list specified dependencies.

reoposync: This command synchronizes a remote repository with a local one. By default, all packages are downloaded to a local directory unless they already exist. Optionally, metadata is also downloaded.

You can use the following options with the command:

--delete: Use this option to remove old packages that are not part of the repository any more.

--download-metadata: Use this option to download the metadata. After you download the the metadata, you can use the directory as a repository.

--gpgcheck: Use this option to check the gpg signature. If invalid, the package is deleted.

--norepopath: When you use this option, no subdirectory with the repo name is created. This option is only valid if you configure more than one repository.

--urls: When you use this option, instead of downloading, the URLs of all files are printed to stdout.

--download-path: Use this option to specify the download path. By default, files are downloaded relative to the current directory.

--metadata-path: Use this option to specify the download path. You can download metadata to a different directory.

--arch: Use this option to download specific architectures. You can use this option repeatedly.

--source: Use this option to download only source packages. This option is similar to --arch src. Note that this option is incompatible with the --arch option.

--newest-only: Use this option to download only the latest versions of the repository.

remove: This command removes a package. When removing a package, tdnf by default also removes dependencies that are no longer used if they were was installed by tdnf as a dependency without being explicitly requested by a user. You can modify the dependency removal by changing the clean_requirements_on_remove option in /etc/tdnf/tdnf.conf to false.

tdnf remove packagename

search: This command searches for the attributes of packages. The argument can be the names of packages. The following is an example:

tdnf search docker kubernetes
docker : Docker
docker : Docker
docker-debuginfo : Debug information for package docker
docker : Docker
kubernetes : Kubernetes cluster management
kubernetes : Kubernetes cluster management
kubernetes-debuginfo : Debug information for package kubernetes
kubernetes : Kubernetes cluster management

The argument of the search command can also be a keyword or a combination of keywords and packages:

tdnf search terminal bash
rubygem-terminal-table : Simple, feature rich ascii table generation library
ncurses : Libraries for terminal handling of character screens
mingetty : A minimal getty program for virtual terminals
ncurses : Libraries for terminal handling of character screens
ncurses : Libraries for terminal handling of character screens
bash : Bourne-Again SHell
bash-lang : Additional language files for bash
bash-lang : Additional language files for bash
bash : Bourne-Again SHell
bash-debuginfo : Debug information for package bash
bash : Bourne-Again SHell
bash-lang : Additional language files for bash

updateinfo: This command displays security advisories about packages. The following is an example:

tdnf updateinfo info

Name : unzip-6.0-15.ph3.x86_64.rpm
Update ID : patch:PHSA-2020-3.0-0083
Type : Security
Updated : Fri Apr 24 01:15:03 2020
Needs Reboot: 0
Description : Security fixes for {'CVE-2018-1000035'}
Name : runc-1.0.0.rc9-3.ph3.x86_64.rpm
Update ID : patch:PHSA-2020-3.0-0102
Type : Security
Updated : Tue Jun  9 06:01:28 2020
Needs Reboot: 0
Description : Security fixes for {'CVE-2019-19921'}
Name : ruby-2.5.8-2.ph3.x86_64.rpm
Update ID : patch:PHSA-2020-3.0-0163
Type : Security
Updated : Thu Nov 19 17:21:29 2020
Needs Reboot: 0

upgrade: This command upgrades the package or packages that you specify to an available higher version that tdnf can resolve. If the package is already the latest version, the command returns Nothing to do. The following is an example:

tdnf upgrade boost

Upgrading:
boost                                 x86_64        1.60.0-1.ph1              8.11 M

Total installed size: 8.11 M
Is this ok [y/N]:y

Downloading:
boost                                  2785950    100%
Testing transaction
Running transaction

Complete!

You can also run the upgrade command with the refresh option to update the cached metadata with the latest information from the repositories. The following example refreshes the metadata and then checks for a new version of tdnf but does not find one, so tdnf takes no action:

tdnf upgrade tdnf --refresh
Refreshing metadata for: 'VMware Lightwave 1.0(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)Updates'
Refreshing metadata for: 'VMware Photon Extras 1.0(x86_64)'
Refreshing metadata for: 'VMware Photon Linux 1.0(x86_64)'
Nothing to do.

upgrade-to: This command upgrades to the version of the package that you specify. The following is an example:

tdnf upgrade-to ruby2.3

The commands and options of tdnf are a subset of those of dnf. For more help with tdnf commands, see the DNF documentation.

5.2.9.2 - tdnf Command Options

You can add the following options to tdnf commands. If the option to override a configuration is unavailable in a command, you can add it to the /etc/tdnf/tdnf.conf configuration file.

The following is an example that adds the short form of the assumeyes option to the install command:

tdnf -y install gcc
Upgrading:
gcc 	x86_64	5.3.0-1.ph1 	91.35 M

The following is an example for the downloadonly option with the install command:

tdnf install --downloadonly less
    
Installing:
    
lessx86_64551-2.ph4 photon234.35k 239976
       
Total installed size: 234.35k 239976
  
tdnf will only download packages needed for the transaction
   
Is this ok [y/N]: y

Downloading:
   
less117650   100%
    
Complete!
   
Packages have been downloaded to cache.

The following is an example for the downloaddir=dir option with the install command:

tdnf install --downloadonly --downloaddir=/tmp less
 
Installing:

lessx86_64551-2.ph4 photon234.35k 239976
        
Total installed size: 234.35k 239976

tdnf will only download packages needed for the transaction

Is this ok [y/N]: y

Downloading:

less117650   100%

    
Complete!

Packages have been downloaded to /tmp.

root [ /build/build ]# ls -l /tmp/less-551-2.ph4.x86_64.rpm 

-rw-r--r-- 1 root root 117650 Feb 22 18:43 /tmp/less-551-2.ph4.x86_64.rpm

5.2.10 - Configuration Options

You can use the configuration file to set and modify the tdnf configuration. The tdnf configuration file is located in the following directory: /etc/tdnf/tdnf.conf

The following table lists the configuration options that you can set in the tdnf configuration file:

Configuration in sub-directories

There are other configurations that you can set in the subdirectories of /etc/tdnf.

Package Locks

You can configure to lock packages in the following directory: /etc/tdnf/locks.d. You cannot remove, upgrade, or downgrade a locked package. You can create multiple files with multiple lines. Each line can contain a package name.

Note: A locked package is considered locked only after it is installed. If a package is not installed, the features of a locked package do not apply.

Minimal Versions

You can configure a minimum version for a package in the following directory: /etc/tdnf/minversions.d. You can create multiple files with multiple lines in them. Each line can contain a package name. The package name must include a version number, and an = symbol must separate the name and version number.

Example:

# cat /etc/tdnf/minversions.d/rpm.conf 
rpm-libs=4.16.1.3-1

You can also configure this option in the main configuration file as mentioned in the table previously.

5.3 - Managing Services with 'systemd'

Photon OS manages services with systemd. By using systemd, Photon OS adopts a contemporary Linux standard to bootstrap the user space and concurrently start services. This is an architecture that differs from traditional Linux systems such as SUSE Linux Enterprise Server.

A traditional Linux system contains an initialization system called SysVinit. With SLES 11, for instance, the SysVinit-style init programs control how the system starts up and shuts down. Init implements system runlevels. A SysVinit runlevel defines a state in which a process or service runs.

In contrast to a SysVinit system, systemd defines no such runlevels. Instead, systemd uses a dependency tree of targets to determine which services to start when. Combined with the declarative nature of systemd commands, systemd targets reduce the amount of code needed to run a command, leaving you with code that is easier to maintain and probably faster to execute. For an overview of systemd, see systemd System and Service Manager and the man page for systemd.

On Photon OS, you must manage services with systemd and systemctl, its command-line utility for inspecting and controlling the system, and not the deprecated commands of init.d.

For more information, see the index of all the systemd man pages, including systemctl, at https://www.freedesktop.org/software/systemd/man/

5.3.1 - Viewing Services

To view a description of all the loaded and active units, run the systemctl command without any options or arguments:

systemctl

To see all the loaded, active, and inactive units and their description, run the following command:

systemctl --all

To see all the unit files and their current status but no description, run thie following command:

systemctl list-unit-files

The grep command filters the services by a search term, a helpful tactic to recall the exact name of a unit file without looking through a long list of names. Example:

systemctl list-unit-files | grep network
org.freedesktop.network1.busname           static
dbus-org.freedesktop.network1.service      enabled
systemd-networkd-wait-online.service       enabled
systemd-networkd.service                   enabled
systemd-networkd.socket                    enabled
network-online.target                      static
network-pre.target                         static
network.target                             static

5.3.2 - Controlling Services

To control services on Photon OS, use systemctl command.

For example, instead of running the /etc/init.d/ssh script to stop and start the OpenSSH server on a init.d-based Linux system, run the following systemctl commands on Photon OS:

systemctl stop sshd
systemctl start sshd

The systemctl tool includes a range of commands and options for inspecting and controlling the state of systemd and the service manager. For more information, see the systemctl man page.

5.3.3 - Creating a Startup Service

Use systemd to create a startup service.

The following example shows you how to create a systemd startup service that changes the maximum transmission unit (MTU) of the default Ethernet connection, eth0.

1. Concatenate the following block of code into a file:

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=/usr/sbin/ifconfig eth0 mtu 1460 up
	Type=oneshot

	[Install]
	WantedBy=multi-user.target
EOF

1. Set the service to auto-start when the system boots:

cd /lib/systemd/system/multi-user.target.wants/
	ln -s ../eth0.service eth0.service

5.3.4 - Disabling the Photon OS httpd.service

If your application or appliance includes its own HTTP server, you must turn off and disable the HTTP server that comes with Photon OS so that it does not conflict with your own HTTP server.

To stop it and disable it, run the following commands as root:

systemctl stop httpd.service
systemctl disable httpd.service

5.3.5 - Installing Sendmail

Before you install Sendmail, you should set the fully qualified domain name (FQDN) of your Photon OS machine.

By default, Sendmail is not installed with either the minimal or full version of Photon OS. When you install Sendmail, it provides Photon OS with a systemd service file that typically enables Sendmail. If the service is not enabled after installation, you must enable it.

Sendmail resides in the Photon extras repository. You can install it with tdnf after setting the machine’s FQDN.

Procedure

1. Check whether the FQDN of the machine is set by running the hostnamectl status command:

hostnamectl status
       Static hostname: photon-d9ee400e194e
             Icon name: computer-vm
               Chassis: vm
            Machine ID: a53b414142f944319bd0c8df6d811f36
               Boot ID: 1f75baca8cc249f79c3794978bd82977
        Virtualization: vmware
      Operating System: VMware Photon/Linux
                Kernel: Linux 4.4.8
          Architecture: x86-64

2. If the machine does not have an FQDN, set one by running hostnamectl set-hostname new-name, replacing new-name with the FQDN that you want. For example:

   hostnamectl set-hostname photon-d9ee400e194e.corp.example.com
   

   The hostnamectl status command now shows that the machine has an FQDN:

   root@photon-d9ee400e194e [ ~ ]# hostnamectl status
       Static hostname: photon-d9ee400e194e.corp.example.com
               Icon name: computer-vm
               Chassis: vm
               Machine ID: a53b414142f944319bd0c8df6d811f36
               Boot ID: 1f75baca8cc249f79c3794978bd82977
           Virtualization: vmware
       Operating System: VMware Photon/Linux
                   Kernel: Linux 4.4.8
           Architecture: x86-64
   

3. Install Sendmail:

   tdnf install sendmail
   

4. Verify if Sendmail is enabled:

   systemctl status sendmail
   

5. Enable Sendmail if it is disabled and then start it:

   systemctl enable sendmail
   systemctl start sendmail
   

5.3.6 - Auditing System Events with auditd

To manage security on Photon OS, the Linux auditing service auditd is enabled and active by default on the full version of Photon OS.

The following command shows the security status:

systemctl status auditd
	* auditd.service - Security Auditing Service
	   Loaded: loaded (/usr/lib/systemd/system/auditd.service; enabled; vendor preset: enabled)
	   Active: active (running) since Fri 2016-04-29 15:08:50 UTC; 1 months 9 days ago
	 Main PID: 250 (auditd)
	   CGroup: /system.slice/auditd.service
	           `-250 /sbin/auditd -n

To help improve security, the auditd service can monitor file changes, system calls, executed commands, authentication events, and network access. After you implement an audit rule to monitor an event, the aureport tool generates reports to display information about the events.

You can use the auditctl utility to set a rule that monitors the sudoers file for changes:

auditctl -w /etc/sudoers -p wa -k sudoers_changes

This rule specifies that the auditd service must watch (-w) the /etc/sudoers file to log permissions changes (-p) to the write access (w) or attributes (a) of the file and to identify them in logs as sudoers_changes. The auditing logs appear in /var/log/audit/audit.log. You can list the auditing rules as follows:

auditctl -l
-w /etc/sudoers -p wa -k sudoers_changes

For more information on the Linux Audit Daemon, see the auditd man page:

man auditd

For more information on setting auditing rules and options, see the auditctl man page:

man auditctl

For more information on viewing reports on audited events, see the aureport man page:

man aureport

5.3.7 - Analyzing systemd Logs with journalctl

The journalctl tool queries the contents of the systemd journal.

The following command displays the messages that systemd generated the last time the machine started:

journalctl -b

The following command reveals the messages for the systemd service unit specified by the -u option:

journalctl -u auditd

In the above example, auditd is the system service unit.

For more information, see the journalctl man page by running the following command on Photon OS:

man journalctl

5.3.8 - Migrating Scripts to systemd

Although systemd maintains compatibility with init.d scripts, as a best practice, you must adapt the scripts that you want to run on Photon OS to systemd to avoid potential problems.

Such a conversion standardizes the scripts, reduces the footprint of your code, makes the scripts easier to read and maintain, and improves their robustness on a systemd system.

5.4 - Configure Wireless Networking

You can configure wireless networking in Photon OS. Connect to an open network or a WPA2 protected network using wpa_cli and configure systemd-networkd to assign an IP address to the network.

• Connect using wpa_cli
• Assign IP address to network

Connect Using wpa_cli

When you connect using wpa_cli, you can scan for available networks and associate the network with a network ID.

Perform the following steps:

1. Ensure that the wpa_supplicant service is running on the WLAN interface:

   systemctl status wpa_supplicant@<wlan-interface>.service

2. Connect to wpa_cli:

   wpa_cli -i wlan0

3. Scan for available networks:

   scan

4. To see the list of networks, use the following command:

   scan_results

5. Add the network:

   add_network

   This command returns a network ID.

6. Associate the network with the network ID.

   set_network <network ID> ssid “<ssid-name>”

7. For a WPA2 network, set the passphrase:

   set_network <network ID> psk “<passphrase>”

8. Enable the network:

   enable_network <network ID>

9. Save the configuration file:

   save_config

   To exit the wpa_cli, type ‘quit`.

Assign IP Address To Network

Configure systemd-networkd to assign IP address to network. Perform the following steps:

1. Create a /etc/systemd/network/98-dhcp-wlan.network file with the following contents:

   [Match]
   Name=wlan*
   [Network]
   DHCP=yes
   IPv6AcceptRA=no
   

2. Restart systemd-networkd using:

   systemctl restart systemd-networkd

5.5 - Managing the Network Configuration

The network service, which is enabled by default, starts when the system boots.

5.5.1 - Commands to Manage Network Service

You manage the network service by using systemd commands, such as systemd-networkd, systemd-resolvd, and networkctl.

To check the status of the network service, run the following command:

	systemctl status systemd-networkd

Output

	* systemd-networkd.service - Network Service
	   Loaded: loaded (/usr/lib/systemd/system/systemd-networkd.service; enabled; vendor preset: enabled)
	   Active: active (running) since Fri 2016-04-29 15:08:51 UTC; 6 days ago
	     Docs: man:systemd-networkd.service(8)
	 Main PID: 291 (systemd-network)
	   Status: "Processing requests..."
	   CGroup: /system.slice/systemd-networkd.service
	           `-291 /lib/systemd/systemd-networkd

Because Photon OS relies on systemd to manage services, you must use the systemd suite of commands and not the deprecated init.d commands or other deprecated commands to manage networking.

5.5.2 - Using the Network Configuration Manager

The network-config-manager nmctl allows to configure and introspect the state of the network links as seen by systemd-networkd. nmctl can be used to query and configure links for Address, Routes, Gateways and also hostname, DNS, NTP or Domain. nmctl uses sd-bus, libudev APIs to interact with systemd, systemd-networkd, systemd-resolved, systemd-hostnamed, and systemd-timesyncd via dbus. nmctl uses networkd verbs to explain output. nmctl can generate configurations for required network links from YAML description. It also understands kernel command line specified in dracut network configuration format and can generate systemd-networkd configuration while the system boots and will persist between reboots.

Note: See systemd.network for more information.

nmctl is used to configure:

• Static IPv4 and IPv6 Address, Routes, Gateway
• DHCP type (IPv4/IPv6), DHCP4 Client Identifier, UseMTU/UseDNS/UseDomains/UseNTP/UseRoutes. LLDP, Link Local Addressing, IPv4LLRoute, LLMNR
• DNS, Domains and NTP
• Link MAC, MTU
• Create netdevs, vlan, vxlan, bridge, bond, veth, macvlan/macvtap, ipvlap/ipvtap, veth, tunnels(ipip, sit, gre, sit, vti), wireguard
• Hostname
• Can delete and view nftables table, chains and rules.

You can use nmctl to generate network configurations from the following:

• YAML file: nmctl can generate configurations for required network links from YAML description. Configuration written to disk under /etc/systemd/network will persist between reboots. When network-config-manager-yaml-generator.service is enabled it reads YAML files from /etc/network-config-manager/yaml and generates systemd-networkd configuration files.

  nmctl uses similar format as defined by different YAML format.

  nmctl can generate WPA Supplicant configuration from YAML file. When a YAML file with wifi configuration is found, it generates a configuration file found in /etc/network-config-manager/wpa_supplicant_photon_os.conf which is understood by wpa_supplicant.

• Dracut kernel command line network configuration: nmctl understands kernel command line specified in dracut’s network configuration format and can generate systemd-networkd’s configuration while the system boots and will persist between reboots.

Network
       ip={dhcp|on|any|dhcp6|auto6}
           dhcp|on|any: get ip from dhcp server from all links. If root=dhcp, loop
           sequentially through all links (eth0, eth1, ...) and use the first with a valid
           DHCP root-path.

           auto6: IPv6 autoconfiguration

           dhcp6: IPv6 DHCP

       ip=<link>:{dhcp|on|any|dhcp6|auto6}
           dhcp|on|any|dhcp6: get ip from dhcp server on a specific link

           auto6: do IPv6 autoconfiguration

           This parameter can be specified multiple times.

       ip=<client-IP>:[ <server-id>]:<gateway-IP>:<netmask>:<client_hostname>:<link>:{none|off}
           explicit network configuration.

       ifname=<link>:<MAC>
           Assign network device name <link> (ie eth0) to the NIC with MAC <MAC>. Note
           letters in the MAC-address must be lowercase!  Note: If you use this option you must
           specify an ifname= argument for all links used in ip= or fcoe= arguments.  This
           parameter can be specified multiple times.

       nameserver=<IP>[nameserver=<IP> ...]
           specify nameserver(s) to use

      cat /proc/cmdline
       BOOT_IMAGE=/boot/vmlinuz-4.19.52-2.ph3-esx root=PARTUUID=ebf01b6d-7e9c-4345-93f4-122f44eb2726
       init=/lib/systemd/systemd rcupdate.rcu_expedited=1 rw systemd.show_status=0 quiet noreplace-smp
       cpu_init_udelay=0 net.ifnames=0 plymouth.enable=0 systemd.legacy_systemd_cgroup_controller=yes
       ip=dhcp

network-config-manager-generator.service is a oneshot type systemd service unit which runs while the system boots. It parses the kernel command line and generates networkd config in /etc/systemd/network:

systemctl enable network-config-manager-generator.service

It creates symlink /etc/systemd/system/network.target.wants/network-config-manager-generator.service → /usr/lib/systemd/system/network-config-manager-generator.service.

5.5.3 - Use 'ip' and 'ss' Commands

Use the ip and ss commands to view a list of network interfaces and information for IP addresses.

Although the ifconfig command and the netstat command work on Photon OS, VMware recommends that you use the ip or ss commands. The ipconfig and netstat commands are deprecated.

For example, to display a list of network interfaces, run the ss command instead of netstat. To display information for IP addresses, run the ip addr command instead of ifconfig -a.

Examples are as follows:

USE THIS IPROUTE COMMAND 	INSTEAD OF THIS NET-TOOL COMMAND
ip addr 					ifconfig -a
ss 							netstat
ip route 					route
ip maddr 					netstat -g
ip link set eth0 up 		ifconfig eth0 up
ip -s neigh					arp -v
ip link set eth0 mtu 9000	ifconfig eth0 mtu 9000

Using the ip route version of a command instead of the net-tools version often provides more complete and accurate information on Photon OS. Examples are as follows:

ip neigh
198.51.100.2 dev eth0 lladdr 00:50:56:e2:02:0f STALE
198.51.100.254 dev eth0 lladdr 00:50:56:e7:13:d9 STALE
198.51.100.1 dev eth0 lladdr 00:50:56:c0:00:08 DELAY

arp -a
? (198.51.100.2) at 00:50:56:e2:02:0f [ether] on eth0
? (198.51.100.254) at 00:50:56:e7:13:d9 [ether] on eth0
? (198.51.100.1) at 00:50:56:c0:00:08 [ether] on eth0

5.5.4 - Configuring Network Interfaces

Network configuration files for systemd-networkd reside in /etc/systemd/network and /usr/lib/systemd/network. Example:

root@photon-rc [ ~ ]# ls /etc/systemd/network/
99-dhcp-en.network

By default, when Photon OS starts, it creates a DHCP network configuration file, or rule, which appears in /etc/systemd/network, the highest priority directory for network configuration files with the lowest priority filename:

cat /etc/systemd/network/99-dhcp-en.network
[Match]
Name=e*

[Network]
DHCP=yes

Network configuration files can also appear in the system network directory, /usr/lib/systemd/network, as the results of the following search illustrate:

root@photon-rc [ ~ ]# updatedb
root@photon-rc [ ~ ]# locate systemd/network
/etc/systemd/network
/etc/systemd/network/99-dhcp-en.network
/usr/lib/systemd/network
/usr/lib/systemd/network/80-container-host0.network
/usr/lib/systemd/network/80-container-ve.network
/usr/lib/systemd/network/99-default.link
root@photon-rc [ ~ ]#

In the above search, the /usr/lib/systemd/network directory contains several network configuration files. Photon OS applies the configuration files in lexicographical order specified by the file names without regard for the network configuration directory in which the file resides unless the file name is the same. Photon OS processes files with identical names by giving precedence to files in the /etc directory over the other directory. Thus, the settings in /etc/systemd/network override those in /usr/lib/systemd/network. Once Photon OS matches an interface in a file, Photon OS ignores the interface if it appears in files processed later in the lexicographical order.

Each .network file contains a matching rule and a configuration that Photon OS applies when a device matches the rule. Set the matching rule and the configuration as sections containing vertical sets of key-value pairs according to the information in systemd network configuration.

To configure Photon OS to handle a networking use case, such as setting a static IP address or adding a name server, create a configuration file with a .network extension and place it in the /etc/systemd/network directory.

After you create a network configuration file with a .network extension, you must run the chmod command to set the new file’s mode bits to 644.

Example:

chown systemd-network:systemd-network 10-static-en.network

For Photon OS to apply the new configuration, you must restart the systemd-networkd service by running the following command:

systemctl restart systemd-networkd

For information about network configuration files, their processing order, and their matching rules, sections, and keys, see https://www.freedesktop.org/software/systemd/man/systemd.network.html.

For information about creating virtual network device files (.netdev), see https://www.freedesktop.org/software/systemd/man/systemd.netdev.html.

5.5.5 - Setting a Static IP Address

Before you set a static IP address, obtain the name of your Ethernet link by running the following command:

networkctl
IDX LINK             TYPE               OPERATIONAL SETUP
	1 lo               loopback           carrier     unmanaged
	2 eth0             ether              routable    configured

In the results of the command, you can see the name of an Ethernet link, eth0.

To create a network configuration file that systemd-networkd uses to establish a static IP address for the eth0 network interface, execute the following command as root:

cat > /etc/systemd/network/10-static-en.network << "EOF"

[Match]
Name=eth0

[Network]
Address=198.51.0.2/24
Gateway=198.51.0.1
EOF

Change the new file’s mode bits by running the chmod command:

chmod 644 10-static-en.network

Apply the configuration by running either the first or the second step:

1. systemctl restart systemd-networkd

2. networkctl reload networkctl reconfigure *interface_name/index_number*

Note: The advantage of using reload and reconfigure is that the settings of other interfaces are not disturbed and only the settings of the specific interface are reloaded and reconfigured.

For more information, see the man page for systemd-networkd: man systemd.network

5.5.6 - Turning Off DHCP

By default, when Photon OS first starts, it creates a DHCP network configuration file or rule, which appears in /etc/systemd/network, the highest priority directory for network configuration files with the lowest priority filename:

cat /etc/systemd/network/99-dhcp-en.network
[Match]
Name=e*

[Network]
DHCP=yes

To turn off DHCP for all Ethernet interfaces, change the value of DHCP from yes to no, save the changes, and then restart the systemd-networkd service:

	systemctl restart systemd-networkd

Or you can reload and reconfigure the settings:

networkctl reload
networkctl reconfigure <interface_name>/<index_number>`

If you create a configuration file with a higher priority filename (e.g. 10-static-en.network), it is not necessary but still recommended to turn off DHCP.

You can also check the status of a specific interface:

networkctl status <interface_name>/<index_number>

(eth0 is an example)

❯ networkctl status eth0
● 2: eth0
                     Link File: /usr/lib/systemd/network/99-default.link
                  Network File: /etc/systemd/network/50-dhcp-en.network
                         State: routable (configured)
                  Online state: online
                          Type: ether
                          Path: pci-0000:0b:00.0
                        Driver: vmxnet3
                        Vendor: VMware
                         Model: VMXNET3 Ethernet Controller
             Alternative Names: eno1
                                enp11s0
                                ens192
              Hardware Address: 00:50:56:ba:43:98 (VMware, Inc.)
                           MTU: 1500 (min: 60, max: 9000)
                         QDisc: fq_codel
  IPv6 Address Generation Mode: eui64
      Number of Queues (Tx/Rx): 1/1
              Auto negotiation: no
                         Speed: 10Gbps
                        Duplex: full
                          Port: tp
                       Address: 192.168.1.8/24 (DHCPv4 via 192.168.1.1)
                                fe80::250:56ff:feba:4398
                       Gateway: 192.168.1.1
                           DNS: 192.168.1.1
                                192.168.1.2
                                192.168.1.3
                           NTP: 192.168.1.1
                                192.168.1.2
                                192.168.1.3
                                192.168.1.4
             Activation Policy: up
           Required For Online: yes
               DHCP4 Client ID: IAID:0xb6220feb/DUID

May 04 10:37:14 photon systemd-networkd[625]: eth0: found matching network '/etc/systemd/network/50-dhcp-en.network', based on potentially unpredictable interface name.
May 04 10:37:14 photon systemd-networkd[625]: eth0: Configuring with /etc/systemd/network/50-dhcp-en.network.
May 04 10:37:14 photon systemd-networkd[625]: eth0: Link UP
May 04 10:37:14 photon systemd-networkd[625]: eth0: Gained carrier
May 04 10:37:14 photon systemd-networkd[625]: eth0: found matching network '/etc/systemd/network/50-dhcp-en.network', based on potentially unpredictable interface name.

5.5.7 - Adding a DNS Server

Photon OS uses systemd-resolved to resolve domain names, IP addresses, and network names for local applications. The systemd-resolved daemon automatically creates and maintains the /etc/resolv.conf file, into which systemd-resolved places the IP address of the DNS server. You must not modify the /etc/resolv.conf file.

Note: If you want to implement a local resolver like bind instead of systemd-resolved, stop the systemd-resolved service and disable it.

If you open the default /etc/resolv.conf file after you deploy Photon OS, it looks like this:

root@photon-rc [ ~ ]# cat /etc/resolv.conf
# This file is managed by systemd-resolved(8). Do not edit.
#
# Third party programs must not access this file directly, but
# only through the symlink at /etc/resolv.conf. To manage
# resolv.conf(5) in a different way, replace the symlink by a
# static file or a different symlink.

nameserver 198.51.100.2

To add a DNS server, insert a DNS key into the Network section of the static network configuration file, for example, /etc/systemd/network/10-eth0-static.network and set it to the IP address of your DNS server:

[Match]
Name=e*

[Network]
Address=198.51.0.2/24
Gateway=198.51.0.1
DNS=198.51.0.1

Note: To apply the changes made to /etc/systemd/network/*.network files, perform the following:

• Restart systemd-networkd and systemd-resolved services by running the following commands:

  • systemctl restart systemd-networkd
  • systemctl restart systemd-resolved

• Or you can reload and reconfigure the settings by running the following commands: networkctl reload networkctl reconfigure *interface_name/index_number*

Note: The advantage of using reload and reconfigure is that the settings of other interfaces are not disturbed and only the settings of the specific interface are reloaded and reconfigured.

If your machine is working with DHCP, you can add a DNS server by modifying the /etc/systemd/resolved.conf--a method.

For more information, see https://www.freedesktop.org/software/systemd/man/resolved.conf.html.

You can optionally activate the local DNS stub resolver of systemd-resolved by adding dns and resolve to the /etc/nsswitch.conf file. To do so, make a backup copy of the /etc/nsswitch.conf file and then execute the following command as root:

sed -i 's/^hosts.*$/hosts: files resolve dns/' /etc/nsswitch.conf

For more information about the systemd-resolved service, see https://www.freedesktop.org/software/systemd/man/systemd-resolved.service.html.

5.5.8 - Setting Up Networking for Multiple NICs

If your machine contains multiple NICs, it is recommend that you create a .network configuration file for each network interface. The following scenario demonstrates how to set one wired network interface to use a static IP address and another wired network interface to use a dynamic IP address obtained through DHCP.

Note: The following configurations are examples and you must change the IP addresses and other information to match your network and requirements.

First, create the .network file for the static Ethernet connection in /etc/systemd/network. A best practice is to match the exact name of the network interface, which is eth0 in this example. This example file also includes a DNS server for the static IP address. As a result, the configuration sets the UseDNS key to false in the DHCP column so that Photon OS ignores the DHCP server for DNS for this interface.

cat > /etc/systemd/network/10-eth0-static-en.network << "EOF"
[Match]
Name=eth0

[Network]
Address=10.137.20.11/19
Gateway=10.137.23.253
DNS=10.132.71.1

[DHCP]
UseDNS=false
EOF

Second, create the .network file for the second network interface, which is eth1 in this example. This configuration file sets the eth1 interface to an IP address from DHCP and sets DHCP as the source for DNS lookups. Setting the DHCP key to yes acquires an IP address for IPv4 and IPv6. To acquire an IP address for IPv4 only, set the DHCP key to ipv4.

cat > /etc/systemd/network/50-eth1-dhcp-en.network << "EOF"

[Match]
Name=eth1

[Network]
DHCP=yes  

[DHCP]
UseDNS=true
EOF

How to configure two gateways for two different NIC ?

This is an IP routing policy feature of kernel and is supported by systemd-networkd. You have to add two routes. One is for the subnet so that the IP address can find its gateway. The other route is for specifying the default gateway for that interface. Finally, we add policy route rules for that IP address that we want to use that table. This will not only ensure that the IP address you are trying to communicate with on that one interface can respond properly, but it will also ensure that you do not route information between subnets.

[Match]
Name=eth2
 
[Network]
Address=192.168.60.70/24
DHCP=no
 
[Route]
PreferredSource=192.168.60.70
Destination=192.168.60.0/24
Table=10
 
 
[Route]
Gateway=192.168.60.1
Table=10
 
[RoutingPolicyRule]
Table=10
To=192.168.60.70/24
 
[RoutingPolicyRule]
Table=10
From=192.168.60.70/24

5.5.8.1 - Combining DHCP and Static IP Addresses with IPv4 and IPv6

You can combine DHCP and static IP addresses with both IPv4 and IPv6.

Examples

The following example shows how to use DHCP to allocate both IPv4 and IPv6 addresses:

[Network]
DHCP=yes

The following example shows how to use DHCP to allocate only IPv4 addresses:

[Network]
DHCP=ipv4

The following example shows how to use DHCP to allocate only IPv6 addresses:

[Network]
DHCP=ipv6

The following example shows how to use DHCP for IPv4 addresses and static IP addresses for IPv6 addresses:

[Network]
DHCP=ipv4
Address=fd00::1/48
Gateway=fd00::252

The following example shows how to use DHCP for IPv6 addresses and static IP addresses for IPv4:

[Network]
DHCP=ipv6
Address=10.10.10.1/24
Gateway=10.10.10.253

The following example shows how to use static IP addresses for both IPv4 and IPv6:

[Network]
DHCP=ipv6
Address=10.10.10.1/24
Gateway=10.10.10.253
Address=fd00::1/48
Gateway=fd00::252

5.5.9 - Clearing the Machine ID of a Cloned Instance for DHCP

Photon OS uses the contents of /etc/machine-id to determine the DHCP unique identifier (duid) that is used for DHCP requests. If you use a Photon OS instance as the base system for cloning, to create additional Photon OS instances, you must clear the machine-id with this command:

echo -n > /etc/machine-id

When the value is cleared, machine-id can be regenerated by calling systemd-machine-id-setup.

systemd-machine-id-setup

This command initializes the machine ID stored in /etc/machine-id during installation. For more information on this command, see https://www.freedesktop.org/software/systemd/man/systemd-machine-id-setup.html.

5.5.10 - Using Predictable Network Interface Names

When you run Photon OS on a virtual machine or a bare-metal machine, the Ethernet network interface name might shift from one device to another if you add or remove a card and reboot the machine. For example, a device named eth2 might become eth1 after you remove a NIC and restart the machine.

You can prevent interface names from reordering by turning on predictable network interface names. The naming schemes that Photon OS uses can then assign fixed, predictable names to network interfaces even after you add or remove cards or other firmware and the restart the system.

When you enable predictable network interface names, you can use one of the following options to assign persistent names to network interfaces:

• Apply the slot name policy to set the name of networking devices in the ens format with a statically assigned PCI slot number.
• Apply the mac name policy to set the name of networking devices in the enx format a unique MAC address.
• Apply the path name policy to set the name of networking devices in the enpXsY format derived from a device connector’s physical location.

Though Photon OS supports the onboard name policy to set the name of networking devices from index numbers given by the firmware in the eno format, the policy might result in nonpersistent names.

The option to choose depends on your use case and your unique networking requirements. For example, when you clone virtual machines and require the MAC addresses to be different from one another but the interface name to be the same, consider using ens to keep the slot the same after system reboots.

Alternatively, if the cloning function supports enx, you can use it to set a MAC address which persists after reboots.

Perform the following steps to turn on predictable network interface names:

1. Make a backup copy of the following file in case you need to restore it later:

cp /boot/grub/grub.cfg /boot/grub/grub.cfg.original

2. To turn on predictable network interface names, edit /boot/grub/grub.cfg to remove the following string:

net.ifnames=0Item

The string appears near the bottom of the file in the menuentry section:

menuentry "Photon" {
    linux "/boot/"$photon_linux root=$rootpartition net.ifnames=0 $photon_cmdline
    if [ "$photon_initrd" ]; then
        initrd "/boot/"$photon_initrd
    fi
}
# End /boot/grub2/grub.cfg

Edit out net.ifnames=0, but make no other changes to the file, and then save it.

1. Specify the types of policies that you want to use for predictable interface names by modifying the NamePolicy option in /lib/systemd/network/99-default.link. The file contents are as follows:

cat /lib/systemd/network/99-default.link
[Link]
NamePolicy=kernel database
MACAddressPolicy=persistent

To use the ens or enx option, the slot policy or the mac policy can be added to the space-separated list of policies that follow the NamePolicy option in the default link file, /lib/systemd/network/99-default.link. The order of the policies matters. Photon OS applies the policy listed first before proceeding to the next policy if the first one fails.

For example:

/lib/systemd/network/99-default.link
    [Link]
    NamePolicy=slot mac kernel database
    MACAddressPolicy=persistent

With the name policy specified in the above example, you might still have an Ethernet-style interface name if the two previous policies, slot and mac, fail.

For information on setting name policies, see systemd.link–network device configuration.

5.5.11 - Inspecting the Status of Network Links with 'networkctl'

You can inspect information about network connections by using the networkctl command. This can help you configure networking services and troubleshoot networking problems.

You can progressively add options and arguments to the networkctl command to move from general information about network connections to specific information about a network connection.

networkctl Command Without Options

Run the networkctl command without options to default to the list command:

networkctl
IDX LINK             TYPE               OPERATIONAL  SETUP
  1 lo               loopback           carrier      unmanaged
  2 eth0             ether              routable     configured
  3 docker0          ether              routable     unmanaged
  11 vethb0aa7a6     ether              degraded     unmanaged
  4 links listed.

’networkctl status’ Command

Run networkctl with the status command to display the following information:

root@photon-rc [ ~ ]# > networkctl status
   State: routable
  Address: 10.197.103.56 on eno1
           172.17.0.1 on docker0
           fe80::20c:29ff:fe44:f92c on eno1
  Gateway: 10.197.103.253 (Cisco Systems, Inc) on eno1
      DNS: 10.142.7.1
           10.132.7.1
           10.166.17.90
      NTP: 10.128.152.81
           10.166.1.120
           10.188.26.119
           10.84.55.42

You can see that there are active network links with IP addresses for not only the Ethernet connection but also a Docker container.

’networkctl status’ Command With Network Link Option

You can add a network link, such as the Ethernet connection, as the argument of the status command to show specific information about the link:

	root@photon-rc [ ~ ]# networkctl status ens33
	* 2: ens33
	         Link File: /usr/lib/systemd/network/99-default.link                                      
                  Network File: /usr/lib/systemd/network/10-eth.network                                       
                          Type: ether                                                                         
                         State: routable (configured)                               
             Alternative Names: enp2s1                                                                        
                          Path: pci-0000:02:01.0                                                              
                        Driver: e1000                                                                         
                        Vendor: Intel Corporation                                                             
                         Model: 82545EM Gigabit Ethernet Controller (Copper) (PRO/1000 MT Single Port Adapter)
                    HW Address: 00:0c:29:5f:d1:39 (VMware, Inc.)                                              
                           MTU: 1500 (min: 46, max: 16110)                                                    
                         QDisc: fq_codel                                                                      
  IPv6 Address Generation Mode: eui64                                                                         
          Queue Length (Tx/Rx): 1/1                                                                           
              Auto negotiation: yes                                                                           
                         Speed: 1Gbps                                                                         
                        Duplex: full                                                                          
                          Port: tp                                                                            
                       Address: 172.16.85.225 (DHCP4 via 172.16.85.254)                                       
                                fe80::20c:29ff:fe5f:d139                                                      
                       Gateway: 172.16.85.2 (VMware, Inc.)                                                    
                           DNS: 172.16.85.2                                                                   
               DHCP4 Client ID: IAID:0x2b9434c1/DUID                                                          
             DHCP6 Client DUID: DUID-EN/Vendor:0000ab11d258482fc7eee6510000                                   
Feb 26 10:19:44 photon systemd-networkd[650]: ens33: Link UP
Feb 26 10:19:44 photon systemd-networkd[650]: ens33: Gained carrier
Feb 26 10:19:45 photon systemd-networkd[650]: ens33: DHCPv4 address 172.16.85.225/24 via 172.16.85.2
Feb 26 10:19:46 photon systemd-networkd[650]: ens33: Gained IPv6LL

’networkctl status’ Command With Docker Option

You can add a Docker container as the argument of the status command to show specific information about the container:

networkctl status docker0
	* 3: docker0
	       Link File: /usr/lib/systemd/network/99-default.link
	    Network File: n/a
	            Type: ether
	           State: routable (unmanaged)
	          Driver: bridge
	      HW Address: 02:42:f0:f7:bd:81
	             MTU: 1500
	         Address: 172.17.0.1
	                  fe80::42:f0ff:fef7:bd81

In the example above, the state of the Docker container is unmanaged because Docker handles managing the networking for the containers without using systemd-resolved or systemd-networkd. Docker manages the container connection by using its bridge drive.

For more information about networkctl commands and options, see https://www.freedesktop.org/software/systemd/man/networkctl.html.

5.5.12 - Turning On Network Debugging

You can set systemd-networkd to work in debug mode so that you can analyze log files with debugging information to help troubleshoot networking problems.

You can turn on network debugging by adding a drop-in file in /etc/systemd to customize the default systemd configuration in /usr/lib/systemd.

Procedure

1. Run the following command as root to create a directory with the name systemd-networkd.service.d, including the .d extension:

   systemctl edit systemd-networkd.service
   

2. Add following configuration in the file override.conf to establish a systemd drop-in unit with a debugging configuration for the network service:

   	[Service]
   	Environment=SYSTEMD_LOG_LEVEL=debug
   

3. Reload the systemctl daemon and restart the systemd-networkd service for the changes to take effect:

   systemctl daemon-reload
   systemctl restart systemd-networkd
   

4. Verify your changes:

   systemd-delta --type=extended
   

5. View the log files by running this command:

   journalctl -u systemd-networkd
   

6. After debugging the network connections, turn debugging off by deleting the drop-in file:

   rm /etc/systemd/system/systemd-networkd.service.d/10-loglevel-debug.conf
   

5.5.13 - Installing packages for 'tcpdump' and 'netcat'

Photon OS includes the following networking tools:

• tcpdump. A networking tool that captures and analyzes packets on a network interface. tcpdump is not available with the minimal version of Photon OS but available in the repository. The minimal version includes the iproute2 tools by default.

  You can install tcpdump and its accompanying package libpcap, a C/C++ library for capturing network traffic, by using tdnf:

tdnf install tcpdump

• netcat. A tool to send data over network connections with TCP or UDP. This tool is not included in either the minimal or the full version of Photon OS. But since netcat furnishes powerful options for analyzing, troubleshooting, and debugging network connections, you might want to install it. To install `netcat’, run the following command:

tdnf install netcat

5.5.14 - Mounting a Network File System

To mount a network file system, Photon OS requires nfs-utils. The nfs-utils package contains the daemon, userspace server, and client tools for the kernel Network File System (NFS). The tools include mount.nfs, umount.nfs, and showmount.

The nfs-utils package is installed by default in the full version of Photon OS but not in the minimal version. To install nfs-utils in the minimal version, run the following command as root:

tdnf install nfs-utils

For instructions on how to use nfs-utils to share files over a network, see Photon OS nfs-utils.

5.5.15 - Configuring a Secondary Network Interface using Cloud-Network

When you add a secondary network interface to a linux instance in the cloud environment, you need to configure the network parameters for the secondary interface in the linux instance. The configuration ensures that you do not face any routing issues while using the secondary network interface. Configuring the secondary network interface involves several manual processes that include configuring a new routing table, setting up rules in the routing table and so on.

cloud-network automates the whole manual process of configuring the secondary network interface. It configures the network parameters required for any network interfaces that you create or add to the linux instance. In a cloud environment, instances are set to public IPs and private IPs. If you add more than one private IP for the secondary network interface, the IP other than the one provided by DHCP cannot be fetched and configured for your virtual machine. The cloud-network project is designed to adapt the cloud-network environments such as Azure, GCP, and Amazon EC2. cloud-network fetches the metadata from the metadata server endpoint, parses the metadata, and then assigns IPs and routes. When cloud-network is installed, it automatically configures network interfaces in the cloud frameworks. It detects the available interfaces using netlink. Additionally, for all the interfaces, including the primary one, it looks for any secondary IP addresses from the metadata server endpoint and configures them on the interface, if any.

A local RESTful JSON server runs on the address 127.0.0.1:5209 and the instance metadata is saved on per link basis in the following directory: /run/cloud-network.

The network parameters in the cloud framework are checked periodically for any changes, and in case of a change, the interface is reconfigured accordingly.

The image below illustrates the communication of cloud-network and the instance metadata server:

Use Case: Making a secondary network interface work in a cloud instance.

This functionality is scattered across different scripts/tools that are cloud provider dependent. cloud-network provides a cloud-agnostic mechanism to retrieve the metadata like network parameters, and configure the interfaces. This means that there is no need to manually edit and update the configuration when there are changes in the network parameters. cloud-network automatically configures the interfaces since it has the metadata information.

The image below illustrates how cloud-network fetches the network parameters to configure the secondary network interface (eth1) in a cloud instance:

Installing Cloud Network Setup

Type the following command to install cloud network in your system:

tdnf install cloud-network-setup

Configuration

To manage the configuration, use the configuration file named cloud-network.toml located in the following directory: /etc/cloud-network/

[System] Section

You can set values for the following keys in the [System] section:

LogLevel=
Specifies the log level. The key takes one of the following values: Trace, Debug, Info, Warning, Error, Fatal and Panic. Default is info.

LogFormat=
Specifies the log format. The key takes one of the following values: text or JSON. Takes one of text or json, Default is text.

RefreshTimer=
Specifies the time interval. The time interval indicates the amount of time taken to retrieve the data from the metadata endpoint.

[Network] Section

You can set values for the following keys in the [Network] section:

Listen=

Specifies the IP address and the port that the local REST API server listens. You can specify the IP address and the port in the following format ip:port. Defaults is 127.0.0.1:5209.

Supplementary=
A whitespace-separated list of interfaces matching the device name. Specifies the interfaces you want to configure with a default gateway and routing policy rules for each IP address including the primary IP address. No default value is set for this key.

Note When there are multiple interfaces, the secondary interface becomes unreachable. When you set a value for Supplementary= key, the default route and routing policy rules are automatically configured.

The following example shows a sample configuration of the key values in the cloud-network.toml file:

> cat /etc/cloud-network/cloud-network.toml
[System]
RefreshTimer="300s"
LogLevel="info"
LogFormat="text"

[Network]
Listen="127.0.0.1:5209"
Supplementary="eth0"

After you set the configuration, use the sudo systemctl status cloud-network command to check the network status of the cloud-network service. Following example shows the command output of the sudo systemctl status cloud-network command:

❯ > sudo systemctl status cloud-network
● cloud-network.service - Configures network in cloud enviroment
     Loaded: loaded (/usr/lib/systemd/system/cloud-network.service; disabled; vendor preset: enabled)
     Active: active (running) since Mon 2021-05-31 22:54:50 UTC; 3min 31s ago
   Main PID: 19754 (cloud-network)
      Tasks: 5 (limit: 4400)
     Memory: 8.7M
     CGroup: /system.slice/cloud-network.service
             └─19754 /usr/bin/cloud-network

May 31 22:54:50 zeus-final-2 systemd[1]: Started Configures network in cloud enviroment.

cnctl

Use the cnctl CLI tool to view the metadata that is retrieved from the endpoint metadata server. The Following examples show the output of the cnctl status command for the network and system:

❯ cnctl status system
    Cloud provider: aws
             AmiID: ami-005f15863xxxxxxxx  
          Location: 0
BlockDeviceMapping: Ami:xvda Root:/dev/xvda
          Hostname: Zeus.us-west-2.compute.internal
    PublicHostname: Zeuspublic.us-west-2.compute.amazonaws.com
     LocalHostname: Zeus.us-west-2.compute.internal
    InstanceAction: none
    InstanceID: i-0c8c1test
 InstanceLifeCycle: on-demand
      InstanceType: t4g.micro
         Placement: AvailabilityZone:us-west-2d AvailabilityZoneID:usw2-az4 Region:us-west-2
           Profile: default-hvm
       Mac Address: 0e:c5:3f:c5:33:a5
         LocalIpv4: 192.31.63.114
        PublicIpv4: 02:42:8d:4c:0c:cf
   Services Domain: amazonaws.com
Services Partition: aws  

❯ cnctl status network
            Name: ens33
     MAC Address: 00:0c:29:5f:d1:39
       Public IP: 104.42.20.194
      Private IP: 10.0.0.4/24 10.0.0.6/24 10.0.0.7/24
          Subnet: 10.0.0.0

5.5.16 - Using Network Event Broker

network-event-broker is a daemon that configures network and executes scripts on network events such as systemd-networkd’s DBus events, dhclient lease gains, and so on.

network-event-broker also detects the following events:

• An IP address is added/removed/modified
• A link is added or removed

In the /etc/network-event-broker directory, network-event-broker creates the link state directories such as carrier.d, configured.d, degraded.d, no-carrier.d, routable.d and manager state directory such as manager.d . You can also keep the executable scripts in these directories.

Use Case: Running command when a new address is acquired via DHCP.

1. systemd-networkd: systemd-networkd’s scripts are executed when the daemon receives the relevant event from systemd-networkd.

    May 14 17:08:13 Zeus cat[273185]: OperationalState="routable"  
    May 14 17:08:13 Zeus cat[273185]: LINK=ens33
   

2. dhclient: For dhclient, scripts are executed in the routable.d directory when dhclient modifies the /var/lib/dhclient/dhclient.leases file and lease information is passed to the scripts as environmental arguments.

Environment variables such as LINK, LINKINDEX= and DHCP lease information DHCP_LEASE= are passed to the scripts.

Configuration

To manage the network-event-broker configuration, use the configuration file named network-broker.toml located in the following directory: /etc/network-broker/

[System] section

You can set values for the following keys in the [System] section:

LogLevel=
Specifies the log level. The key takes one of the following values: info, warn, error, debug and fatal. Default is info.

Generator=
Specifies the network event generator source. The key takes one of the following values: systemd-networkd or dhclient. Default is systemd-networkd.

[Network] section

You can set values for the following keys in the [Network] section:

Links=
A whitespace-separated list of links whose events should be monitored. No default value is set for this key.

RoutingPolicyRules=
A whitespace-separated list of links for which you want to configure the routing policy rules per address. When you set this configuration, network-event-broker automatically adds the to and from routing policy rules in another routing table (ROUTE_TABLE_BASE = 9999 + ifindex). When these addresses are removed, the routing policy rules are dropped. No default value is set for this key.

UseDNS=
Specifies whether you want to send the DNS server details to systemd-resolved. The key takes one of the following values: true, false. When set to true, the DNS server details are sent to systemd-resolved via DBus. This is applicable only to the DHClient. Default is false.

UseDomain=
Specifies whether you want to send the DNS domain details to systemd-resolved. The key takes one of the following values: true, false. When set to true, the DNS domain details are sent to systemd-resolved via DBus. This is applicable only to the DHClient. Default is false.

UseHostname=
Specifies whether you want to send the host name to systemd-hostnamed. The key takes one of the following values: true, false. When set to true, the host name is sent to systemd-hostnamed via DBus. This is applicable only to the DHClient. Default is false.

The following example shows a sample configuration of the key values in the network-broker.toml file:

❯ sudo cat /etc/network-broker/network-broker.toml 
[System]
LogLevel="debug"
Generator="dhclient"

[Network]
Links="ens33 ens37"
RoutingPolicyRules="ens33 ens37"
UseDNS="true"
UseDomain="true"

5.5.17 - Configuring a Network Using Network Configuration Manager

You can use network-configuration-manager to configure a network in Photon OS. The YAML-based configuration system in network-config-manager makes the network configuration easy and simple.

The following sections in the document demonstrate the configuration of a network in Photon OS using network-config-manager.

You can find the YAML network configuration files at the following location:

/etc/network-config-manager/yaml/ 

When you install network-configuration-manager, it generates the network-config-manager configuration file for systemd-networkd named 99-dhcp.yaml.example.

Perform the following steps to configure static or dynamic IP addressing in Photon OS:

1. To find the name of the active network interfaces that you want to configure, execute the following command:

❯ ip a   
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 00:0c:29:5f:d1:39 brd ff:ff:ff:ff:ff:ff
    altname enp2s1
    inet 192.168.1.4/24 metric 1024 brd 192.168.1.255 scope global dynamic ens33
       valid_lft 82465sec preferred_lft 82465sec
    inet6 fe80::20c:29ff:fe5f:d139/64 scope link 
       valid_lft forever preferred_lft forever

Note the name of the interface that you want to configure using network-config-manager.

2. To find the network-configuration-manager default configuration file, execute the following command:

   ❯ ls /etc/network-config-manager/yaml
   

3. To view the content of the network-config-manager network configuration file, execute the following command:

   ❯ cat /etc/network-config-manager/yaml/*.yaml
   

4. Open the configuration file in an editor.
   For example, if you use vim editor, execute the following command to open the configuration file in an editor:

   ❯ sudo vim /etc/network-config-manager/yaml/99-dhcp.yaml
   

5. Use the following syntax to update the configuration file as per your networking needs:

   network:
   Version: 2
   Renderer: networkd
   ethernets:
      device:
         dhcp4: yes/no
         nameservers:
            addresses: [NAMESERVER, NAMESERVER, ...]
         addresses: [IPADDRESS/PREFIX]
          routes:
         - to: DESTINATION
           via: GATEWAY
   

   Note that for static IP addressing, add the IP address, Gateway, and DNS details. For dynamic IP addressing, you need not add these details as it is fetched from the DHCP server.

   The following table describes the properties used in the syntax to update the configuration file.

   Properties	Description
   device: |	Name of the interface.
   dhcp4: |	yes or no depending upon dynamic or static IP addressing
   addresses: |	IP address of the device in prefix notation.
   routes: to: destination via: |	gateway IP address to connect to an outside network
   nameservers: |	Address of DNS name servers

Note: It is recommended that you use spaces for indentation instead of tabs in the YAML configuration file. If you use a tab instead of spaces for indentation, you might encounter errors.

Configuring static IP address in Photon OS

To manually configure an IP address, use the previously mentioned file syntax in this topic, and add the IP address, Gateway, and DNS server details.

The following is a sample configuration for the static IP addressing:

network:
    ethernets:
        eth0:
            dhcp4: false
            addresses: [192.168.1.202/24]
            nameservers:
              addresses: [8.8.8.8,8.8.4.4,192.168.1.1]
            routes:
            - to: 172.16.0.0/24
              via: 192.168.1.100

Configure Dynamic IP address in Photon OS

To get the IP address from the DHCP server, use the previously mentioned file syntax in this topic. You need not add the IP address, Gateway, and DNS server details here.

The following is a sample configuration for the dynamic IP addressing:

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: true

After configuring the IP address, you need to apply the new configuration. Execute the following command as sudo to apply the configuration:

$ sudo nmctl apply

To verify that the configurations are successfully applied, execute the following command and verify the IP address:

❯ nmctl status eth0
                       Flags: UP BROADCAST RUNNING NOARP LOWERUP 
                        Kind: dummy
                        Type: ether
                      Driver: dummy
                   Link File: /usr/lib/systemd/network/99-default.link
                Network File: /etc/systemd/network/10-eth0.network
                       State: routable (configured) 
               Address State: routable
          IPv4 Address State: routable
          IPv6 Address State: degraded
                Online State: online
         Required for Online: yes
           Activation Policy: up
                  HW Address: 56:d3:b9:4f:03:38 ((null))
                         MTU: 1500 (min: 0 max: 0) 
                       QDISC: noqueue 
              Queues (Tx/Rx): 1/1 
             Tx Queue Length: 1000 
IPv6 Address Generation Mode: eui64 
                GSO Max Size: 65536 GSO Max Segments: 65535 
                     Address: fe80::54d3:b9ff:fe4f:338/64
                              192.168.1.202/24
                     Gateway: 192.168.1.100
                         DNS: 8.8.4.4 192.168.1.1 8.8.8.8
           DHCP6 Client DUID: DUID-EN/Vendor:0000ab11d258482fc7eee6510000

To see the routes, execute the following command:

❯ ip r show dev eth0
172.16.0.0/24 via 192.168.1.100 proto static 

5.6 - Prioritize eth0 Route Over WLAN

You can prioritise the eth0 route over the WLAN route. Perform the following steps:

1. Modify the /etc/systemd/network/99-dhcp-en.network file and add the following content:

   [DHCP]
   RouteMetric=512
   

2. Restart systemd-networkd.

5.7 - Configuring Photon Real-Time Operating System for Real-Time Applications

Photon Real-Time (RT) Operating System (OS) (and the Linux kernel PREEMPT_RT patchset that it is based on) is optimized to support low-latency real-time scheduling and minimize the OS jitter as observed by real-time applications. However, to get the most out of Photon RT OS, it is must to have a proper system configuration. To run low-latency real time applications effectively, the sources of jitter have to be identified and eliminated across all layers of the underlying system, spanning the BIOS / firmware, the hypervisor, and the guest operating system (Photon RT).

BIOS/Firmware

Tuning a system for real time operation starts from the lowest layers of the software stack, namely the System BIOS or Platform Firmware. The goal is to configure the settings for the following functions:

• Maximize Performance Ex: Set CPU, memory and device power management modes to maximum performance, disable CPU idle states

• Minimize Computational Jitter Ex: Disable Turbo Boost, disable Hyper-Threading

• Minimize System Management Interrupts Ex: Disable options such as Processor Power and Utilization Monitoring, memory Pre-Failure Notification, and so on

Platform vendors often publish low-latency tuning guides for their BIOS/firmware. Refer documentation to learn about the recommended low-latency settings specific to your platform.

Deploying Real-Time Applications on Photon Real-Time Operating System

A general strategy to deploy real-time applications on Photon RT is described as follows:

• Partition CPUs between the OS and the RT workload: Among the available CPUs in the system, isolate a subset of CPUs, designated to run the RT workload. By default, the Linux scheduler will only run tasks on non-isolated CPUs, leaving the isolated CPUs to those tasks that are explicitly bound to them. Thus, all the housekeeping tasks of the OS will execute on non-isolated CPUs (with a few exceptions, such as per-CPU kernel threads). Then bind the RT workload to the isolated CPUs.

• Steer unrelated interrupts away from the CPUs running the RT workload: Linux supports the ability to affine most interrupts to specific CPUs in the system. By using this mechanism, interrupts that are not relevant to the real-time workload can be affined to non-isolated CPUs, thus avoiding the jitter caused by interrupt handling latency on the isolated CPUs.

This strategy provides two important benefits:

1. It limits OS interference with the RT workload.

2. It protects the OS services from getting starved by the CPU-intensive RT tasks.

This configuration can be achieved using a combination of kernel command-line options, and user space packages, as discussed in the following sections.

Kernel Command-Line Parameters

• CPU isolation

  isolcpus=X,Y-Z (Ex: isolcpus=2,4-5)

• Interrupt affinity

  irqaffinity=X,Y-Z (Ex: irqaffinity=0-1,3) [ Usually it is the inverse of isolcpus.]

• RCU callbacks

rcu_nocbs=X,Y-Z [ Usually it is same as isolcpus. ] rcu_nocb_poll=1

• NOHZ (Eliminating the periodic timer)

  nohz=on nohz_full=X,Y-Z [ Usually it is same as isolcpus. ]

• CPU idle

  idle=halt or idle=poll intel_idle.max_cstate=0 cpuidle.off=1

• CPU frequency

  intel_pstate=disable

• Lockup detectors

  nosoftlockup nowatchdog nmi_watchdog=0

• Timer skew detection

    skew_tick=1
    clocksource=tsc
    tsc=reliable
  

The full list of kernel command-line parameters and their descriptions are available at https://www.kernel.org/doc/html/v6.1/admin-guide/kernel-parameters.html

Tuned configuration

Tuned is a system tuning daemon that offers several profiles to tailor the OS to various usecases, including a ‘realtime’ profile for low-latency workloads.

The realtime tuned profile can be applied as shown below:

• tdnf install tuned

• systemctl enable tuned

• systemctl start tuned

Add isolcpus to /etc/tuned/realtime-variables.conf (by uncommenting the isolated_cores= parameter):

$ cat /etc/tuned/realtime-variables.conf

Examples:

# isolated_cores=2,4-7

Note: The cores configured as isolated in tuned should be consistent with isolcpus in the kernel command-line.

tuned-adm profile realtime

Stalld configuration

The stalld daemon monitors the system for starved tasks and revives them by giving them a temporary boost using the SCHED_DEADLINE policy. stalld offers fine-grained controls to give starved tasks a user-specified amount of CPU time.

The stalld configuration file is /etc/sysconfig/stalld.

The key parameters are Starving Threshold (THRESH), Boost Period (BP), Boost Runtime (BR), and Boost Duration (BD).

The mode of operation is as follows:

If a task is starved for at least THRESH seconds, it is scheduled using SCHED_DEADLINE scheduling policy, so that it will run at least BR nanoseconds in every BP nanoseconds time period, and this repeats up to BD seconds, after which the task gets back its original scheduler policy/priority settings.

Real Time Scheduling Policies

The Linux kernel offers several scheduling policies to support various applications, among which the real time policies are highlighted below:

• SCHED_OTHER (default policy), SCHED_BATCH, SCHED_IDLE (non real-time policies)

• SCHED_FIFO (First-In First-Out Real Time Scheduling)

1. Priority Range: 1 to 99 (highest)

2. Algorithm: The scheduler runs the highest-priority runnable task in the SCHED_FIFO scheduling class, until it yields (blocks/waits) the CPU voluntarily.

• SCHED_RR (Round-Robin Real Time Scheduling)

1. Priority Range: 1 to 99 (highest)

2. Algorithm: The scheduler runs the highest-priority SCHED_RR task, and time-slices between equal-priority SCHED_RR tasks in configurable intervals.

• SCHED_DEADLINE ( Earliest Deadline First Real Time Scheduling)

1. Key parameters: Runtime, Period and Deadline, which can be configured on a per-task basis.

2. Algorithm: The scheduler gives a SCHED_DEADLINE task at least Runtime amount of time on the CPU in every Period time period, before Deadline time is up.

Real Time Throttling

The Linux kernel offers proc file system (procfs) controls to influence real-time task scheduling and throttling.

The RT throttling algorithm is as follows:

• All real-time tasks are throttled to run up to runtime microseconds, in every period microseconds. The remaining time in period microseconds is used to run non-RT tasks in the system.

• runtime and period values can be configured by writing to the files listed as follows:

1. /proc/sys/kernel/sched_rt_runtime_us Default: 95% (950000) Range: -1 to (INT_MAX -1) [ -1 implies no limit, i.e., no throttling ]

2. /proc/sys/kernel/sched_rt_period_us Default: 1s (1000000) Range: 1 to INT_MAX

Note: See Command Line Reference for the commands for manipulating real-time properties of processes.

5.8 - Containers

A container is a process that runs on the Photon OS host with its own isolated application, file system, and networking.

Photon OS includes the open source version of Docker. With Docker, Photon OS becomes a Linux run-time host for containers, that is, a Linux cloud container.

The full version of Photon OS includes Kubernetes so you can manage clusters of containers.

5.8.1 - Docker Containers

On Photon OS, the Docker daemon is enabled by default. To view the status of the daemon, run the following command:

systemctl status docker

Docker is loaded and running by default on the full version of Photon OS. On the minimal version, it is loaded but not running by default. To start it, run the following command:

systemctl start docker

To obtain information about Docker, run the following command as root:

docker info

After Docker is enabled and started, you can create a container. For example, run the following docker command as root to create a container running Ubuntu 14.04 with an interactive terminal shell:

docker run -i -t ubuntu:14.04 /bin/bash

Photon OS also enables you to run a docker container that runs Photon OS:

docker run -i -t photon /bin/bash

5.8.2 - Docker Rootless Support

Run the Docker daemon as a non-root user (Rootless mode)

The Rootless mode allows you to run the Docker daemon and containers as a non-root user. This mitigates the potential vulnerabilities in the daemon and the container runtime.

As long as the prerequisites are met, rootless mode does not require root privileges even during the installation of the Docker daemon.

After its introduction in Docker Engine v19.03 as an experimental feature, the rootless mode was available in Docker Engine v20.10 as a more stable feature.

This feature is available in Photon OS 4.0 and above versions starting from the docker-20.10.14-1 version (in Ph4).

Prerequisites:

• You must install newuidmap and newgidmap on the host. - Provided by the shadow package in Photon

• /etc/subuid and /etc/subgid should contain at least 65,536 subordinate UIDs/GIDs for the user. In the following example, the user called testuser has 65,536 subordinate UIDs/GIDs (100000-165535).

• You can install the pre-required packages using the following command:

  tdnf install -y shadow fuse slirp4netns libslirp
  

• Photon 3 or above with docker-20.10.14-1 version (this version is specific to Ph4. For higher versions please refer spec file in the Photon source).

Usage:

You can perform the following tasks with the respective commands for them:

1. Install docker-rootless using the following command:

   tdnf install -y docker-rootless
   

2. Use the following command to add a new user:

   useradd -m test_user
   

3. Use the following command to set a password for the new user:

   passwd test_user
   

4. Use the following command to log in as the user you created:

   `ssh test_user@localhost`
   

5. Run the following command:

   dockerd-rootless-setuptool.sh --help`
   

   The above command shows something like the following output:

   test_user@photon [ ~ ]$ dockerd-rootless-setuptool.sh --help
   Usage: /usr/bin/dockerd-rootless-setuptool.sh [OPTIONS] COMMAND
   
   A setup tool for Rootless Docker (dockerd-rootless.sh).
   
   Documentation: https://docs.docker.com/go/rootless/
   
   Options:
   -f, --force Ignore rootful Docker (/var/run/docker.sock)
   --skip-iptables Ignore missing iptables
   
   Commands:
   check Check prerequisites
   install Install systemd unit (if systemd is available) and show how to manage the service
   uninstall Uninstall systemd unit
   

6. Run the following command, and then check and fix the errors and warnings, if any:

   dockerd-rootless-setuptool.sh`
   

   Run the following commands:

   a. echo "test_user:100000:65536" >> /etc/subuid

   b. echo "test_user:100000:65536" >> /etc/subgid

   c. echo "kernel.unprivileged_userns_clone = 1" >> /etc/sysctl.d/50-rootless.conf

   d. chmod 644 /etc/subuid /etc/subgid /etc/sysctl.d/50-rootless.conf

   e. sysctl --system

   After you run the above commands, the dockerd-rootless-setuptool.sh check shows the following output:

   test_user@photon [ ~ ]$ dockerd-rootless-setuptool.sh check
   
   [INFO] Requirements are satisfied
   

7. After the Requirements are satisfied message appears, run the following command:

   dockerd-rootless-setuptool.sh install
   

8. Carefully, go through the output messages of the above command and ensure that everything is fine. Follow the instructions that appear, if any.

9. Add the following to your .bashrc or .bash_profile:

   export PATH=/usr/bin:$PATH
   export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
   

Now, you can run docker run -it photon as a regular user.

Limitations:

Exposing Network Ports Be aware that port numbers below 1024 are called privileged ports and are not available for rootless users. So, you need to use the unprivileged ports such as 8080, and so on. If you want to run an HTTP server, you need to run docker run -p 8080:80. However, if you really need to expose privileged ports, you can do that by adjusting sysctl /proc/sys/net/ipv4/ip_unprivileged_port_start or by setting CAP_NET_BIND SERVICE capability on the binary rootlesskit.

Limiting Resources such as CPU, Memory

Limiting resources with cgroup-related docker run flags such as --cpus, --memory, --pids-limit is supported only while running with cgroup v2 and systemd.

If docker info shows none as Cgroup Driver, the conditions are not satisfied. When these conditions are not satisfied, rootless mode ignores the cgroup-related docker run flags.

5.8.3 - Kubernetes

The Kubernetes package provides several services: kube-apiserver, kube-scheduler, kube-controller-manager, kubelet, kube-proxy. These services are managed by systemd. Their configuration resides in a central location: /etc/kubernetes.

For more information, see Running Kubernetes on Photon OS.

5.8.4 - Support for distributed builds using Kubernetes

The distributed system using Kubernetes allows the build system to utilize the maximum CPU power across a kubernetes cluster (pods) for faster build process.

Prerequisites

• Ensure that the NFS server is running
• Ensure that you have the Kubernetes cluster ready that has access to the NFS server
• Ensure that you have installed Kubernetes package and have kubeconfig accessible in the build VM.

Triggering Distributed Photon Builds

Perform the following steps in the Photon OS repository:

1. Update the 'common/data/distributed_build_options.json' configuration file . The following parameters need to be filled:

• command→ target to run like 'make packages' or 'make packages-minimal' or 'make toolchain-stage-1' or so on. Note: Keep the command with flag 'SCHEDULER_SERVER=enable'.

• nfs-server-ip→ IP address of the nfs server

• pods→ number of builder/worker pods you want such as 10 or 20. The default value is 1.

• nfs-server-path-> path of the nfs mount. For example,/mnt/NFS_PATH/MY_DIR

2. Run make distributed-build.

Note:

• This process will make use of the kubeconfig file present under the home directory and start building packages over the specified cluster.
• It creates one Master pod and multiple worker pods (numbers defined in config.json).
• The master pod runs the scheduler while the worker or the builder pods build the packages.
• Distributed Builder monitors the build mob and deletes everything when build has either completed successfully or failed.

The master starts the scheduler server to schedule the packages that have to be built. The worker makes REST calls to scheduler server.get package and notify after the build.

The distributed build also builds cloud images.

5.9 - Changing the Locale

You can change the locale if the default locale does not meet your requirements.

To find the locale, run the the localectl command:

localectl
System Locale: LANG=en_US.UTF-8
   VC Keymap: n/a
  X11 Layout: n/a

To change the locale, choose the languages that you want from /usr/share/locale/locale.alias, add them to /etc/locale-gen.conf, and then regenerate the locale list by running the following command as root:

locale-gen.sh

Finally, run the following command to set the new locale, replacing the example (en_US.UTF-8) with the locale that you require:

localectl set-locale LANG="de_CH.UTF-8" LC_CTYPE="de_CH.UTF-8"

Changing the keyboard layout

See which keymaps are currently available on your system:

localectl list-keymaps

If the response to that command is the all-too-common Couldn't find any console keymaps, install the key tables files and utilities:

tdnf install kbd

You should now be able to find a keymap matching your keyboard. As an example, here I’m searching for the German keyboard layout (so I’m expecting something with de in the name) used in Switzerland:

localectl list-keymaps | grep de

    ...
    de-latin1
    de-latin1-nodeadkeys
    de-mobii
    de_CH-latin1
    de_alt_UTF-8
    ...

de_CH-latin1 seems to be what we’re looking for, so change your current layout to that keymap:

localectl set-keymap de_CH-latin1

and confirm that the change has been made:

localectl
System Locale: LANG=de_CH.UTF-8
   VC Keymap: de_CH-latin1
  X11 Layout: n/a

Note: Photon OS comes with a minimal set of locales by default. If you need a full set of locales, you need to install the glibc-i18n package using the following command:

tdnf install -y glibc-i18n

5.10 - Cloud-Init on Photon OS

The minimal and full versions of Photon OS include the cloud-init service as a built-in component. Cloud-init is a set of Python scripts that initialize cloud instances of Linux machines. The cloud-init scripts configure SSH keys and run commands to customize the machine without user interaction. The commands can set the root password, create a hostname, configure networking, write files to disk, upgrade packages, run custom scripts, and restart the system.

5.10.1 - Cloud-Init Overview

cloud-init is a multi-distribution package that handles early initialization of a cloud instance.

In-depth documentation for cloud-init is available here:

https://cloudinit.readthedocs.org/en/latest/

Supported installations

Both the full version of and the minimal version of Photon OS support cloud-init.

Supported capabilities

Photon OS supports the following cloud-init capabilities:

• run commands: execute a list of commands with output to console.
• configure ssh keys: add an entry to ~/.ssh/authorized_keys for the configured user.
• install package: install additional packages on first boot.
• configure networking: update /etc/hosts, hostname, etc.
• write files: write arbitrary files to disk.
• add tdnf repository: add a tdnf repository to /etc/yum.repos.d.
• create groups and users: add groups and users to the system and set properties for them.
• run tdnf upgrade: upgrade all packages.
• reboot: reboot or power off when done with cloud-init.

Getting Started

The Amazon Machine Image of Photon OS has an ec2 datasource turned on by default so an ec2 configuration is accepted. However, for testing, the following methods provide ways to do cloud-init with a standalone instance of Photon OS.

Using a Seed ISO

This will be using the nocloud data source. In order to initialize the system in this way, an ISO file needs to be created with a meta-data file and an user-data file as shown below:

$ { echo instance-id: iid-local01; echo local-hostname: cloudimg; } > meta-data
$ printf "#cloud-config\nhostname: testhost\n" > user-data
$ genisoimage  -output seed.iso -volid cidata -joliet -rock user-data meta-data

Attach the seed.iso generated above to your machine and reboot for the init to take effect. In this case, the hostname is set to testhost.

Using a Seed Disk File

To init using local disk files, do the following:

mkdir /var/lib/cloud/seed/nocloud
cd /var/lib/cloud/seed/nocloud
$ { echo instance-id: iid-local01; echo local-hostname: cloudimg; } > meta-data
$ printf "#cloud-config\nhostname: testhost\n" > user-data

Reboot the machine and the hostname will be set to testhost.

Frequencies

Cloud-init modules have predetermined frequencies. Based on the frequency setting, multiple runs will yield different results. For the scripts to always run, remove the instances directory before rebooting.

rm -rf /var/lib/cloud/instances

Module Frequency Info

5.10.2 - Deploy Photon OS With 'cloud-init'

You can deploy Photon OS with cloud-init in the following ways:

• As a stand-alone Photon machine
• In Amazon Elastic Compute Cloud, called EC2
• In the Google cloud through the Google Compute Engine, or GCE
• In a VMware Vsphere private cloud

When a cloud instance of Photon OS starts, cloud-init requires a data source. The data source can be an EC2 file for Amazon’s cloud platform, a seed.iso file for a stand-alone instance of Photon OS, or the internal capabilities of a system for managing virtual machines, such as VMware vSphere or vCenter. Cloud-init also includes data sources for OpenStack, Apache CloudStack, and OVF. The data source comprises two parts:

1. Metadata
2. User data

The metadata gives the cloud service provider instructions on how to implement the Photon OS machine in the cloud infrastructure. Metadata typically includes the instance ID and the local host name.

The user data contains the commands and scripts that Photon OS executes when it starts in the cloud. The user data commonly takes the form of a shell script or a YAML file containing a cloud configuration. The cloud-init overview and cloud-init documentation contains information about the types of data sources and the formats for metadata and user data.

On Photon OS, cloud-init is enabled and running by default. You can use the following command to check the status:

systemctl status cloud-init 

The Photon OS directory that contains the local data and other resources for cloud-init is /var/lib/cloud.

Photon OS stores the logs for cloud-init in the /var/log/cloud-init.log file.

The following sections demonstrate how to use cloud-init to customize a stand-alone Photon OS machine, instantiate a Photon OS machine in the Amazon EC2 cloud, and deploy a virtual machine running Photon OS in vSphere. Each section uses a different combination of the available options for the metadata and the user data that make up the data source. Specifications, additional options, and examples appear in the cloud-init documentation.

5.10.3 - Customizing Guest OS using Cloud-Init

A guest operating system is an operating system that runs inside a virtual machine. You can install a guest operating system in a virtual machine and control guest operating system customization for virtual machines created from vApp templates.

When you customize your guest OS you can set up a virtual machine with the operating system that you want.

Procedure

1. Perform the following steps before cloning or customizing the guest operating system:
2. Ensure that disable_vmware_customization is set to false in the /etc/cloud/cloud.cfg file.
3. Set manage_etc_hosts: true in the /etc/cloud/cloud.cfg file.
4. Make a backup of the 99-disable-networking-config.cfg file and delete the file from /etc/cloud/cloud.cfg.d folder after backup.
5. Clone the VM or customize the guest operating system.
6. After you clone your VM or customize the guest operating system, perform the following steps:
7. Ensure that disable_vmware_customization is set to true in the /etc/cloud/cloud.cfg file in the newly created VM and the VM from where cloning was initiated.
8. Remove manage_etc_hosts: true from the /etc/cloud/cloud.cfg file in the newly created VM and the VM from where cloning was initiated.
9. Add a copy of the backed up file 99-disable-networking-config.cfg to its original folder /etc/cloud/cloud.cfg.d in the newly created VM and the VM from where cloning was initiated.

Note:

1. The disable_vmware_customization flag in /etc/cloud/cloud.cfg.d file decides which customization workflow to be initiated.

• Setting this to false invokes the Cloud-Init GOS customization workflow.
• Setting this to true invokes the traditional GOSC script based customization workflow.

1. When the manage_etc_hosts flag is set to true, Cloud-Init can edit the /etc/hosts file with the updated values.

   When the flag is set to true Cloud-Init edits the /etc/hosts file, even when there is no cloud config metadata available. Remove this entry once the Cloud-Init GOS customization is done, to stop Cloud-Init from editing /etc/hosts file and set a fallback configuration.

2. The 99-disable-networking-config.cfg file is packaged as part of Cloud-Init RPM in photon and it prevents Cloud-Init from configuring the network. Delete this file before starting the Cloud-Init customization and then paste the backup of the file in the /etc/cloud/cloud.cfg.d/ folder once the cloud-init workflow is complete. It is important to replace this file after Cloud-Init customization to avoid removal of network configuration in the Cloud-Init instance.

Result

Cloud-Init guest OS customization is now enabled.

5.10.4 - Creating a Stand-Alone Photon Machine With cloud-init

Cloud-init can customize a Photon OS virtual machine by using the nocloud data source. The nocloud data source bundles the cloud-init metadata and user data into an ISO that acts as a seed when you boot the machine. The seed.iso delivers the metadata and the user data without requiring a network connection.

Procedure

1. Create the metadata file with the following lines in the YAML format and name it meta-data:

   instance-id: iid-local01
      local-hostname: cloudimg
   

2. Create the user data file with the following lines in YAML and name it user-data:

     #cloud-config
     hostname: testhost
     packages:
      - vim
   

3. Generate the ISO that will serve as the seed. The ISO must have the volume ID set to cidata. In the following example, the ISO is generated on an Ubuntu 14.04 computer containing the files named meta-data and user-data in the local directory:

   genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data
   

   The ISO now appears in the current directory:

   steve@ubuntu:~$ ls
   meta-data seed.iso user-data
   

4. Optionally, check the ISO that you generated on Ubuntu by transferring the ISO to the root directory of your Photon OS machine and then running the following command:

   cloud-init --file seed.iso --debug init
   

   After running the cloud-init command above, check the cloud-init log file:

   more /var/log/cloud-init.log
   

5. Attach the ISO to the Photon OS virtual machine as a CD-ROM and reboot it so that the changes specified by seed.iso take effect. In this case, cloud-init sets the hostname and adds the vim package.

5.10.5 - Customizing a Photon OS Machine on EC2

You can upload an ami image of Photon OS to Amazon Elastic Compute Cloud (EC2) and customize the Photon OS machine by using cloud-init with an EC2 data source. The Amazon machine image version of Photon OS is available as a free download at the location packages.vmware.com/photon.

The cloud-init service is commonly used on EC2 to configure the cloud instance of a Linux image. On EC2, cloud-init sets the .ssh/authorized_keys file to let you log in with a private key from another computer, that is, a computer besides the workstation that you are already using to connect with the Amazon cloud.

Example

The cloud-config user-data file that appears in the following example contains abridged SSH authorized keys to show you how to set them.

Prerequisites

• To work with EC2, obtain Amazon accounts for both AWS and EC2 with valid payment information. If you execute the below examples, you will be charged by Amazon. You must replace the <placeholders> for access keys and other account information in the examples with your account information.
• Install and set up the Amazon AWS CLI and the EC2 CLI 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 Setting Up the AMI Tools.
• Create SSH keys and an RSA user signing certificate and its corresponding private RSA key file.

Procedure

1. Upload the Photon OS .ami image to the Amazon cloud and configure it with cloud-init. The correct virtualization type for Photon OS is hvm.

$ mkdir bundled
	$ tar -zxvf ./photon-ami.tar.gz 
	$ ec2-bundle-image -c ec2-certificate.pem -k ec2-privatekey.pem -u <EC2 account id>  --arch x86_64 --image photon-ami.raw --destination ./bundled/
	$ aws s3 mb s3://<bucket-name>
	$ ec2-upload-bundle --manifest ./bundled/photon-ami.manifest.xml --bucket <bucket-name> --access-key <Account Access Key> --secret-key <Account Secret key>
	$ ec2-register <bucket-name>/photon-ami.manifest.xml --name photon-ami --architecture x86_64 --virtualization-type hvm

1. Import the cloud-config data. In the following command, the --user-data-file option instructs cloud-init to import the cloud-config data in user-data.txt. The command assumes you have uploaded the user-data.txt file and created the keypair mykeypair and the security group photon-sg.

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

Describe the instance to see its ID:

$ ec2-describe-instances

1. Run the following command to obtain its public IP address, which you can use to connect to the instance with SSH:

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

1. Run the following commands to terminate the machine. It is important to shut down the machine because Amazon charges you while the host is running down.

$ ec2-deregister <ami-image-identifier>
$ ec2-terminate-instances <instance-id>

Result

The following are the contents of the user-data.txt file that cloud-init applies to the machine the first time that 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
	ssh_authorized_keys:
	 - ssh-rsa MIIEogIBAAKCAQEAuvHKAjBhpwuomcUTpIzJWRJAe71JyBgAWrwqyN1Mk5N+c9X5
	Ru2fazFA7WxQSD1KyTEvcuf8JzdBfrEJ0v3/nT2x63pvJ8fCl6HRkZtHo8zRu8vY
	KYTZS/sdvM/ruubHfq1ldRpgtYSqbkykoe6PCQIDAQABAoIBAEgveQtjVzHDhLTr
	rmwJmO316ERfkQ/chLaElhi9qwYJG/jqlNIISWFyztqD1b3fxU6m5MOBIujh7Xpg
	... ec3test@example.com