Photon OS Documentation

• 1: Quick Start Links
• 2: What is New in Photon OS 4 Rev2
• 3: What is New in Photon OS 4
• 4: Overview
• 4.1: Introduction to Photon OS
• 4.2: Flavours
• 5: Installation Guide
• 5.1: Downloading Photon OS
• 5.2: Upgrading to Photon OS 4.0
• 5.3: Building Images
• 5.3.1: Folder Layout
• 5.3.2: Build Prerequisites
• 5.3.3: Build an ISO from the Source Code for Photon OS
• 5.3.3.1: Building the ISO
• 5.3.4: Build Other Images for Photon OS
• 5.3.4.1: Building Cloud Images
• 5.3.4.2: Building OVA image
• 5.3.5: Use the Cached Toolchain and RPMS
• 5.3.6: Use Cached Sources
• 5.3.7: View Build Logs
• 5.4: Building Package or Kernel Modules Using a Script
• 5.5: Running Photon OS on vSphere
• 5.5.1: Prerequisites for Running Photon OS on vSphere
• 5.5.2: Importing the OVA for Photon OS 4.0
• 5.5.3: Installing the ISO Image for Photon OS 4.0
• 5.6: Running Photon OS on Fusion
• 5.6.1: Prerequisites for Running Photon OS on Fusion
• 5.6.2: Importing the OVA for Photon OS 4.0
• 5.6.3: Installing the ISO Image for Photon OS 4.0
• 5.7: Running Photon OS on Workstation
• 5.7.1: Prerequisites for Running Photon OS on Workstation
• 5.7.2: Importing the OVA for Photon OS 4.0
• 5.7.3: Installing the ISO Image for Photon OS 4.0
• 5.8: Running Photon OS on Amazon Elastic Cloud Compute
• 5.8.1: Prerequisites for Running Photon OS on AWS EC2
• 5.8.2: Set Up Photon OS on EC2
• 5.8.3: Deploy a Containerized Application in Photon OS
• 5.8.4: Launch the Web Server with Cloud-Init
• 5.8.5: Terminate the AMI Instance
• 5.9: Running Photon OS on Microsoft Azure
• 5.9.1: Prerequisites for Running Photon OS on Azure
• 5.9.2: Set Up Azure Storage and Uploading the VHD
• 5.9.3: Remove Photon OS From Azure
• 5.10: Running Photon OS on Google Compute Engine
• 5.10.1: Prerequisites for Running Photon OS on GCE
• 5.10.2: Installing Photon OS on Google Compute Engine
• 5.11: Running Photon OS on Raspberry Pi
• 5.11.1: Prerequisites for Running Photon OS on Raspberry Pi
• 5.11.2: Installing Photon OS on Raspberry Pi
• 5.11.3: Enabling Raspberry Pi Interfaces using Device Tree
• 5.12: Deploying a Containerized Application in Photon OS
• 5.13: Compatible Cloud Images
• 6: Administration Guide
• 6.1: Photon OS Packages
• 6.1.1: Examining the Packages in the SPECS Directory on Github
• 6.1.2: Looking at the Differences Between the Minimal and the Full Version
• 6.1.3: The Root Account and the 'sudo' and 'su' Commands
• 6.1.4: Examining Signed Packages
• 6.1.5: Photon OS Package Repositories
• 6.1.6: Building a Package from a Source RPM
• 6.1.7: Compiling C++ Code on the Minimal Version of Photon OS
• 6.2: Package Management in Photon OS with 'tdnf'
• 6.2.1: Introduction to 'tdnf'
• 6.2.2: Configuration Files and Repositories
• 6.2.3: Adding a New Repository
• 6.2.4: Mount the Photon ISO Image for the Photon-ISO Repository
• 6.2.5: Adding the Dev Repository to Get New Packages from the GitHub Dev Branch
• 6.2.6: tdnf-automatic
• 6.2.7: Install Packages from CLI
• 6.2.8: SSL Options
• 6.2.9: Standard Syntax for tdnf Commands
• 6.2.9.1: tdnf Commands
• 6.2.9.2: tdnf Command Options
• 6.3: Managing Services with 'systemd'
• 6.3.1: Viewing Services
• 6.3.2: Controlling Services
• 6.3.3: Creating a Startup Service
• 6.3.4: Disabling the Photon OS httpd.service
• 6.3.5: Installing Sendmail
• 6.3.6: Auditing System Events with auditd
• 6.3.7: Analyzing systemd Logs with journalctl
• 6.3.8: Migrating Scripts to systemd
• 6.4: Configure Wireless Networking
• 6.5: Managing the Network Configuration
• 6.5.1: Commands to Manage Network Service
• 6.5.2: Using the Network Configuration Manager
• 6.5.3: Use 'ip' and 'ss' Commands
• 6.5.4: Configuring Network Interfaces
• 6.5.5: Setting a Static IP Address
• 6.5.6: Turning Off DHCP
• 6.5.7: Adding a DNS Server
• 6.5.8: Setting Up Networking for Multiple NICs
• 6.5.8.1: Combining DHCP and Static IP Addresses with IPv4 and IPv6
• 6.5.9: Clearing the Machine ID of a Cloned Instance for DHCP
• 6.5.10: Using Predictable Network Interface Names
• 6.5.11: Inspecting the Status of Network Links with 'networkctl'
• 6.5.12: Turning On Network Debugging
• 6.5.13: Installing packages for 'tcpdump' and 'netcat'
• 6.5.14: Mounting a Network File System
• 6.5.15: Network Configuration Manager - C API
• 6.5.16: Network Configuration Manager - Python API
• 6.6: Prioritize eth0 Route Over WLAN
• 6.7: Configuring Photon Real-Time Operating System for Real-Time Applications
• 6.8: Containers
• 6.8.1: Docker Containers
• 6.8.2: Kubernetes
• 6.8.3: Support for distributed builds using Kubernetes
• 6.9: Changing the Locale
• 6.10: Cloud-Init on Photon OS
• 6.10.1: Cloud-Init Overview
• 6.10.2: Deploy Photon OS With 'cloud-init'
• 6.10.3: Customizing Guest OS using Cloud-Init
• 6.10.4: Creating a Stand-Alone Photon Machine With cloud-init
• 6.10.5: Customizing a Photon OS Machine on EC2
• 6.10.6: Running a Photon OS Machine on GCE
• 6.11: Security Policy
• 6.11.1: Default Firewall Settings
• 6.11.2: Default Permissions and umask
• 6.11.3: Disabling TLS 1.0 to Improve Transport Layer Security
• 6.12: Support for zstd Compression
• 6.13: Photon RPM OSTree: a simple guide
• 6.13.1: Introduction
• 6.13.2: Installing a host against default server repository
• 6.13.3: Concepts in Action
• 6.13.4: Querying For Commit File and Package Metadata
• 6.13.5: Host Updating Operations
• 6.13.6: Creating a Server
• 6.13.7: Installing a Photon RPM-OStree host against a custom server repository
• 6.13.8: Automatic Updates
• 6.13.9: File Oriented Server Operations
• 6.13.10: Package Oriented Server Operations
• 6.13.11: Remotes
• 6.13.12: Running container applications between bootable images
• 6.13.13: Install or rebase to Photon OS 4.0
• 6.14: Support for SELinux
• 6.15: Remotely Upgrading a Photon OS Machine
• 6.15.1: Remotely Update a Single Photon OS Machine With Photon Management Daemon
• 6.15.2: Remotely Upgrade Multiple Photon OS Machines With Photon Management Daemon
• 6.16: Photon Management Daemon
• 6.16.1: Installing the pmd Package
• 6.16.2: Available APIs
• 7: User Guide
• 7.1: Setting Up Network PXE Boot
• 7.2: Kickstart Support in Photon OS
• 7.3: Kubernetes on Photon OS
• 7.3.1: Prerequisites
• 7.3.2: Running Kubernetes on Photon OS
• 7.3.2.1: System Information
• 7.3.2.2: Prepare the Hosts
• 7.3.2.3: Configure Kubernetes Services on the Master
• 7.3.2.4: Configure the Kubernetes services on Node
• 7.4: Photon NFS Utilities for Mounting Remote File Systems
• 8: Command-Line Reference
• 8.1: Command-line Interfaces
• 8.1.1: Photon Management Daemon Command-line Interface (pmd-cli)
• 8.1.2: Photon Network Config Manager Command-line Interface (nmctl)
• 8.1.3: Photon Real-Time Operating System Command-line Interface
• 9: Troubleshooting Guide
• 9.1: Introduction
• 9.1.1: Systemd and TDNF
• 9.1.2: The Root Account and the `sudo` and `su` Commands
• 9.1.3: Checking the Version and Build Number
• 9.1.4: General Best Practices
• 9.1.5: Photon OS Logs
• 9.1.6: Troubleshooting Progression
• 9.2: Solutions to Common Problems
• 9.2.1: Boot in Emergency Mode
• 9.2.2: Resetting a Lost Root Password
• 9.2.3: Fixing Permissions on Network Config Files
• 9.2.4: Permitting Root Login with SSH
• 9.2.5: Fixing Sendmail
• 9.3: Photon OS General Troubleshooting
• 9.3.1: Photon Code
• 9.3.2: Package Management
• 9.3.3: Network Configuration
• 9.3.4: Cloud-init
• 9.3.5: Open-vm-tools/Vmtoolsd
• 9.4: Troubleshooting Tools
• 9.4.1: Common Tools
• 9.4.2: Troubleshooting Tools Installed by Default
• 9.4.3: Installing Tools from Repositories
• 9.4.4: Linux Troubleshooting Tools
• 9.5: Systemd
• 9.5.1: Enabling 'systemd' Debug Shell During Boot
• 9.5.2: Troubleshooting Services With 'systemctl'
• 9.5.3: Analyzing System Logs with 'journalctl'
• 9.5.4: Inspecting Services with 'systemd-analyze'
• 9.5.5: Inspecting Services with 'systemd-analyze'
• 9.6: Network Troubleshooting
• 9.6.1: Managing the Network Configuration
• 9.6.2: Inspecting IP Addresses
• 9.6.3: Inspecting the Status of Network Links with 'networkctl'
• 9.6.4: Network Debugging
• 9.6.5: Checking Firewall Rules
• 9.6.6: Inspect Network Settings with 'netmgr'
• 9.7: File System Troubleshooting
• 9.7.1: Checking Disk Space
• 9.7.2: Adding a Disk and Partitioning It
• 9.7.3: Expanding Disk Partition
• 9.7.4: List Disk Partitions with 'fdisk'
• 9.7.5: File System Consistency Check Tool
• 9.7.6: Fixing File System Errors When fsck Fails
• 9.8: Troubleshooting Packages
• 9.9: Kernel Problems and Boot and Login Errors
• 9.9.1: Kernel Overview
• 9.9.2: Boot Process Overview
• 9.9.3: Blank Screen on Reboot
• 9.9.4: Investigating Unexpected Behavior
• 9.9.5: Investigating the Guest Kernel
• 9.9.6: Kernel Log Replication with VProbes
• 9.9.7: Linux Kernel
• 9.10: Performance Issues
• 9.10.1: General Performance Guidelines
• 9.10.2: Throughput Performance
• 10: 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 4 Rev2

Photon OS 4.0 Rev2 supports OpenSSL 3.0.0, RPM packages 4.16.1.3, eBPF, GNU tarfs. This release adds critical updates to the base OS packages. The release also includes installer improvements, Photon Real-Time OS performance improvements, tdnf upgrade, and the implementation of the pmd-nextgen package. This topic summarizes what’s new and different in Photon OS 4.0 Rev2.

New Features

• OpenSSL 3.0.0 : In Photon OS 4.0 Rev2, the default OpenSSL version is 3.0.0. To support OpenSSL 3.0.0, all the dependent packages are updated and published.

• pmd-nextgen: The pmd-nextgen package introduces the photon-mgmtd tool. Use photon-mgmtd to manage systems, networks, services, and applications. photon-mgmtd features a plugin-based architecture with platform-independent APIs that you can use for remote access, performance analysis, configuration, and health monitoring.

• tdnf: In Photon OS 4.0 Rev2, tdnf is updated to version 3.2.3. This version of tdnf includes bug fixes and new features such as the repoquery command. Use of the metalink library has been deprecated. For more information about the features in version 3.2.3 refer to the following link: tdnf Releases

• Installer: In Photon OS 4.0 Rev2, the following enhancements are added to the installer:

  • Support for Kickstart files in secondary devices.
  • Support for a user-specified mount media to boot the operating system.

• Photon Real-Time Operating System: The Photon Real-Time Operating System is improved with lower latency and reduced operating system jitters. Other improvements include better stability of the real-time applications and enhanced application-debugging capability.

• eBPF: Support for eBPF in the Linux kernel is added.

• GNU tarfs: Support for GNU tarfs in Linux-ESX kernel is added.

Package and Binary Maintenance

• Cloud-ready images for rapid deployment on Microsoft Azure (new), Google Compute Engine (GCE), Amazon Elastic Compute Cloud (EC2), and VMware products (vSphere, Fusion, and Workstation)

• Critical updates to the following base OS packages:

  • Linux kernel 5.10.83
  • Glibc 2.32
  • systemd 247.10
  • Python3 3.10.0
  • Openjdk : 11.0.9
  • Openssl : 3.0.0
  • Cloud-init: 21.4

• RPM packages are updated to version 4.16.1.3 with SQLite as the default database.

• Critical updates for most packages available in the repo.

3 - What is New in Photon OS 4

Photon OS 4.0 provides support for the Real Time flavor of kernel linux-rt, SELinux , installer improvements, PMD role management improvements and critical updates to OSS packages including linux kernel, systemd, and glibc. This topic summarizes what’s new and different in Photon OS 4.0.

New Features

• Photon OS 4.0 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 4.0 supports several userspace packages such as tuned, tuna, stalld etc., 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).

• SELinux is an implementation of mandatory access controls (MAC) on Linux. Photon OS 4.0 provides an opportunity for the appliance to enable SElinux, either in Permissive or Enforcement mode. Photon OS ships will also include a default policy which the appliance can choose to customise depending on their needs during the build time. Photon also supports SELinux for containers.

• Photon 4.0 brings out a completely revamped network configuration management library. It is a totally new avatar of the previous netmgr and has been developed with the goal of providing a set of APIs for common tasks such as configuring IP addresses, network routes, interface states, DNS, etc. This allows the user to configure the network on a Photon OS through simpler API calls that handle much of the complexity of configuring the network, which the user would have to do if they took the route of directly manipulating the various configuration files.

• Photon OS 4.0 provides support for Raspberry Pi 4.

• OVA and AMI images for ARM architecture are available in Photon OS 4.0.

• In tdnf, support is added for the following:

  1. Validation of externally configured GPGkeys
  2. tdnf-automatic to allow administrators to configure systems to automatically download and perform updates without manual intervention
  3. Metalink in the tdnf repositories allows configuration of multiple mirrors to download the repository data
  4. Local and remote URL package installation
  5. SSL Options

• The performance of the makecache command in tdnf is improved in Photon OS 4.0. To improve the performance of the makecache command, the update RPM repository is split into the following repositories for both the architectures:

  1. photon_updates_4.0_<architecture>
  2. photon_4.0_<architecture>

  photon_updates_4.0_<architecture> repository contains all the latest versions of the updated RPMs and is enabled by default. photon_4.0_<architecture> contains all the previous versions of the updated RPMs and is disabled by default. The users can enable this repository by specifying the enablerepo option in tdnf command if they wish to consume a previous version.

Installer and Build System Updates

• Support for distributed builds using Kubernetes
• Availability of Photon OS installer as RPM
• Support for multiple disks in image builder
• Support for untrusted (self-signed) HTTPS in kickstart ISO installation
• zstd as the default compression mechanism for RPM

Package and Binary Maintenance

• Cloud-ready images for rapid deployment on Microsoft Azure (new), Google Compute Engine (GCE), Amazon Elastic Compute Cloud (EC2), and VMware products (vSphere, Fusion, and Workstation)
• Critical updates to the following base OS packages:
  • Linux kernel 5.10 LTS
  • Glibc 2.32
  • systemd 247
  • Python3 3.9
  • Openjdk : 1.8.0.265, 11.0.9
  • Openssl : 1.1.1
  • Cloud-init: 20.4.1
  • GCC: 10.2.0
• Up-to-date versions for most packages available in the repository.

Notes

Openjdk 1.10 is end of life and is being shipped to serve the sole purpose of build dependency. There will no future updates - Updates to security or otherwise will be done to the openjdk10 package.

4 - Overview

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

Product version: 4.0

This documentation applies to all 4.0.x releases.

Intended Audiences

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

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

4.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 4.0 supports several userspace packages such as tuned, tuna, stalld etc., 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).

5 - Installation Guide

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

Product version: 4.0

This documentation applies to all 4.0.x releases.

Intended Audiences

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

5.1 - Downloading Photon OS

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

Download Formats

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

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.

5.2 - Upgrading to Photon OS 4.0

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

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

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

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

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

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

3. Install photon-upgrade package

   # tdnf -y install photon-upgrade
   

4. Run the upgrade script

   # photon-upgrade.sh --upgrade-os
   

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

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

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

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

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

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

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

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

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

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

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

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

5.3.7 - View Build Logs

You can view build logs at the following location:

$HOME/workspaces/photon/stage/LOGS

5.4 - Building Package or Kernel Modules Using a Script

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

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

Result: You have a native Photon OS RPM package.

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

• Prerequisites
• Procedure
• Example
• Build Logs

Prerequisites

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

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

Procedure

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

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

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

Example

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

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

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

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

%description
Example of building linux module for Photon OS

%prep
%setup -q -n module_example

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

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

%post
/sbin/depmod -a

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

Build Logs

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

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

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

5.5 - Running Photon OS on vSphere

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

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

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

5.5.2 - Importing the OVA for Photon OS 4.0

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

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

1. Start the Import Process

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

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

   

   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.

5.5.3 - Installing the ISO Image for Photon OS 4.0

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

1. Upload the ISO Image

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

2. Create a new VM

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

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

   

   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.

5.6 - Running Photon OS on Fusion

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

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

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

5.6.2 - Importing the OVA for Photon OS 4.0

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

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

1. Start the Import Process

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

   

   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 (13 or 11) that you want to use. Upgrade if you need to use devices supported only in hardware version 13. Don’t upgrade if you want to be compatible with older tools that are supported in hardware version 11.

5. Update Login Credentials

   

   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.

5.6.3 - Installing the ISO Image for Photon OS 4.0

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

1. Start the Installation Process

   From the File menu, choose New.

   

   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.

5.7 - Running Photon OS on Workstation

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

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

5.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/4.0/GA/).

   
   

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

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

   

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

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

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

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

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

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

   For instructions, see Downloading Photon OS.

5.7.2 - Importing the OVA for Photon OS 4.0

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

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

1. Start the Import Process

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

   

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.

5.7.3 - Installing the ISO Image for Photon OS 4.0

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

1. Start the Installation Process

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

   

   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.

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

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

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

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

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

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

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

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

5.9.2 - Set Up Azure Storage and Uploading the VHD

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

Setting Up Using the Azure Portal

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

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

Setting Up Using the Azure CLI

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

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

1. Create a resource group.

   From the Azure CLI, create a resource group.

   az group create \
    --name <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

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

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

5.10.1 - Prerequisites for Running Photon OS on GCE

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

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

Google Compute Engine Account

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

GCE Tools

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

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

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

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

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

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

Photon OS Image

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

For instructions, see Downloading Photon OS.

Optionally you can customize Photon OS to work with GCE.

Creating Photon image for GCE

Perform the following tasks:

1. Prepare Photon Disk

   1. Install Photon Minimal on Fusion/Workstation and install some required packages.

   mount /dev/cdrom /media/cdrom
   tdnf install python2-libs ntp sudo wget tar which gptfdisk sed findutils grep gzip -y
   

2. Convert GPT to MBR and update Grub

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

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

3. Install Google Cloud SDK and GCE Packages

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

4. Update /etc/hosts file with GCE values as follows:

   echo "169.254.169.254 metadata.google.internal metadata" >> /etc/hosts
   

5. Remove all servers from ntp.conf and add Google’s ntp server.

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

6. Set UTC timezone

   ln -sf /usr/share/zoneinfo/UTC /etc/localtime
   

7. Update /etc/resolv.conf

   echo "nameserver 8.8.8.8" >> /etc/resolv.conf
   

8. Remove ssh host keys and add script to regenerate them at boot time.

   rm /etc/ssh/ssh_host_*
   # Depending on the installation, you may need to purge the following keys
   rm /etc/ssh/ssh_host_rsa_key*
   rm /etc/ssh/ssh_host_dsa_key*
   rm /etc/ssh/ssh_host_ecdsa_key*
   
   sed -i -e "/exit 0/d" /etc/rc.local
   echo "[ -f /etc/ssh/ssh_host_key ] && echo 'Keys found.' || ssh-keygen -A" >> /etc/rc.local
   echo "exit 0" >> /etc/rc.local
   printf "GOOGLE\n" > /etc/ssh/sshd_not_to_be_run
   
   # Edit sshd_config and ssh_config as per instructions on [this link](https://cloud.google.com/compute./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"
    

5.10.2 - Installing Photon OS on Google Compute Engine

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

Perform the following steps:

1. Create a New Bucket

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

   

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.

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

5.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/4.0/GA/rpi/rpi.tar.xz.

      For instructions, see Downloading Photon OS.

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

5.11.3 - Enabling Raspberry Pi Interfaces using Device Tree

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

SPI Interface: Execute following commands to enable SPI Interface:

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

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

Audio Interface: Execute following commands to enable Audio Interface:

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

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

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

I2C Interface: Execute following command to enable I2C Interface:

modprobe i2c-dev

#Customizing Device Tree Overlay

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

tdnf install dtc

Execute following command to compile the overlay:

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

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

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

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

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

This documentation applies to all 4.0.x releases.

Intended Audiences

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

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

6.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, the version of OpenJDK, which contains the openjre package that installs the Java class library and the javac Java compiler appears as follows:

%define _use_internal_dependency_generator 0
Summary:	OpenJDK 
Name:		openjdk
Version:	1.8.0.72
Release:	1%{?dist}
License:	GNU GPL
URL:		https://openjdk.java.net
Group:		Development/Tools
Vendor:		VMware, Inc.
Distribution:   Photon
AutoReqProv: 	no
Source0:	http://anduin.linuxfromscratch.org/files/BLFS/OpenJDK-%{version}/OpenJDK-%{version}-x86_64-bin.tar.xz
%define sha1 OpenJDK=0c705d7b13f4e22611d2da654209f469a6297f26
%description
The OpenJDK package installs java class library and javac java compiler. 

%package	-n openjre
Summary:	Jave runtime environment
AutoReqProv: 	no
%description	-n openjre
It contains the libraries files for Java runtime environment
#%global __requires_exclude ^libgif.*$
#%filter_from_requires ^libgif.*$...

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

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

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

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

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 /home/steve/workspace/photon/stage/SRPMS/kubernetes-1.1.8-4.ph1.src.rpm
/home/steve/workspace/photon/stage/SRPMS/kubernetes-1.1.8-4.ph1.src.rpm: sha1 md5 OK

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

rpm -Kv /home/steve/workspace/photon/stage/SRPMS/kubernetes-1.1.8-4.ph1.src.rpm
/home/steve/workspace/photon/stage/SRPMS/kubernetes-1.1.8-4.ph1.src.rpm:
Header SHA1 digest: OK (89b55443d4c9f67a61ae0c1ec9bf4ece2d6aa32b)
        MD5 digest: OK (51eee659a8730e25fd2a52aff9a6c2c2)

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

6.1.5 - Photon OS Package Repositories

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

ls /etc/yum.repos.d/
photon-extras.repo
photon-iso.repo
photon-updates.repo
photon.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 main Photon OS repository (photon.repo) contains all the packages that are built from the ISO or from another source. This repository points to a static batch of packages and spec files at the point of a release.

The updates repository (photon-updates.repo) is irrelevant to a major release until after the release is installed. Thereafter, the updates repository holds the updated packages for that release. The repository points to updates for the installed version, such as a version of Kubernetes that supersedes the version installed during the major release.

The Photon extras repository (photon-extras.repo) holds Likewise Open, an open source authentication engine, and other VMware software that you can add to Photon OS for free. Photon OS supports but does not build the packages in the extras repository.

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

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

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

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

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

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

baseurl=https://https://packages.vmware.com/photon/
metalink=http://example.com/*username*/metalink/metalink
gpgkey=file:///etc/pki/rpm-gpg/VMWARE-RPM-GPG-KEY
gpgcheck=1
enabled=1
skip_if_unavailable=True

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

• By using metalink, you can point to multiple URLs to download the repomd.xml file. 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 due to any reason, tdnf will sync to the next mirror url with the lower preference than before one.

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

• The gpgcheck setting specifies whether to check the GPG signature.

• 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 will be checked for the metadata signatures. The default value is 0. 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

• The enabled setting tells tdnf whether to poll the repository. If enabled is set to 1, tdnf polls it; if it is set to 0, tdnf ignores it.

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

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

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

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

6.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/4.0/photon_release_4.0_x86_64/x86_64/open-vm-tools-11.2.5-1.ph4.x86_64.rpm
  
    open-vm-tools-11.2.5-1.ph4.x86_64.rpm 763014   100%
  
    Installing:
  
    attrx86_642.4.48-1.ph4  photon  88.65k 90778
  
    nss x86_643.57-2.ph4photon  1.69M 1768005
  
    ...
  
    open-vm-tools   x86_6411.2.5-1.ph4  @cmdline2.65M 2779392
  
  
    Total installed size:  91.57M 96019175
  
  
    Upgrading:
  
    nss-libsx86_643.57-2.ph4photon  2.48M 2601790
  
    util-linux-libs x86_642.36-2.ph4photon752.75k 770816
  
    pcre-libs   x86_648.44-2.ph4photon275.60k 282216
  
  
  
    Total installed size:   3.49M 3654822
  
    Is this ok [y/N]: 
  

• Using a file:

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

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

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

6.2.9.1 - tdnf Commands

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

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

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.

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

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.

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

OPTION                     DESCRIPTION
--allowerasing             Allow erasing of installed packages to resolve dependencies
--assumeno                 Answer no for all questions
--best                     Try the best available package versions in transactions
--debugsolver              Dump data aiding in dependency solver debugging info.
--disablerepo=<repoid>     Disable specific repositories by an id or a glob.
--enablerepo=<repoid>      Enable specific repositories
-h, --help                 Display help
--refresh                  Set metadata as expired before running command
--nogpgcheck               Skip gpg check on packages
--rpmverbosity=<debug level name>
                           Debug level for rpm
--version                  Print version and exit
-y, --assumeyes            Answer yes to all questions
-q, --quiet                Quiet operation
--downloadonly             Enables you to download the packages and dependencies that are
                           not installed to the cache.
--downloaddir=dir          Downloads the packages to the specified directory 

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

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

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

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

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

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

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

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

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

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

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

6.5 - Managing the Network Configuration

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

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

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

For more information, see:

• CLI - see the -net commands in the Photon Management Daemon Command-line Interface (pmd-cli)
• C APIs - Network Configuration Manager - C API
• Python APIs - Network Configuration Manager - Python API

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

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

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

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

(ens33 is an example)

    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 fedora systemd-networkd[650]: ens33: Link UP
    Feb 26 10:19:44 fedora systemd-networkd[650]: ens33: Gained carrier
    Feb 26 10:19:45 fedora systemd-networkd[650]: ens33: DHCPv4 address 172.16.85.225/24 via 172.16.85.2
    Feb 26 10:19:46 fedora systemd-networkd[650]: ens33: Gained IPv6LL

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

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

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

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

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

6.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 fedora systemd-networkd[650]: ens33: Link UP
Feb 26 10:19:44 fedora systemd-networkd[650]: ens33: Gained carrier
Feb 26 10:19:45 fedora systemd-networkd[650]: ens33: DHCPv4 address 172.16.85.225/24 via 172.16.85.2
Feb 26 10:19:46 fedora 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.

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

   mkdir -p /etc/systemd/system/systemd-networkd.service.d/
   

2. Run the following command as root to establish a systemd drop-in unit with a debugging configuration for the network service:

   cat > /etc/systemd/system/systemd-networkd.service.d/override.conf
   	[Service]
   	Environment=SYSTEMD_LOG_LEVEL=debug
   	EOF
   

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
   

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

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

6.5.15 - Network Configuration Manager - C API

Photon OS provides a C API for the Network Configuration Manager.

• About the Network Configuration Manager C API
• Interface Configuration APIs
• IP Address Configuration APIs
• Route Configuration APIs
• DNS Configuration APIs
• DHCP Options DUID and IAID Configuration APIs
• NTP Configuration APIs
• Service Management APIs

About the Network Configuration Manager C API

Use the Network Configuration Manager C API to simplify common network configuration tasks for:

• interfaces
• IP addresses (IPv4 and IPv6 addresses)
• routes
• DNS server and domain settings
• DHCP DUID and IAID settings
• NTP server settings
• service management
• object parameters (interfaces and files)

Header File

Header files for all the C APIs are defined in the following location:

https://github.com/ vmware /pmd/tree/master/include

To install the Network Configuration Manager header file, run the following command:

tdnf install netmgmt-devel n Once installed, you can reference the header file in the following location:

/usr/include/netmgmt/network-config-manager.h

Freeing Memory

For all get APIs that take a pointer-to-pointer parameter, the caller has the responsibility to free the memory upon successful response from API by calling free().

Error Codes

All C API calls return 0 for success, or one of the following error codes for failure.

• 4097 - NM_ERR_INVALID_PARAMETER
• 4098 - NM_ERR_NOT_SUPPORTED
• 4099 - NM_ERR_OUT_OF_MEMORY
• 4100 - NM_ERR_VALUE_NOT_FOUND
• 4101 - NM_ERR_VALUE_EXISTS
• 4102 - NM_ERR_INVALID_INTERFACE
• 4103 - NM_ERR_INVALID_ADDRESS
• 4104 - NM_ERR_INVALID_MODE
• 4105 - NM_ERR_BAD_CONFIG_FILE
• 4106 - NM_ERR_WRITE_FAILED
• 4107 - NM_ERR_TIME_OUT
• 4108 - NM_ERR_DHCP_TIME_OUT

Use nm_get_error_info to retrieve information about an error code.

 const char \*
 nm_get_error_info(
     uint32_t nmErrCode
 );``

Interface Configuration APIs

The Photon OS network manager C API enables you to manage network interfaces.

Structure Declarations

Link Mode

Description

Link mode. Available settings:

• LINK_AUTO - the specified interface is managed and configured by systemd network manager
• LINK_MANUAL - systemd will not bring up or configure the specified interface
• LINK_MODE_UNKNOWN - the link mode is unknown

Declaration

 typedef enum _NET_LINK_MODE
 {
     LINK_AUTO = 0,
     LINK_MANUAL,
     LINK_MODE_UNKNOWN
 } NET_LINK_MODE;``

Link State

Description

Link state. Available settings:

• LINK_DOWN - the link is being administratively down or has no carrier signal
• LINK_UP - the link is configured up and has carrier signal
• LINK_STATE_UNKNOWN - link state is unknown

Declaration

 typedef enum _NET_LINK_STATE
 {
     LINK_DOWN = 0,
     LINK_UP,
     LINK_STATE_UNKNOWN,
 } NET_LINK_STATE;

Link Information

Description

Link information. Includes the following information:

• pszInterfaceName - interface name
• pszMacAddress - interface hardware address specified in a colon-separated format (for example: “00:0c:29:99:a5:7b”)
• mtu - maximum transmission unit (MTU)
• mode - link mode (see above)
• state - link state (see above)

Declaration

 typedef struct _NET_LINK_INFO
 {
     struct _NET_LINK_INFO \*pNext;
     char \*pszInterfaceName;
     char \*pszMacAddress;
     uint32_t mtu;
     NET_LINK_MODE mode;
     NET_LINK_STATE state;
 } NET_LINK_INFO, \*PNET_LINK_INFO;

nm_set_link_mac_addr

Description

Set the MAC address of the interface.

Declaration

uint32_t

nm_set_link_mac_addr(

     const char \*pszInterfaceName,
     const char \*pszMacAddress
 );

Arguments

• pszInterfaceName - interface name
• pszMacAddress - interface hardware address specified in a colon-separated format (for example: “00:0c:29:99:a5:7b”)

Returns

• success: 0
• failure: error code

nm_get_link_mac_addr

Description

Get the MAC address of the interface.

Declaration

uint32_t
 nm_get_link_mac_addr(
     const char \*pszInterfaceName,
     char \*\*ppszMacAddress
 );

Arguments

• pszInterfaceName - interface name
• ppszMacAddress - interface hardware address specified in a colon-separated format (for example: “00:0c:29:99:a5:7b”)

Returns

• success: 0
• failure: error code

nm_set_link_mode

Description

Set the mode of the interface (auto or manual).

Declaration

uint32_t
 nm_set_link_mode(
     const char \*pszInterfaceName,
     NET_LINK_MODE mode
 );

Arguments

• pszInterfaceName - interface name
• mode - link mode. One of the following values:
  • LINK_AUTO - the specified interface is managed and configured by systemd network manager
  • LINK_MANUAL - systemd will not bring up or configure the specified interface
  • LINK_MODE_UNKNOWN - the link mode is unknown

Returns

• success: 0
• failure: error code

nm_get_link_mode

Description

Get the mode of the interface (auto or manual).

Declaration

uint32_t
 nm_get_link_mode(
     const char \*pszInterfaceName,
     NET_LINK_MODE \*pLinkMode
 );

Arguments

• pszInterfaceName - interface name
• pLinkMode - link mode. One of the following values:
  • LINK_AUTO - the specified interface is managed and configured by systemd network manager
  • LINK_MANUAL - systemd will not bring up or configure the specified interface
  • LINK_MODE_UNKNOWN - the link mode is unknown

Returns

• success: 0
• failure: error code

nm_set_link_mtu

Description

Set the maximum transmission unit (MTU) of the interface.

Declaration

uint32_t
 nm_set_link_mtu(
     const char \*pszInterfaceName,
     uint32_t mtu
 );

Arguments

• pszInterfaceName - interface name
• mtu - maximum transmission unit (MTU)

Returns

• success: 0
• failure: error code

nm_get_link_mtu

Description

Get the maximum transmission unit (MTU) of the interface.

Declaration

nm_get_link_mtu
 uint32_t
 nm_get_link_mtu(
     const char \*pszInterfaceName,
     uint32_t \*pMtu
 );

Arguments

• pszInterfaceName - interface name
• pMtu - maximum transmission unit (MTU)

Returns

• success: 0
• failure: error code

nm_set_link_state

Description

Set the link state of the interface (up or down).

Declaration

 uint32_t
 nm_set_link_state(
     const char \*pszInterfaceName,
     NET_LINK_STATE state
 );

Arguments

• pszInterfaceName - interface name
• state - link state. One of the following values:
  • LINK_DOWN - the link is being administratively down or has no carrier signal.
  • LINK_UP - the link is configured up and has carrier signal.
  • LINK_STATE_UNKNOWN - the link state is unknown

Returns

• success: 0
• failure: error code

nm_get_link_state

Description

Get the link state of the interface (up or down).

Declaration

uint32_t
 nm_get_link_state(
     const char \*pszInterfaceName,
     NET_LINK_STATE \*pLinkState
 );

Arguments

• pszInterfaceName - interface name
• pLinkState - link state. One of the following values:
  • LINK_DOWN - the link is being administratively down or has no carrier signal
  • LINK_UP - the link is configured up and has carrier signal
  • LINK_STATE_UNKNOWN - the link state is unknown

Returns

• success: 0
• failure: error code

nm_ifup

Description

Set the specified interface state to UP. Additionally, if the interface is configured to have an IP address, it waits for the interface to acquire the IP address, and then updates neighbors of its IP address via the address resolution protocol (ARP) messages.

Declaration

 uint32_t
 nm_ifup(
     const char \*pszInterfaceName
 );

Arguments

• pszInterfaceName - interface name

Returns

• success: 0
• failure: error code

nm_ifdown

Description

Set the specified interface state to DOWN.

Declaration

uint32_t
 nm_ifdown(
     const char \*pszInterfaceName
 );

Arguments

• pszInterfaceName - interface name

Returns

• success: 0
• failure: error code

nm_get_link_info

Description

Get link information for the interface. The caller is responsible for freeing ppLinkInfo by calling nm_free_link_info.

Declaration

uint32_t
 nm_get_link_info(
     const char \*pszInterfaceName,
     NET_LINK_INFO \*\*ppLinkInfo
 );

Arguments

• pszInterfaceName - interface name
• ppLinkInfo, which includes the following information:
  • *pszInterfaceName - interface name
  • *pszMacAddress - interface hardware address specified in a colon-separated format (for example: “00:0c:29:99:a5:7b”)
  • mtu - maximum transmission unit (MTU)
  • mode - One of the following values:
    • LINK_AUTO - the specified interface is managed and configured by systemd network manager
    • LINK_MANUAL - systemd will not bring up or configure the specified interface
    • LINK_MODE_UNKNOWN - the link mode is unknown
  • state - One of the following values:
    • LINK_DOWN - the link is being administratively down or has no carrier signal
    • LINK_UP - the link is configured up and has carrier signal
    • LINK_STATE_UNKNOWN - the link state is unknown

Returns

• success: 0
• failure: error code

nm_free_link_info

Description

Frees the NET_LINK_INFO structure returned by a successful nm_get_link_info call.

Declaration

void
 nm_free_link_info(
     NET_LINK_INFO \*pNetLinkInfo
 );

Arguments

• pNetLinkInfo, which includes the following information:
  • *pszInterfaceName - interface name
  • *pszMacAddress - interface hardware address specified in a colon-separated format (for example: “00:0c:29:99:a5:7b”)
  • mtu - maximum transmission unit (MTU)
  • mode - One of the following values:
    • LINK_AUTO - the specified interface is managed and configured by systemd network manager
    • LINK_MANUAL - systemd will not bring up or configure the specified interface
    • LINK_MODE_UNKNOWN - the link mode is unknown
  • state - One of the following values:
    • LINK_DOWN - the link is being administratively down or has no carrier signal
    • LINK_UP - the link is configured up and has carrier signal
    • LINK_STATE_UNKNOWN - the link state is unknown

Returns

• success: 0
• failure: error code

IP Address Configuration APIs

The Photon OS network manager C API enables you to manage IP addresses for interfaces that are managed by systemd network manager.

Structure Declarations

IP Address Mode

Description

Defines the IP address mode. One of the following values:

• IPV4_ADDR_MODE_NONE - no IPv4 address configured on the interface
• IPV4_ADDR_MODE_STATIC - the interface is configured with a static IPv4 address
• IPV4_ADDR_MODE_DHCP - the interface is configured with a DHCP IPv4 address

Declaration

 typedef enum _NET_IPV4_ADDR_MODE
 {
     IPV4_ADDR_MODE_NONE = 0,
     IPV4_ADDR_MODE_STATIC,
     IPV4_ADDR_MODE_DHCP,
     IPV4_ADDR_MODE_MAX
 } NET_IPV4_ADDR_MODE;

Address Type

Description

Defines the type of IP address. One of the following options:

• STATIC_IPV4 - static IPv4 address
• STATIC_IPV6 - static IPv6 address
• DHCP_IPV4 - DHCP IPv4 address
• DHCP_IPV6 - DHCP IPv6 address
• AUTO_IPV6 - stateless dynamic IPv6 address
• LINK_LOCAL_IPV6 - link local IPv6 address

Declaration

 typedef enum _NET_ADDR_TYPE
 {
     STATIC_IPV4        =  0x00000001,
     STATIC_IPV6        =  0x00000002,
     DHCP_IPV4          =  0x00000010,
     DHCP_IPV6          =  0x00000020,
     AUTO_IPV6          =  0x00000040,
     LINK_LOCAL_IPV6    =  0x00000080,
 } NET_ADDR_TYPE;

IP Addresses

Description

Defines IP addresses.

• pszInterfaceName - interface name
• type - address type
• pszIPAddrPrefix - IP address

Declarations

 typedef struct _NET_IP_ADDR
 {
     char \*pszInterfaceName;
     NET_ADDR_TYPE type;
     char \*pszIPAddrPrefix;
 } NET_IP_ADDR, \*PNET_IP_ADDR;

nm_set_ipv4_addr_gateway

Description

Set the IPv4 address and (optionally) the default gateway address for the interface.

Declaration

 uint32_t

 nm_set_ipv4_addr_gateway(

     const char \*pszInterfaceName,
     NET_IPV4_ADDR_MODE mode,
     const char \*pszIPv4AddrPrefix,
     const char \*pszIPv4Gateway
 );

Arguments

• pszInterfaceName - interface name
• mode - IP address mode; one of the following values:
  • IPV4_ADDR_MODE_NONE
  • IPV4_ADDR_MODE_STATIC
  • IPV4_ADDR_MODE_DHCP
• pszIPv4AddrPrefix - IPv4 address specified in dot-decimal / prefix notation (for example, 10.10.10.101/23). If the prefix is not specified, then a /32 prefix is assumed.
• pszIPv4Gateway - IPv4 gateway (optional) specified in the dot-decimal format (for example,10.10.20.30).

Returns

• success: 0
• failure: error code

nm_get_ipv4_addr_gateway

Description

Get the IPv4 address and the default gateway address for the interface.

Declaration

uint32_t
 nm_get_ipv4_addr_gateway(
     const char \*pszInterfaceName,
     NET_IPV4_ADDR_MODE \*pMode,
     char \*\*ppszIPv4AddrPrefix,
     char \*\*ppszIPv4Gateway
 );

Arguments

• pszInterfaceName - interface name
• pmode - IP mode; one of the following values:
  • IPV4_ADDR_MODE_NONE
  • IPV4_ADDR_MODE_STATIC
  • IPV4_ADDR_MODE_DHCP
• ppszIPv4AddrPrefix - IPv4 address returned in dot-decimal / prefix notation (for example, 10.10.10.101/23). If the prefix is not specified, then a /32 prefix is assumed.
• ppszIPv4Gateway - IPv4 gateway (optional) returned in the dot-decimal format (for example,10.10.10.250).

Returns

• success: 0
• failure: error code

nm_add_static_ipv6_addr

Description

Add an IPv6 address to the specified interface.

Declaration

uint32_t
 nm_add_static_ipv6_addr(
     const char \*pszInterfaceName,
     const char \*pszIPv6AddrPrefix
 );

Arguments

• pszInterfaceName - interface name
• pszIPv6AddrPrefix - IPv6 address specified in the standard colon-separated IPv6 address format followed by the prefix (for example, 2010:a1:b2::25/64). If the not prefix is specified, then a /128 prefix is assumed.

Returns

• success: 0
• failure: error code

nm_delete_static_ipv6_addr

Description

Delete a static IPv6 address from the interface.

Declaration

uint32_t
 nm_delete_static_ipv6_addr(
     const char \*pszInterfaceName,
     const char \*pszIPv6AddrPrefix
 );

Arguments

• pszInterfaceName - interface name
• pszIPv6AddrPrefix - IPv6 address specified in the standard colon-separated IPv6 address format followed by the prefix (for example, 2010:a1:b2::25/64). If the not prefix is specified, then a /128 prefix is assumed.

Returns

• success: 0
• failure: error code

nm_set_ipv6_addr_mode

Description

Set the mode for the interface.

Declaration

uint32_t
 nm_set_ipv6_addr_mode(
     const char \*pszInterfaceName,
     uint32_t enableDhcp,
     uint32_t enableAutoconf
 );

Arguments

• pszInterfaceName - interface name
• enableDhcp - enable (1) or disable (0) DHCP; enabling configures the interface to acquire a DHCP IPv6 address.
• enableAutoconf - enable (1) or disable (0) autoconf; enabling configures the interface to acquire a stateless autoconfiguration IPv6 address.

Returns

• success: 0
• failure: error code

nm_get_ipv6_addr_mode

Description

Get the mode for the interface.

Declaration

 uint32_t
 nm_get_ipv6_addr_mode(
     const char \*pszInterfaceName,
     uint32_t \*pDhcpEnabled,
     uint32_t \*pAutoconfEnabled
 );

Arguments

• pszInterfaceName - interface name
• pDhcpEnabled - returns whether IPv6 DHCP is enabled (1) or disabled (0).
• pAutoconfEnabled - returns whether IPv6 stateless autoconfiguration is enabled (1) or disabled (0).

Returns

• success: 0
• failure: error code

nm_get_ip_addr

Description

Get the IP address for the interface.

Declaration

uint32_t
 nm_get_ip_addr(
     const char \*pszInterfaceName,
     uint32_t addrTypes,
     size_t \*pCount,
     NET_IP_ADDR \*\*\*pppIpAddrList
 );

Arguments

• pszInterfaceName - interface name
• addrTypes - type of IP address; one of the following values:
  • STATIC_IPV4
  • STATIC_IPV6
  • DHCP_IPV4
  • DHCP_IPV6
  • AUTO_IPV6
  • LINK_LOCAL_IPV6
• pCount - number of IP address structures in the pppIpAddrList array returned by the API call.
• pppIpAddrList - array of NET_IP_ADDR elements that includes the following:
  • pszInterfaceName
  • type
  • pszIPAddrPrefix

Returns

• success: 0
• failure: error code

nm_set_ipv6_gateway

Description

Set the default IPv6 gateway for the interface.

Declaration

 uint32_t
 nm_set_ipv6_gateway(
     const char \*pszInterfaceName,
     const char \*pszIPv6Gateway
 );

Arguments

• pszInterfaceName - interface name
• pszIPv6Gateway - IPv6 gateway specified in the standard colon-separated IPv6 address format (for example, 2010:125::100)

Returns

• success: 0
• failure: error code

nm_get_ipv6_gateway

Description

Get the default IPv6 gateway for the interface.

Declaration

 uint32_t
 nm_get_ipv6_gateway(
     const char \*pszInterfaceName,
     char \*\*ppszIPv6Gateway
 );

Arguments

• pszInterfaceName - interface name
• ppszIPv6Gateway - IPv6 gateway specified in the standard colon-separated IPv6 address format (for example, 2010:125::100)

Returns

• success: 0
• failure: error code

Route Configuration APIs

The Photon OS network manager C API enables you to manage static IP routes configuration.

Structure Declarations

Route Scope

Description

Defines the scope of a route. One of the following options.

• GLOBAL_ROUTE - route to a destination one or more hops away
• LINK_ROUTE - route to a destination on the local network
• HOST_ROUTE - route to a destination address on the local host

Declaration

 typedef enum _NET_ROUTE_SCOPE
 {
     GLOBAL_ROUTE = 0,
     LINK_ROUTE,
     HOST_ROUTE,
     NET_ROUTE_SCOPE_MAX
 } NET_ROUTE_SCOPE;

IP Route

Description

Defines an IP route. Includes the following information:

• pszInterfaceName - interface through which the specified destination network can be reached
• pszDestNetwork - destination IP network reached by the specified route
• pszSourceNetwork - source network for the specified route
• pszGateway - IP gateway through which the specified destination network can be reached
• scope - scope of this route entry; one of the following values: GLOBAL_ROUTE, LINK_ROUTE, or HOST_ROUTE as defined above
• metric - metric of this route, an unsigned integer
• table - identifier for the route table to which this route belongs.

Declaration

 typedef struct _NET_IP_ROUTE
 {
     char \*pszInterfaceName;
     char \*pszDestNetwork;
     char \*pszSourceNetwork;
     char \*pszGateway;
     NET_ROUTE_SCOPE scope;
     uint32_t metric;
     uint32_t table;
 } NET_IP_ROUTE, \*PNET_IP_ROUTE;

nm_add_static_ip_route

Description

Add a static IP route.

Declaration

uint32_t
 nm_add_static_ip_route(
     NET_IP_ROUTE \*pRoute
 );

Arguments

• pRoute - static IP route

Returns

• success: 0
• failure: error code

nm_delete_static_ip_route

Description

Delete a static IP route.

Declaration

 uint32_t
 nm_delete_static_ip_route(
     NET_IP_ROUTE \*pRoute
 );

Arguments

• pRoute - static IP route

Returns

• success: 0
• failure: error code

nm_get_static_ip_routes

Description

Get the static IP routes for an interface.

Declaration

 uint32_t
 nm_get_static_ip_routes(
     const char \*pszInterfaceName,
     size_t \*pCount,
     NET_IP_ROUTE \*\*\*pppRouteList
 );

Arguments

• pszInterfaceName - interface name
• pCount - number of NET_IP_ROUTE elements returned in the pppRouteList array by the API call upon success
• pppRouteList - array of static IP routes

Returns

• success: 0
• failure: error code

DNS Configuration APIs

The Photon OS network manager C API enables you to manage the DNS and Domains configuration.

Structure Declarations

DNS Mode

Description

DNS mode. Any of the following values:

• DNS_MODE_INVALID - DNS mode is unknown
• STATIC_DNS - DNS servers are statically configured
• DHCP_DNS - DNS servers configuration is acquired from DHCP protocol.

Declaration

 typedef enum _NET_DNS_MODE
 {
     DNS_MODE_INVALID = 0,
     STATIC_DNS,
     DHCP_DNS,
     DNS_MODE_MAX,
 } NET_DNS_MODE;

nm_set_dns_servers

Description

Set the DNS servers list for the interface.

Declaration

uint32_t
 nm_set_dns_servers(
     const char \*pszInterfaceName,
     NET_DNS_MODE mode,
     size_t count,
     const char \*\*ppszDnsServers
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• mode - DNS mode. One of the following values:
  • DNS_MODE_INVALID = 0
  • DNS_MODE_MA
  • DHCP_DNS
  • STATIC_DNS
• count - number of NUL terminated DNS server entries passed in the ppszDnsServers array to the API call (for example, 10.10.10.200 or 2020::40)
• ppszDnsServers - array of DNS servers

Returns

• success: 0
• failure: error code

nm_add_dns_server

Description

Add a server to the DNS servers list associated with an interface.

Declaration

uint32_t
 nm_add_dns_server(
     const char \*pszInterfaceName,
     const char \*pszDnsServer
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• ppszDnsServer - server to add to the DNS server list

Returns

• success: 0
• failure: error code

nm_delete_dns_server

Description

Delete a server from the DNS servers list associated with an interface.

Declaration

 uint32_t
 nm_delete_dns_server(
     const char \*pszInterfaceName,
     const char \*pszDnsServer
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• ppszDnsServer - server to remove from the DNS server list

Returns

• success: 0
• failure: error code

nm_get_dns_servers

Description

Get the the DNS servers list for the interface.

Declaration

uint32_t
 nm_get_dns_servers(
     const char \*pszInterfaceName,
     NET_DNS_MODE \*pMode,
     size_t \*pCount,
     char \*\*\*pppszDnsServers
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• pMode - DNS mode. One of the following values:
  • DNS_MODE_INVALID
  • DHCP_DNS
  • STATIC_DNS
• pCount - number of NUL terminated DNS server entries in the pppszDnsServers array returned by the API call (for example, 10.10.10.200 or 2020::40)
• pppszDnsServers - array of DNS servers

Returns

• success: 0
• failure: error code

nm_set_dns_domains

Description

Set the DNS domain list.

Declaration

uint32_t
 nm_set_dns_domains(
     const char \*pszInterfaceName,
     size_t count,
     const char \*\*ppszDnsDomains
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• count - number of DNS domains specified in the ppszDnsDomains array to the API call (for example, if count = 2, then there are two elements: ppszDnsDomains[0] and ppszDnsDomains[1])
• ppszDnsDomains - array of DNS domains

Returns

• success: 0
• failure: error code

nm_add_dns_domain

Description

Add a DNS domain to the DNS domain list.

Declaration

uint32_t
 nm_add_dns_domain(
     const char \*pszInterfaceName,
     const char \*pszDnsDomain
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• pszDnsDomain - DNS domain to add to the list

Returns

• success: 0
• failure: error code

nm_delete_dns_domain

Description

Delete a DNS domain from the DNS domain list.

Declaration

uint32_t
 nm_delete_dns_domain(
     const char \*pszInterfaceName,
     const char \*pszDnsDomain
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• pszDnsDomain - DNS domain to remove from the list

Returns

• success: 0
• failure: error code

nm_get_dns_domains

Description

Get the list of DNS domains.

Declaration

uint32_t
 nm_get_dns_domains(
     const char \*pszInterfaceName,
     size_t \*pCount,
     char \*\*\*pppszDnsDomains
 );

Arguments

• pszInterfaceName - interface name (optional, can be NULL)
• pCount - number of DNS domains returned in the pppszDnsDomains from the API call (for example, if count = 2, then there are two elements: ppszDnsDomains[0] and ppszDnsDomains[1])
• pppszDnsDomains - array of DNS domains

Returns

• success: 0
• failure: error code

DHCP Options DUID and IAID Configuration APIs

The Photon OS network manager C API enables you to manage DHCP DUID and Interface IAID.

nm_set_iaid

Description

Set the IAID for the interface.

Declaration

uint32_t
 nm_set_iaid(
     const char \*pszInterfaceName,
     uint32_t iaid
 );

Arguments

• pszInterfaceName - interface name
• iaid - interface association identifier (IAID)

Returns

• success: 0
• failure: error code

nm_get_iaid

Description

Get the IAID for the interface.

Declaration

uint32_t
 nm_get_iaid(
     const char \*pszInterfaceName,
     uint32_t \*pIaid
 );

Arguments

• pszInterfaceName - interface name
• pIaid - interface association identifier (IAID)

Returns

• success: 0
• failure: error code

nm_set_duid

Description

Set the DUID for the interface.

Declaration

uint32_t
 nm_set_duid(
     const char \*pszInterfaceName,
     const char \*pszDuid
 );

Arguments

• pszInterfaceName - interface name (optional, specify NULL to set system global DUID configuration)
• pszDuid - DHCP unique identifier (DUID)

Returns

• success: 0
• failure: error code

nm_get_duid

Description

Get the DUID for the interface.

Declaration

uint32_t
 nm_get_duid(
     const char \*pszInterfaceName,
     char \*\*ppszDuid
 );

Arguments

• pszInterfaceName - interface name (optional, specify NULL to query system global DUID configuration)
• ppszDuid - DHCP unique identifier (DUID)

Returns

• success: 0
• failure: error code

NTP Configuration APIs

The Photon OS network manager C API enables you to manage NTP servers configured for the system.

nm_set_ntp_servers

Description

Set the list of NTP servers.

Declaration

 uint32_t
 nm_set_ntp_servers(
     size_t count,
     const char \*\*ppszNtpServers
 );

Arguments

• count - number of NTP servers in the ppszNtpServers array passed to the API call.
• ppszNtpServers - array of NTP servers

Returns

• success: 0
• failure: error code

nm_add_ntp_servers

Description

Add a server to the NTP servers list.

Declaration

 uint32_t
 nm_add_ntp_servers(
     size_t count,
     const char \*\*ppszNtpServers
 );

Arguments

• count - number of NTP servers to add (specified in the ppszNtpServers array) passed to the API call.
• ppszNtpServers - array of NTP servers to add

Returns

• success: 0
• failure: error code

nm_delete_ntp_servers

Description

Delete a server from the NTP servers list.

Declaration

 uint32_t
 nm_delete_ntp_servers(
     size_t count,
     const char \*\*ppszNtpServers
 );

Arguments

• count - number of NTP servers to delete (specified in the ppszNtpServers array) passed to the API call
• ppszNtpServers - array of NTP servers to delete

Returns

• success: 0
• failure: error code

nm_get_ntp_servers

Description

Get the NTP servers list.

Declaration

 uint32_t
 nm_get_ntp_servers(
     size_t \*pCount,
     char \*\*\*pppszNtpServers
 );

Arguments

• pCount - number of NTP servers in the pppszNtpServers array returned from the API call
• pppszNtpServers - array of NTP servers

Returns

• success: 0
• failure: error code

Other APIs

nm_set_hostname

Description

Set the host name for the system.

Declaration

 uint32_t
 nm_set_hostname(
     const char \*pszHostname
 );

Arguments

• pszHostname - host name

Returns

• success: 0
• failure: error code

nm_get_hostname

Description

Get the host name for the system.

Declaration

 uint32_t
 nm_get_hostname(
     char \*\*ppszHostname
 );

Arguments

• ppszHostname - host name

Returns

• success: 0
• failure: error code

nm_wait_for_link_up

Description

Wait for the specified interface to come up.

Declaration

 uint32_t
 nm_wait_for_link_up(
     const char \*pszInterfaceName,
     uint32_t timeout
 );

Arguments

• pszInterfaceName - interface name
• timeout - maximum time (in seconds) to wait (until the link is up) before timing out of the request; specify 0 for no timeout (wait indefinitely)

Returns

• success: 0
• failure: error code

nm_wait_for_ip

Description

Wait for the interface to acquire an IP address of the specified IP address type.

Declaration

 uint32_t
 nm_wait_for_ip(
     const char \*pszInterfaceName,
     uint32_t timeout,
     NET_ADDR_TYPE addrTypes
 );

Arguments

• pszInterfaceName - interface name
• timeout - maximum time (in seconds) to wait (until the link has an IP address of the specified address type) before timing out of the request; specify 0 for no timeout (wait indefinitely)
• addrTypes - type of IP address; one of the following values:
  • STATIC_IPV4
  • STATIC_IPV6
  • DHCP_IPV4
  • DHCP_IPV6
  • AUTO_IPV6
  • LINK_LOCAL_IPV6

Returns

• success: 0
• failure: error code

nm_set_network_param

Description

Set the value of a network parameter for an object.

Declaration

uint32_t
 nm_set_network_param(
     const char \*pszObjectName,
     const char \*pszParamName,
     const char \*pszParamValue
 );

Arguments

• pszObjectName - an interface name (for example, “eth0”) or a file name (for example, /etc/systemd/resolved.conf)
• pszParamName - name of a parameter associated with the object; specified in the format SectionName_KeyName (for example, Link_MTUBytes represents the MtuBytes key in [Link] section in https://www.freedesktop.org/software/systemd/man/systemd.network.html)
• pszParamValue - points to the parameter value to set; you can add (+) or remove (-) a parameter by prepending the parameter name with + or -. For example:

netmgr net_info –set –object eth1 –paramname +Network_Address –paramvalue “10.10.10.1/24”

Returns

• success: 0
• failure: error code

nm_get_network_param

Description

Get the value of a network parameter associated with an object.

Declaration

 uint32_t
 nm_get_network_param(
     const char \*pszObjectName,
     const char \*pszParamName,
     char \*\*ppszParamValue
 );

Arguments

• pszObjectName - an interface name (for example, “eth0”) or a file name (for example, /etc/systemd/resolved.conf)
• pszParamName - name of a parameter associated with the object; returned in the format SectionName_KeyName (for example, Link_MTUBytes represents the MtuBytes key in [Link] section in https://www.freedesktop.org/software/systemd/man/systemd.network.html)
• ppszParamValue - parameter value

Returns

• success: 0
• failure: error code

Service Management APIs

nm_stop_network_service

Description

Stop the network service.

Declaration

 uint32_t
 nm_stop_network_service();

Returns

• success: 0
• failure: error code

nm_restart_network_service

Description

Restart the network service.

Declaration

 uint32_t
 nm_restart_network_service();

Returns

• success: 0
• failure: error code

nm_stop_dns_service

Description

Stop the DNS service.

Declaration

uint32_t
 nm_stop_dns_service();

Returns

• success: 0
• failure: error code

nm_restart_dns_service

Description

Restart the DNS service.

Declaration

 uint32_t
 nm_restart_dns_service();

Returns

• success: 0
• failure: error code

nm_stop_ntp_service

Description

Stop the NTP service.

Declaration

 uint32_t
 nm_stop_ntp_service();

Returns

• success: 0
• failure: error code

nm_restart_ntp_service

Description

Restart the NTP service.

Declaration

 uint32_t
 nm_restart_ntp_service();

Returns

• success: 0
• failure: error code

6.5.16 - Network Configuration Manager - Python API

Photon OS provides a Python API for the Network Configuration Manager.

• Setup Instructions
• Initialization Steps
• Get Online Help
• Basic Information
• Interface Configuration
• IP Address Configuration
• DNS Configuration
• DHCP Options, DUID, and IAID Configuration
• NTP Servers

Setup Instructions

To set up and run the latest version of the Network Manager API for Python:

# tdnf install pmd pmd-python3
# systemctl start pmd

Initialization Steps

# python3
>>> import pmd
>>> net = pmd.server().net

Get Online Help

Get help for all commands.

>>> help(net)

Get help for a specific command.

>>> help(net.add_ntp_servers)
-in function add_ntp_servers:
add_ntp_servers(...) method of  [server.net](http://server.net/) instance
    net.add_ntp_servers(ntpservers = ["20.20.20.20", "25.30.40.70"])
    adds ntp servers. returns success: 0, failure: exception.
(END)

Basic Information

get_system_network_info

Get network information details that are common to the entire system.

Syntax

net.get_system_network_info()

Returns

• details about the system network (DUID, DNS mode, DNS server list, DNS domain list, NTP server list)

Example

>>> system_network_info = netmgmt.get_system_network_info()

>>> print ( system_network_info)

[{DUID: 00:02:11:22:33:44:55:66:77:20, DNS Mode: (null), DNS ServerList: ['10.10.100.100', '20.20.200.10'], DNS domain list: [' [abcd.com](http://abcd.com)'], NTP ServerList: (null)}]

get_err_info

Get information about the specified error number.

Syntax

net.get_err_info(error = <error_number>)

Parameters

• error - error number

Here is the list of error numbers:

• 4097 - invalid parameter
• 4098 - not supported
• 4099 - out of memory
• 4100 - value not found
• 4101 - value exists
• 4102 - invalid interface
• 4103 - invalid mode
• 4104 - bad configuration file
• 4105 - write failed
• 4106 - timeout
• 4107 - DCHP timeout

Returns

• success: 0
• failure: exception

Example

>> net.get_err_info(error = 4097)

'invalid parameter'

Interface Configuration

Use these commands to manage the configuration for a network interface.

get_link_info

Get the link info for the specified interface or for all interfaces (if no interface is specified).

Syntax

net.get_link_info(ifname = interface_name)

Parameters

• ifname - interface name (optional)

Returns

• success: link info
• failure: exception

get_link_macaddr

Get the MAC address for the specified interface or for all interfaces (if no interface is specified).

Syntax

net.get_link_macaddr(ifname = interface_name)

Parameters

• ifname - interface name (optional)

Returns

• success: MAC address
• failure: exception

get_link_mode

Get the link mode for the specified interface (auto or manual), or for all interfaces (if no interface is specified).

Syntax

net.get_link_mode(ifname = interface_name)

Parameters

• ifname - interface name (optional)

Returns

• success: link mode (auto, manual, or unknown)
• failure: exception

get_link_mtu

Get the MTU of the specified interface or for all interfaces (if no interface is specified).

Syntax

net.get_link_mtu(ifname = interface_name)

Parameters

• ifname - interface name (optional)

Returns

• success: link MTU
• failure: exception

get_link_state

Get the link state of the specified interface or for all interfaces (if no interface is specified).

Syntax

net.get_link_state(ifname = interface_name)

Parameters

• ifname - interface name (optional)

Returns

• success: link state (up, down, unknown)
• failure: exception

set_link_down

Bring down the specified interface.

Syntax

net.set_link_down(ifname = interface_name)

Parameters

• ifname - interface name

Returns

• success: 0
• failure: exception

set_link_macaddr

Set the MAC address of the specified interface.

Syntax

net.set_link_macaddr(ifname = interface_name, macaddr = mac_address)

Parameters

• ifname - interface name
• macaddr = MAC address

Returns

• success: 0
• failure: exception

set_link_mode

Set the mode (auto or manual) of the specifed interface.

Syntax

net.set_link_mode(ifname = interface_name, link_mode = [auto, manual])

Parameters

• ifname - interface name
• link_mode - auto or manual

Returns

• success: 0
• failure: exception

set_link_mtu

Set the MTU for the specified interface.

Syntax

net.set_link_mtu(ifname = interface_name, mtu = mtu)

Parameters

• ifname - interface name
• mtu - mtu

Returns

• success: 0
• failure: exception

set_link_state

Set the state (up or down) of the specified interface.

Syntax

net.set_link_state(ifname = interface_name, link_state = [down, up])

Parameters

• ifname - interface name
• link_state - down or up

Returns

• success: 0
• failure: exception

set_link_up

Brings up the specified interface.

Syntax

net.set_link_up(ifname = interface_name)

Parameters

• ifname - interface name
• link_state - down or up

Returns

• success: 0
• failure: exception

IP Address Configuration

Use these commands to manage IP address configuration for a network interface.

add_static_ipv6_addr

Add a static IPv6 address to the specified interface.

Syntax

net.add_static_ipv6_addr(ifname = interface_name, addr_prefix = ipv6address_prefix)

Parameters

• ifname - interface name
• addr_prefix - IPv6 address prefix

Returns

• success: 0
• failure: exception

del_static_ipv6_addr

Delete a static IPv6 address from the specified interface.

Syntax

net.del_static_ipv6_addr(ifname = interface_name, addr_prefix = ipv6address_prefix)

Parameters

• ifname - interface name
• addr_prefix - IPv6 address prefix

Returns

• success: 0
• failure: exception

get_ipv4_addr_gateway

Get the IPv4 address with the prefix and gateway for the specified interface.

Syntax

net.get_ipv4_addr_gateway(ifname = interface_name)

Parameters

• ifname - interface name

Returns

• success: IPv4 address with the prefix and gateway
• failure: exception

get_ipv6_addr

Get the list of IPv6 addresses for the specified interface.

Syntax

net.get_ipv6_addr(ifname = interface_name)

Parameters

• ifname - interface name

Returns

• success: IPv6 address list
• failure: exception

get_ipv6_addr_mode

Get the address mode for the specified interface to determine whether DHCPv6, autoconf are enabled or disabled.

Syntax

net.get_ipv6_addr_mode(ifname = interface_name)