# Photon OS Administration Guide - [Introduction](#introduction) - [Examining the Packages in the SPECS Directory on Github](#examining-the-packages-in-the-specs-directory-on-github) - [Looking at the Differences Between the Minimal and the Full Version](#looking-at-the-differences-between-the-minimal-and-the-full-version) - [The Root Account and the `sudo` and `su` Commands](#the-root-account-and-the-sudo-and-su-commands) - [Getting Start for Photon OS 2.0](#getting-started-with-photon-os) - [Quick Start for Photon OS 1.0](#quick-start-for-photon-os) - [Obtaining the ISO from Bintray and Creating a Photon OS VM in VMware Workstation](#obtaining-the-iso-from-bintray-and-creating-a-photon-os-vm-in-vmware-workstation) - [Installing the OVA for the Minimal Version in vSphere](#installing-the-ova-for-the-minimal-version-in-vsphere) - [Rapidly Deploying the Photon OS OVA in VMware Workstation 12 Pro](#rapidly-deploying-the-photon-os-ova-in-vmware-workstation-12-pro) - [Root Password Rules](#root-password-rules) - [Permitting Root Login with SSH](#permitting-root-login-with-ssh) - [PXE Boot](#pxe-boot) - [Kickstart](#kickstart) - [Checking the Version and Build Number](#checking-the-version-and-build-number) - [Tiny DNF for Package Management](#tiny-dnf-for-package-management) - [Configuration Files and Repositories](#configuration-files-and-repositories) - [Options for Commands](#options-for-commands) - [Commands](#commands) - [Adding a New Repository](#adding-a-new-repository) - [Adding the Dev Repository to Get New Packages from the GitHub Dev Branch](#adding-the-dev-repository-to-get-new-packages-from-the-github-dev-branch) - [Managing Services with systemd](#managing-services-with-systemd) - [Using the Photon Management Daemon](#using-the-photon-management-daemon) - [Using the Network Configuration Manager](#using-the-network-configuration-manager) - [Viewing Services](#viewing-services) - [Controlling Services](#controlling-services) - [Creating a Startup Service](#creating-a-startup-service) - [Disabling the Photon OS httpd.service](#disabling-the-photon-os-httpd.service) - [Auditing System Events with auditd](#auditing-system-events-with-auditd) - [Analyzing systemd Logs with journalctl](#analyzing-systemd-logs-with-journalctl) - [Migrating Scripts to systemd](#migrating-scripts-to-systemd) - [Managing the Network Configuration](#managing-the-network-configuration) - [Use `ip` and `ss` Commands Instead of `ifconfig` and `netstat`](#use-ip-and-ss-commands-instead-of-ifconfig-and-netstat) - [Configuring Network Interfaces](#configuring-network-interfaces) - [Setting a Static IP Address](#setting-a-static-ip-address) - [Turning Off DHCP](#turning-off-dhcp) - [Adding a DNS Server](#adding-a-dns-server) - [Setting Up Networking for Multiple NICs](#setting-up-networking-for-multiple-nics) - [Combining DHCP and Static IP Addresses with IPv4 and IPv6](#combining-dhcp-and-static-ip-addresses-with-ipv4-and-ipv6) - [Clearing the Machine ID of a Cloned Instance for DHCP](#clearing-the-machine-id-of-a-cloned-instance-for-dhcp) - [Using Predictable Network Interface Names](#using-predictable-network-interface-names) - [Inspecting the Status of Network Links with `networkctl`](#inspecting-the-status-of-network-links-with-networkctl) - [Turning on Network Debugging](#turning-on-network-debugging) - [Mounting a Network File System](#mounting-a-network-file-system) - [Installing the Packages for tcpdump and netcat with tdnf](#installing-the-packages-for-tcpdump-and-netcat-with-tdnf) - [Cloud-Init on Photon OS](#cloud-init-on-photon-os) - [Creating a Stand-Alone Photon Machine with cloud-init](#creating-a-stand-alone-photon-machine-with-cloud-init) - [Customizing a Photon OS Machine on EC2](#customizing-a-photon-os-machine-on-ec2) - [Running a Photon OS Machine on GCE](#running-a-photon-os-machine-on-gce) - [Docker Containers](#docker-containers) - [Kubernetes](#kubernetes) - [RPM-OSTree](#rpm-ostree) - [Installing Sendmail](#installing-sendmail) - [Fixing Sendmail If Installed Before an FQDN Was Set](#fixing-sendmail-if-installed-before-an-fqdn-was-set) - [Changing the Locale](#changing-the-locale) - [The Default Security Policy of Photon OS](#the-default-security-policy-of-photon-os) - [Default Firewall Settings](#default-firewall-settings) - [Default Permissions and umask](#default-permissions-and-umask) - [Disabling TLS 1.0 to Improve Transport Layer Security](#disabling-tls-1.0-to-improve-transport-layer-security) - [Working with Repositories and Packages](#working-with-repositories-and-packages) - [Photon OS Package Repositories](#photon-os-package-repositories) - [Examining Signed Packages](#examining-signed-packages) - [Building a Package from a Source RPM](#building-a-package-from-a-source-rpm) - [Compiling C++ Code on the Minimal Version of Photon OS](#compiling-c-code-on-the-minimal-version-of-photon-os) - [References](#references) ## Introduction This guide describes the fundamentals of administering Photon OS, the open-source minimalist Linux operating system from VMware that is optimized for cloud computing platforms, VMware vSphere deployments, and applications native to the cloud. The 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. The guide also includes a section to get you started using Photon OS quickly and easily. 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. Photon OS optionally works with RPM-OSTree for image-based system versioning. When used with development tools and environments such as VMware Fusion, VMware Workstation, HashiCorp (Vagrant and Atlas), and production runtime environments (vSphere, vCloud Air), 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. There are two versions of Photon OS: a minimal version and a full version. The minimal version of Photon OS is lightweight container host runtime environment best 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 full version of Photon OS includes additional packages to help you customize the system and create containerized applications. For running containers, the full version is excessive. The full version is targeted at helping you create, develop, test, and package an application that runs a container. Two characteristics of Photon OS stand out: It manages services with systemd and it manages packages with an open source, yum-compatible package manager called tdnf, for Tiny DNF. By using systemd, Photon OS adopts a contemporary Linux standard to manage system services. Photon OS bootstraps the user space and concurrently starts services with systemd. The systemctl utility controls services on Photon OS. 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, you run the following systemctl commands on Photon OS: systemctl stop sshd systemctl start sshd Tdnf keeps the operating system as small as possible while preserving yum's robust package-management capabilities. On Photon OS, tdnf is the default package manager for installing new packages. It is a C implementation of DNF package manager. ### 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: 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, looks like this:
%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.*$... ...### Looking at the Differences Between the Minimal and the Full Version The minimal version of Photon OS contains about 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](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 version by examining the following file: [https://github.com/vmware/photon/blob/master/common/data/packages_full.json](https://github.com/vmware/photon/blob/master/common/data/packages_full.json) If the minimal or the full version of Photon OS does not contain a package that you want, you can of course 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: 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 A later section covers tdnf. ### The Root Account and the `sudo` and `su` Commands This guide assumes that you are logged in to Photon OS with the root account and running commands as root. The sudo program comes with the full version of Photon OS. On the minimal version, you must install sudo with tdnf if you want to use it. As an alternative to installing sudo on the minimal version, you can switch users as needed with the `su` command to run commands that require root privileges. ## Getting Started with Photon OS **NOTE:** This section applies to Photon OS w.0 only. To get started with Photon OS 2.0, refer to the installation instructions for your target environment: - [Running Photon OS on VMware vSphere](#https://github.com/vmware/photon/wiki/Running-Photon-OS-on-vSphere) - [Running Photon OS on VMware Fusion](#https://github.com/vmware/photon/wiki/Running-Project-Photon-on-Fusion) - [Running Photon OS on VMware Workstation](#https://github.com/vmware/photon/wiki/Running-Photon-OS-on-vSphere) - [Running Photon OS on Amazon EC2](#https://github.com/vmware/photon/wiki/Running-Photon-OS-on-Amazon-Elastic-Cloud-Compute) - [Running Photon OS on Google Compute Engine](#https://github.com/vmware/photon/wiki/Running-Photon-OS-on-Google-Compute-Engine) - [Running Photon OS on Microsoft Azure](#https://github.com/vmware/photon/wiki/Running-Photon-OS-on-Microsoft-Azure) ## Quick Start for Photon OS **NOTE:** This section applies to Photon OS 1.0 only. This section helps you get Photon OS up and running quickly and easily. There are several ways to deploy Photon OS for free within a matter of minutes: * Obtain the ISO from Bintray and use it to create a virtual machine running Photon OS. * Install the OVA for the minimal version of Photon OS in VMware vSphere. * Rapidly deploy the OVA for the minimal version of Photon OS in VMware Workstation 12 Pro. ### Obtaining the ISO from Bintray and Creating a Photon OS VM in VMware Workstation The full version of Photon OS installs from an ISO in VMware Workstation and other hypervisors in a matter of minutes. Photon OS is a free download from the Bintray web site. This section demonstrates how to create a virtual machine running Photon OS in VMware Workstation 12 Pro. If you are using a different hypervisor, the example set by this section should help you install it in your system. For instructions on how to install Photon OS from an ISO in VMware vSphere, see [Installing Photon OS on VMware vSphere from an ISO Image](https://github.com/vmware/photon/wiki/Running-Project-Photon-on-vSphere). 1. Go to the following Bintray URL and download the ISO for the general availability release of Photon OS: https://bintray.com/vmware/photon/iso/view 1. In VMware Workstation, type Ctrl+N to create a new virtual machine. 1. In the New Virtual Machine Wizard, select `Typical`, and then click `Next`. 1. Select `Installer disk image file (iso)`, click `Browse` to locate the Photon OS ISO that you downloaded from Bintray, and then click `Next`. 1. For the guest operating system, select `Linux`. From the `Version` drop-down menu, select `VMware Photon 64-bit`. If you have an older version of VMware Workstation and Photon does not appear in the list, select `Other Linux 3.x kernel 64-bit`. ![VMware Photon](images/ws-new-vm.png) 1. Click `Next` through the remaining dialog boxes of the wizard, either accepting the default settings, which is recommended, or making the changes that you want, and then click `Finish`. 1. Power on the virtual machine and, in the Workstation window containing Photon, press Enter to start the installation. ![Installer](images/photon-installer-sm.png) 1. During disk setup, the installer might ask you to confirm that this will erase the disk. If so, accept the default value of `yes` by hitting your Enter key. 1. Select the installation that you want. For this example, choose `Photon Full` by using the tab key to move to Photon Full and then hitting the space bar to select it. Press Enter to install it. 1. Either accept the default hostname that Photon provides or type the name that you want. Press Enter to continue. 1. Type the root password. Photon OS requires the root password to be a complex string containing no common words or names. The installation typically completes in about 150 seconds for the full version and in less than 30 seconds for the minimal version. After the installation finishes, boot the system and log in as root with your root password. To connect to Photon OS by SSH, see the section on permitting root login with SSH below. You can also build an ISO containing Photon OS from its source code on GitHub by following the instructions in the document on [building Photon OS](https://github.com/vmware/photon/blob/master/docs/build-photon.md). ### Installing the OVA for the Minimal Version in vSphere You can download the OVA for the minimal version of Photon OS from Bintray and deploy it in vSphere in a matter of seconds. Here's how: Download the OVA for the minimal version of Photon OS from the following URL: https://bintray.com/vmware/photon/ova To install the OVA in vSphere, on the `File` menu, click `Deploy OVF Template`, and then click `Browse` to locate the image that you downloaded. Move through the `Deploy OVF Template` dialog boxes by clicking `Next` to accept the default settings, and then click `Finish`. In vSphere Client, turn on the power of the Photon OS virtual machine and open a console to it. The default password for the root account is `changeme`, and you must change it when you first login. For security, Photon OS forbids common dictionary words for the root password. There are other options for installing Photon OS in vSphere, such as building an ISO from the source code. For more information about the versions of Photon and their installation options, see [Running Photon OS on vSphere](https://github.com/vmware/photon/wiki/Running-Project-Photon-on-vSphere). ### Rapidly Deploying the Photon OS OVA in VMware Workstation 12 Pro Here's how to rapidly deploy the OVA for Photon in VMware Workstation 12 Pro by using an up-to-date version of Firefox. The procedure in other browsers or another version of Workstation might be different. In Firefox, download the OVA for the minimal version of Photon OS from this URL: https://bintray.com/vmware/photon/ova In the download dialog box, select `Open with VMware Workstation (default)`, like this: ![Firefox Dialogue Box](images/ova-firefox.png) In the Workstation Import dialog box, click Import. ![Import virtual machine](images/ova-import.png) Workstation creates a virtual machine from the Photon OS OVA template in a few seconds. In Workstation, power on the virtual machine and log in as root with the initial password of `changeme`. Photon OS then prompts you to change the root password. ### Root Password Rules When you first log on a new Photon OS machine, you must set the root password to a complex string containing no common words or names. Photon OS rejects a root password that contains simplistic patterns, common words, or words derived from the name of your account. The rules apply only to the root password, not other user and group accounts. ### Permitting Root Login with SSH The full version of Photon OS prevents root login with SSH by default. To permit root login over SSH, open `/etc/ssh/sshd_config` with the vim text editor and set `PermitRootLogin` to `yes`. Vim is the default text editor available in both the full and minimal versions of Photon OS. (Nano is also in the full version.) After you modify the SSH daemon's configuration file, you must restart the sshd daemon for the changes to take effect. Example: vim /etc/ssh/sshd_config # override default of no subsystems Subsystem sftp /usr/libexec/sftp-server # Example of overriding settings on a per-user basis #Match User anoncvs # X11Forwarding no # AllowTcpForwarding no # PermitTTY no # ForceCommand cvs server PermitRootLogin yes UsePAM yes Save your changes in vim and then restart the sshd daemon: systemctl restart sshd You can then connect to the Photon OS machine with the root account over SSH: steve@ubuntu:~$ ssh root@198.51.100.131 ### PXE Boot Photon OS works with the Preboot Execution Environment, or PXE, to boot by retrieving software from a PXE server over a network connection. For instructions on how to set Photon OS to boot from a PXE server, see [Network PXE Boot](https://github.com/vmware/photon/blob/master/docs/PXE-boot.md). ### Kickstart Photon OS supports kickstart for unattended installations through a CD-ROM or an HTTP server. On Photon OS, kickstart can set the hostname, password, run post-installation scripts, and add public keys for SSH. See [Kickstart Support](https://github.com/vmware/photon/blob/master/docs/kickstart.md). ### Checking the Version and Build Number To check the version and build number of Photon OS, concatenate `/etc/photon-release`. Example: cat /etc/photon-release VMware Photon Linux 1.0 PHOTON_BUILD_NUMBER=a6f0f63 The build number in the results maps to the commit number on the VMware Photon OS GitHub [commits page](https://github.com/vmware/photon/commits/master). ## Tiny DNF for Package Management On Photon OS, Tiny DNF, for [Tiny Dandified Yum](https://github.com/vmware/tdnf), is the default package manager for installing new packages. It is a C implementation of DNF package manager. The standard syntax for `tdnf` commands is the same as that for DNF: tdnf [options]
httpd.service
by default. To stop it and disable it, run the following commands as root:
systemctl stop httpd.service
systemctl disable httpd.service
### Auditing System Events with auditd
Because Photon OS emphasizes security, the Linux auditing service, auditd, is enabled and active by default on the full version of Photon OS:
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, for instance, 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 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 like this:
auditctl -l
-w /etc/sudoers -p wa -k sudoers_changes
For more information on the Linux Audit Daemon, see its man page on Photon OS:
man auditd
For more information on setting auditing rules and options with auditctl, see its man page:
man auditctl
For more information on viewing reports on audited events, see the aureport man page:
man aureport
### Analyzing systemd Logs with journalctl
The journalctl tool queries the contents of the systemd journal. For help troubleshooting systemd, two journalctl queries are particularly useful: showing the log entries for the last boot and showing the log entries for a systemd service unit.
This command displays the messages that systemd generated during the last time the machine started:
journalctl -b
This command reveals the messages for only the systemd service unit specified by the `-u` option, which is auditd in the following example:
journalctl -u auditd
For more information, see the journalctl man page by running this command on Photon OS: `man journalctl`
### Migrating Scripts to systemd
Although systemd maintains compatibility with init.d scripts, you should, as a best practice, 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.
## Managing the Network Configuration
The network service, which is enabled by default, starts when the system boots. You manage the network service by using systemd commands, such as systemd-networkd, systemd-resolvd, and networkctl. You can check its status of the network service by running the following command:
systemctl status systemd-networkd
Here is a healthy result of the command:
* 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 should employ the systemd suite of commands, not deprecated init.d commands or other deprecated commands, to manage networking.
### Using the Photon Management Daemon
The Photon Management Daemon (PMD) that ships with Photon OS 2.0 provides the remote management of a Photon instance via several APIs: a command line client (pmd-cli), a REST API, and a Python API. The PMD provides the ability to manage network interfaces, packages, firewalls, users, and user groups.
#### Installing the pmd Package
The pmd package is included with your Photon OS 2.0 distribution. To make sure that you have the latest version, you can run:
~~~~
# tdnf install pmd
# systemctl start pmd
~~~~
#### Available APIs
##### pmd-cli
The pmd-cli utility enables Photon customers to invoke API requests securely on local and remote servers. For details, see [Photon Management Daemon Command-line Interface (pmd-cli)](#https://github.com/vmware/photon/blob/master/docs/pmd-cli.md).
##### PMD REST API
The PMD REST API is an openapi 2.0 specification. Once the pmd package is installed, you can use a Swagger UI tool to browse the REST API specifications (/etc/pmd/restapispec.json).
You can also browse it using the copenapi_cli tool that comes with the pmd package:
~~~~
# copenapi_cli --apispec /etc/pmd/restapispec.json
~~~~
For more information about the copenapi_cli tool, refer to [github.com/vmware/copenapi](#https://github.com/vmware/copenapi).
##### PMD Python API
Python3 is included with your Photon OS 2.0 distribution. PMD Python interfaces are available for python3 (pmd-python3) and python2 (pmd-python2). You can use tdnf to ensure that the latest version is installed:
~~~~
# tdnf install pmd-python3
# systemctl start pmd
~~~~
To navigate the help documentation for the pmd Python packages:
~~~~
# python3
>>> import pmd
>>> net = pmd.server().net
>>> help(pmd)
~~~~
To show help text for individual interfaces:
~~~~
>>> help(pmd.server().net)
>>> help(pmd.server().pkg)
>>> help(pmd.server().firewall)
>>> help(pmd.server().user)
~~~~
For details about the network commands, see also the [Network Configuration Manager - Python API](#https://github.com/vmware/photon/blob/master/docs/netmgr.python.md).
##### PMD C Documentation
PMD C APIs are defined in the header files (pmd_fwmgmt.h, pmd_netmgr.h, pmd_pkgmgmt.h, pmd_usermgmt.h) that are stored in the following location:
~~~~
[https://github.com/vmware/pmd/tree/master/include](#https://github.com/vmware/pmd/tree/master/include)
~~~~
For details about the network commands, see also the [Network Configuration Manager - C API](#https://github.com/vmware/photon/blob/master/docs/netmgr.c.md).
### Using the Network Configuration Manager
The Network Configuration Manager library that ships with Photon OS 2.0 provides a collection of C, Python, and CLI APIs that simplify common onfiguration 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)
For additional details, see:
- **CLI** - see the ``-net`` commands in the [Photon Management Daemon Command-line Interface (pmd-cli)](#https://github.com/vmware/photon/blob/master/docs/pmd-cli.md)
- **C APIs** - [Network Configuration Manager - C API](#https://github.com/vmware/photon/blob/master/docs/netmgr.c.md)
- **Python APIs** - [Network Configuration Manager - Python API](#https://github.com/vmware/photon/blob/master/docs/netmgr.python.md)
### Use `ip` and `ss` Commands Instead of `ifconfig` and `netstat`
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, instead of running `netstat` to display a list of network interfaces, run the `ss` command. Similarly, to display information for IP addresses, instead of running `ifconfig -a`, run the `ip addr` command. Examples:
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, accurate information on Photon OS, as the following example demonstrates:
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
### 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/
10-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:
cat /etc/systemd/network/10-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/10-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 [ ~ ]#
As you can see, the /usr/lib/systemd/network directory contains several network configuration files. Photon OS applies the configuration files in the [lexicographical order](https://en.wikipedia.org/wiki/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. You set the matching rule and the configuration as sections containing vertical sets of key-value pairs according to the information at https://www.freedesktop.org/software/systemd/man/systemd.network.html.
To configure Photon OS to handle a networking use case, such as setting a static IP address or adding a name server, you 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:
chmod 644 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.
### 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 the following command:
systemctl restart systemd-networkd
For more information, see the man page for systemd-networkd: `man systemd.network`
### 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:
cat /etc/systemd/network/10-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
### Adding a DNS Server
Photon OS resolves domain names, IP addresses, and network names for local applications by using systemd-resolved. 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 should therefore never modify the /etc/resolv.conf file.
(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 to your static network configuration file, insert a DNS key into the Network section of, in this 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
Another way of adding a DNS server is to modify /etc/systemd/resolved.conf--a method that can be particularly useful when your machine is working with DHCP. 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 /etc/nsswitch.conf. To do so, make a backup copy of /etc/nsswitch.conf and then execute the following command as root:
sed -i 's/^hosts.*$/hosts: files resolve dns/' /etc/nsswitch.conf
For more information on the systemd-resolved service, see https://www.freedesktop.org/software/systemd/man/systemd-resolved.service.html.
### Setting Up Networking for Multiple NICs
If your machine contains multiple NICs, you should, as a best practice, 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. Keep in mind that the following configurations are examples: 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 in this example eth0. 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 named 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
### Combining DHCP and Static IP Addresses with IPv4 and IPv6
This section presents examples that demonstrate how to combine DHCP and static IP addresses with both IPv4 and IPv6.
Here's how to use DHCP to allocate both IPv4 and IPv6 addresses:
[Network]
DHCP=yes
Here's how to use DHCP to allocate only IPv4 addresses:
[Network]
DHCP=ipv4
Here's how to use DHCP to allocate only IPv6 addresses:
[Network]
DHCP=ipv6
Here's how to use DHCP for IPv4 addresses and static IP addresses for IPv6 addresses:
[Network]
DHCP=ipv4
Address=fd00::1/48
Gateway=fd00::252
Here's 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
Here's 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
### 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 should clear the machine-id with this command:
echo -n > /etc/machine-id
With the value cleared, systemd regenerates the machine-id and, as a result, all DHCP requests will contain a unique duid.
### Using Predictable Network Interface Names
On a virtual machine running Photon OS, just as on a bare-metal machine, the Ethernet network interface name might shift from one device to another if you add or removed a card and reboot the machine. A device named `eth2`, for example, might become `eth1` after a NIC is removed and the machine is restarted.
You can prevent interface names from reordering by turning on [predictable network interface names](https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/). The naming schemes that Photon OS uses can then assign fixed, predictable names to network interfaces even after cards or other firmware are added or removed and the system is restarted. With predictable network interface names enabled, you can select among several 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.
(Although Photon OS also supports the `onboard` name policy to set in the `eno` format the name of networking devices from index numbers given by the firmware, the `onboard` policy might result in nonpersistent names.)
The option that you choose depends on your use case and your unique networking requirements. If, for instance, you clone clones virtual machines in a use case that requires the MAC addresses to be different from one another but the interface name to be the same, you should consider using `ens` to keep the slot the same after reboots.
Alternatively, if the cloning function supports it and it works for your use case, you can use `enx` to set a MAC address, which also persists after reboots.
Here's how to turn on predictable network interface names.
First, 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
Second, to turn on predictable network interface names, edit `/boot/grub/grub.cfg` to remove the following string:
net.ifnames=0
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.
Third, 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`. Here's what the file looks like:
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. Example:
/lib/systemd/network/99-default.link
[Link]
NamePolicy=slot mac kernel database
MACAddressPolicy=persistent
With the name policy specified in the above example, it's possible that you could still end up with 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](https://www.freedesktop.org/software/systemd/man/systemd.link.html).
### Inspecting the Status of Network Links with `networkctl`
The `networkctl` command shows information about network connections that helps you configure networking services and troubleshoot networking problems. You can, for example, progressively add options and arguments to the `networkctl` command to move from general information about network connections to specific information about a network connection.
Running `networkctl` without options defaults 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.
Running `networkctl` with the status command displays information that looks like this; you can see that there are active network links with IP addresses for not only the Ethernet connection but also a Docker container.
root@photon-rc [ ~ ]# networkctl status
* State: routable
Address: 198.51.100.131 on eth0
172.17.0.1 on docker0
fe80::20c:29ff:fe55:3ca6 on eth0
fe80::42:f0ff:fef7:bd81 on docker0
fe80::4c84:caff:fe76:a23f on vethb0aa7a6
Gateway: 198.51.100.2 on eth0
DNS: 198.51.100.2
You can then 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 eth0
* 2: eth0
Link File: /usr/lib/systemd/network/99-default.link
Network File: /etc/systemd/network/10-dhcp-en.network
Type: ether
State: routable (configured)
Path: pci-0000:02:01.0
Driver: e1000
HW Address: 00:0c:29:55:3c:a6 (VMware, Inc.)
MTU: 1500
Address: 198.51.100.131
fe80::20c:29ff:fe55:3ca6
Gateway: 198.51.100.2
DNS: 198.51.100.2
CLIENTID: ffb6220feb00020000ab116724f520a0a77337
And you can do the same thing with the Docker 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, it is OK that the state of the Docker container is unmanaged; Docker handles managing the networking for the containers without using systemd-resolved or systemd-networkd. Instead, Docker manages the container's connection by using its bridge drive.
For more information about `networkctl` commands and options, see https://www.freedesktop.org/software/systemd/man/networkctl.html.
### 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. The following procedure turns on network debugging by adding a drop-in file in /etc/systemd to customize the default systemd configuration in /usr/lib/systemd.
First, run the following command as root to create a directory with this exact name, including the `.d` extension:
mkdir -p /etc/systemd/system/systemd-networkd.service.d/
Second, 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/10-loglevel-debug.conf << "EOF"
[Service]
Environment=SYSTEMD_LOG_LEVEL=debug
EOF
You must reload the systemctl daemon and restart the systemd-networkd service for the changes to take effect:
systemctl daemon-reload
systemctl restart systemd-networkd
Verify that your changes took effect:
systemd-delta --type=extended
View the log files by running this command:
journalctl -u systemd-networkd
When you are finished 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
### 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, or 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](https://github.com/vmware/photon/blob/master/docs/nfs-utils.md).
### Installing the Packages for tcpdump and netcat with tdnf
The minimal version of Photon OS leaves out several useful networking tools to keep the operating system lean. Tcpdump, for example, is absent in the minimal version but available in the repository. The minimal version does, however, include the iproute2 tools by default.
Tcpdump captures and analyzes packets on a network interface. On Photon OS, you install tcpdump and its accompanying package libpcap, a C/C++ library for capturing network traffic, by using tdnf, Photon's command-line package manager:
tdnf install tcpdump
Netcat, a tool for sending data over network connections with TCP or UDP, appears in neither the minimal nor 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 do so, run the following command:
tdnf install netcat
## Cloud-Init on Photon OS
The minimal and full versions of Photon OS include the cloud-init service as a built-in component. Cloud-init is a set of Python scripts that initialize cloud instances of Linux machines. The cloud-init scripts configure SSH keys and run commands to customize the machine without user interaction. The commands can set the root password, create a hostname, configure networking, write files to disk, upgrade packages, run custom scripts, and restart the system.
There are several ways in which you can deploy Photon OS with cloud-init, including the following:
* As a stand-alone Photon machine
* In Amazon Elastic Compute Cloud, called EC2
* In the Google cloud through the Google Compute Engine, or GCE
* In a VMware Vsphere private cloud
When a cloud instance of Photon OS starts, cloud-init requires a data source. The data source can be an EC2 file for Amazon's cloud platform, a seed.iso for a stand-alone instance of Photon OS, or the internal capabilities of a system for managing virtual machines, such as VMware vSphere or vCenter. Cloud-init also includes data sources for OpenStack, Apache CloudStack, and OVF. The data source comprises two parts:
1. Metadata
2. User data
The metadata gives the cloud service provider instructions on how to implement the Photon OS machine in the cloud infrastructure. Metadata typically includes the instance ID and the local host name.
The user data contains the commands and scripts that Photon OS executes when it starts in the cloud. The user data commonly takes the form of a shell script or a YAML file containing a cloud configuration. The [cloud-init documentation](https://launchpad.net/cloud-init and https://cloudinit.readthedocs.org/en/latest/) contains information about the types of data sources and the formats for metadata and user data.
On Photon OS, cloud-init is enabled and running by default. You can check its status like this:
systemctl status cloud-init
The Photon OS directory that contains the local data and other resources for cloud-init is here:
/var/lib/cloud
Photon OS stores the logs for cloud-init in the following file:
/var/log/cloud-init.log
The following sections demonstrate how to use cloud-init to customize a stand-alone Photon OS machine, instantiate a Photon OS machine in the Amazon EC2 cloud, and deploy a virtual machine running Photon OS in vSphere. Each section uses a different combination of the available options for the metadata and the user data that make up the data source. Specifications, additional options, and examples appear in the cloud-init documentation.
### Creating a Stand-Alone Photon Machine with cloud-init
Cloud-init can customize a Photon OS virtual machine by using the `nocloud` data source. The nocloud data source bundles the cloud-init metadata and user data into a ISO that acts as a seed when you boot the machine. This seed.iso delivers the metadata and the user data without requiring a network connection.
Here's how customize a Photon OS VM with a nocloud data source:
First, create the metadata file with the following lines in the [YAML](http://www.yaml.org/start.html) format and name it `meta-data`:
instance-id: iid-local01
local-hostname: cloudimg
Second, create the user data file with the following lines in YAML and name it user-data:
#cloud-config
hostname: testhost
packages:
- vim
Third, generate the ISO that will serve as the seed; the ISO must have the volume ID set to `cidata`. In this example, the ISO is generated on an Ubuntu 14.04 computer containing the files named `meta-data` and `user-data` in the local directory:
genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data
The ISO now appears in the current directory:
steve@ubuntu:~$ ls
meta-data seed.iso user-data
Optionally, you can check the ISO that you generated on Ubuntu by transferring the ISO to the root directory of your Photon OS machine and then running the following command:
cloud-init --file seed.iso --debug init
After running the cloud-init command above, check the cloud-init log file:
more /var/log/cloud-init.log
Finally, attach the ISO to the Photon OS virtual machine as a CD-ROM and reboot it so that the changes specified by seed.iso take effect. In this case, cloud-init sets the hostname and adds the vim package.
### Customizing a Photon OS Machine on EC2
This section illustrates how to upload an `ami` image of Photon OS to Amazon Elastic Compute Cloud (EC2) and customize the Photon OS machine by using cloud-init with an EC2 data source. The Amazon machine image version of Photon OS is available as a free download on Bintray:
https://bintray.com/vmware/photon/
The cloud-init service is commonly used on EC2 to configure the cloud instance of a Linux image. On EC2, for example, cloud-init typically sets the `.ssh/authorized_keys` file to let you log in with a private key from another computer--that is, a computer besides the workstation that you are already using to connect with the Amazon cloud. The cloud-config user-data file that appears in the following example contains abridged SSH authorized keys to show you how to set them.
Working with EC2 requires Amazon accounts for both AWS and EC2 with valid payment information. If you execute the following examples, you will be charged by Amazon. You will need to replace the `