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

Return to the regular view of this page.

Managing the Network Configuration

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

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.

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:

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

4 - Configuring Network Interfaces

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

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

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

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

[Network]
DHCP=yes

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

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

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

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

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

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

Example:

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

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

systemctl restart systemd-networkd

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

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

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

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.

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

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

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.

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

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.

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.

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

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

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.

15 - Network Configuration Manager - C API

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

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

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;``

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;

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;

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

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

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

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

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

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

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

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

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

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

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

16 - Network Configuration Manager - Python API

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

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

Bring down the specified interface.

Syntax

net.set_link_down(ifname = interface_name)

Parameters

  • ifname - interface name

Returns

  • success: 0
  • failure: exception

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

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)

Parameters

  • ifname - interface name

Returns

  • Status for DHCPv6, autoconf (True=enabled, False=disabled)
  • failure: exception

get_ipv6_gateway

Get the IPv6 gateway for the specified interface.

Syntax

net.get_ipv6_gateway(ifname = interface_name)

Parameters

  • ifname - interface name

Returns

  • success: IPv6 gateway
  • failure: exception

set_ipv4_addr_gateway

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

Syntax

net.get_ipv4_addr_gateway(ifname = interface_name, addr_mode = [dhcp, static, none], addr_prefix = ipv4addressprefix, gateway = ipv4gateway)

Parameters

  • ifname - interface name
  • addr_mode - address mode - dhcp, static, or none
  • addr_prefix - IPv4 address or prefix
  • gateway - IPv4 gateway

Returns

  • success: 0
  • failure: exception

set_ipv6_addr_mode

Set the address mode for the specified interface.

Syntax

net.set_ipv6_addr_mode(ifname = interface_name, enable_dhcp = [True, False], enable_autoconf = [True, False])

Parameters

  • ifname - interface name
  • enable_dhcp - True to enable, False to disable
  • enable_autoconf - True to enable, False to disable

Returns

  • success: 0
  • failure: exception

set_ipv6_gateway

Set the IPv6 gateway for the specified interface.

Syntax

net.set_ipv6_gateway(ifname = interface_name, gateway = ipv6gateway)

Parameters

  • ifname - interface name
  • gateway - IPv6 gateway

Returns

  • success: 0
  • failure: exception

DNS Configuration

Use these commands to manage DNS domains and servers for a network interface.

get_dns_domains

Get the list of DNS domains for the specified interface.

Syntax

net.get_dns_domains(ifname = interface_name)

Parameters

  • ifname - interface name

Returns

  • success: list of DNS domains
  • failure: exception

get_dns_servers

Get the list of DNS servers and the mode for the specified interface.

Syntax

net.get_dns_servers(ifname = interface_name)

Parameters

  • ifname - interface name

Returns

  • success: list of DNS servers and mode
  • failure: exception

set_dns_domains

Set the list of DNS domains for the specified interface.

Syntax

net.set_dns_domains(domains = ["domain1","domain2",...], ifname = interface_name)

Parameters

  • domains - comma-separated list of one or more domains
  • ifname - interface name

Returns

  • success: 0
  • failure: exception

set_dns_servers

Set the list of DNS servers for the specified interface.

Syntax

net.set_dns_servers(dns_mode = [dhcp, static], servers = ["server1","server2", ...], ifname = interface_name)

Parameters

  • dns_mode - dhcp or static
  • servers - comma-separate list of one or more servers
  • ifname - interface name

Returns

  • success: 0
  • failure: exception

DHCP Options DUID and IAID Configuration

Get the IAID for the specified interface.

Syntax

net.get_link_iaid(ifname = interface)

Parameters

  • ifname - interface name

Returns

  • success: IAID
  • failure: exception

Set the IAID for the specified interface.

Syntax

net.set_link_iaid(ifname = interface_name, iaid = <iaid>)

Parameters

  • ifname - interface name
  • iaid - IAID

Returns

  • success: 0
  • failure: exception

get_dhcp_duid

Get the DCHP DUID.

Syntax

net.get_dhcp_duid(ifname = interface_name)

Parameters

  • ifname - interface name (optional)

Returns

  • success: DUID
  • failure: exception

set_dhcp_duid

Set the DCHP DUID.

Syntax

net.set_dhcp_duid(ifname = interface_name duid = duid)

Parameters

  • ifname - interface name (optional)
  • duid - DUID to set

Returns

  • success: 0
  • failure: exception

NTP Servers

Use these commands to manage the NTP servers list.

add_ntp_servers

Add one or more NTP servers to the NTP servers list.

Syntax

net.add_ntp_servers(ntpservers = ["server1", "server2", ...])

Parameters

  • ntpservers - Comma-separated list of NTP servers to add to the list.

Returns

  • success: 0
  • failure: exception

del_ntp_servers

Remove one or more NTP servers from the NTP servers list.

Syntax

net.del_ntp_servers(ntpservers = ["server1", "server2", ...])

Parameters

  • ntpservers - Comma-separated list of NTP servers to remove from the list.

Returns

  • success: 0
  • failure: exception

get_ntp_servers

Get the NTP servers list.

Syntax

net.get_ntp_servers()

Returns

  • success: NTP servers list
  • failure: exception

set_ntp_servers

Set the NTP servers list.

Syntax

net.set_ntp_servers(ntpservers = ["server1", "server2", ...])

Parameters

  • ntpservers - Comma-separated list of NTP servers to set in the list.

Returns

  • success: 0
  • failure: exception

get_hostname

Get the host name.

Syntax

net.get_hostname()

Returns

  • success: host name
  • failure: exception

set_hostname

Set the host name.

Syntax

net.set_hostname(hostname)

Parameters

  • hostname - name to assign to the host

Returns

  • success: 0
  • failure: exception

wait_for_ip

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

Syntax

net.wait_for_ip(ifname = interface_name, timeout = timeout, addrtypes = [ipv4, ipv6, static_ipv4, static_ipv6, dhcp_ipv4, dhcp_ipv6, auto_ipv6, link_local_ipv6])

Parameters

  • ifname - 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)
  • addrtypes - one of the following address types: ipv4, ipv6, static_ipv4, static_ipv6, dhcp_ipv4, dhcp_ipv6, auto_ipv6, or link_local_ipv6

Returns

  • success: 0 (when the link has an IP of the specified type)
  • failure: exception (for example, timeout expired)

Wait for the specified interface to come up.

Syntax

net.wait_for_link_up(ifname = interface_name, timeout = timeout)

Parameters

  • ifname - 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 (when link is up)
  • failure: exception (for example, timeout expired)

get_network_param

Get the specified network configuration parameter for the specified interface or filename.

Syntax

net.get_network_param(object = IfName or Filename, paramname = SectionName_KeyName)

Parameters

  • object - an interface name (for example, "eth0") or a file name (for example, /etc/systemd/resolved.conf)
  • paramname - 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)

Returns

  • success: 0
  • failure: exception

set_network_param

Set the value of a network configuration parameter for the specified interface or filename.

Syntax

net.set_network_param(object = interface_name or filename, paramname = SectionName_KeyName, paramvalue = key_value)

Parameters

  • object - an interface name (for example, "eth0") or a file name (for example, /etc/systemd/resolved.conf)
  • paramname - 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)

Returns

  • success: 0
  • failure: exception