Oracle Cloud Infrastructure Documentation

Private IP Addresses

This topic describes how to manage the IPv4 addresses assigned to an instance in a virtual cloud network (VCN).

IPv6 addressing is supported for all commercial and government regions. For more information, see IPv6 Addresses.

Overview of IP Addresses

Instances use IP addresses for communication. Each instance has at least one private IP address and optionally one or more public IP addresses. A private IP address enables the instance to communicate with other instances inside the VCN, or with hosts in your on-premises network (via Site-to-Site VPN or Oracle Cloud Infrastructure FastConnect). A public IP address enables the instance to communicate with hosts on the internet. For more information, see these related topics:

About the Private IP Object

The Networking service defines an object called a private IP, which consists of:

Each private IP object has an Oracle-assigned OCID (see Resource Identifiers). If you're using the API, you can also assign each private IP object a friendly name.

Each instance receives a primary private IP object during launch. The Networking service uses the Dynamic Host Configuration Protocol (DHCP) to pass the object's private IP address to the instance. This address does not change during the instance's lifetime and cannot be removed from the instance. The private IP object is terminated when the instance is terminated.

If an instance has any secondary VNICs attached, each of those VNICs also has a primary private IP.

A private IP can have a public IP assigned to it at your discretion.

A private IP can be the target of a route rule in your VCN. For more information, see Using a Private IP as a Route Target.

About Secondary Private IP Addresses

You can add a secondary private IP to an instance after it's launched. You can add it to either the primary VNIC or a secondary VNIC on the instance. The secondary private IP address must come from the CIDR of the VNIC's subnet. You can move a secondary private IP from a VNIC on one instance to a VNIC on another instance if both VNICs belong to the same subnet.

Here are a few reasons why you might use secondary private IPs:

  • Instance failover: You assign a secondary private IP to an instance. Then if the instance has problems, you can easily reassign that secondary private IP to a standby instance in the same subnet. If the secondary private IP has a public IP assigned to it, that public IP moves along with the private IP.
  • Running multiple services or endpoints on a single instance: For example, you could have multiple container pods running on a single instance, and each uses an IP address from the VCN's CIDR. The containers have direct connectivity to other instances and services in the VCN. Another example: you could run multiple SSL websites with each one using its own IP address.

Here are more details about secondary private IP addresses:

  • They're supported for all shapes and OS types, for both bare metal and VM instances.
  • A VNIC can have a maximum of 31 secondary private IPs.
  • They can be assigned only after the instance is launched (or the secondary VNIC is created/attached).
  • A secondary private IP that is assigned to a VNIC in a regional subnet has a null availability domain attribute. Compare this with the VNIC's primary private IP, which always has its availability domain attribute set to the instance's availability domain, regardless of whether the instance's subnet is regional or AD-specific.
  • Deleting a secondary private IP from a VNIC returns the address to the pool of available addresses in the subnet.
  • They are automatically deleted when you terminate the instance (or detach/delete the secondary VNIC).
  • The instance's bandwidth is fixed regardless of the number of private IP addresses attached. You can't specify a bandwidth limit for a particular IP address on an instance.
  • A secondary private IP can have a reserved public IP assigned to it at your discretion.

IP Address Information in the Instance Metadata

The instance metadata includes information about the private IP addresses at this URL:
http://169.254.169.254/opc/v1/vnics/

Here's an example response:

[ {
  "vnicId" : "ocid1.vnic.oc1.sea.<unique_ID>",
  "privateIp" : "10.0.3.6",
  "vlanTag" : 11,
  "macAddr" : "00:00:00:00:00:01",
  "virtualRouterIp" : "10.0.3.1",
  "subnetCidrBlock" : "10.0.3.0/24"
}, {
  "vnicId" : "ocid1.vnic.oc1.sea.<unique_ID>",
  "privateIp" : "10.0.4.3",
  "vlanTag" : 12,
  "macAddr" : "00:00:00:00:00:01",
  "virtualRouterIp" : "10.0.4.1",
  "subnetCidrBlock" : "10.0.4.0/24"
} ]

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: see IAM Policies for Networking.

Using the Console

To view an instance's private IPs
  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs assigned to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

To assign a new secondary private IP to a VNIC
  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs attached to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

  7. Click Assign Secondary Private IP Address.

  8. Enter the following:

    • Private IP Address: Optional. An available private IP address of your choice from the subnet's CIDR (otherwise the private IP address is automatically assigned).
    • Unassign if already assigned to another VNIC: Select this check box to force reassignment of the IP address if it's already assigned to another VNIC in the subnet. Relevant only if you specify a private IP address in the preceding field.
    • Hostname: Optional. A hostname to be used for DNS within the cloud network. Available only if the VCN and subnet both have DNS labels. See DNS in Your Virtual Cloud Network.
    • Public IP Type: Whether to assign a public IP address. Available only if the VNIC is in a public subnet. See Public IP Addresses.

  9. Click Assign.

    The secondary private IP is created and then displayed on the IP Addresses page for the VNIC.

  10. Configure the IP address:

To move a secondary private IP to another VNIC in the same subnet
  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs attached to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

  7. Click Assign Secondary Private IP Address.

  8. Enter the following:

    • Private IP Address: The secondary private IP address you want to move.
    • Unassign if already assigned to another VNIC: Select this check box to move the secondary IP address from the VNIC it's currently assigned to.
    • Hostname: Optional. The hostname to be used for DNS within the cloud network. Available only if the VCN and subnet both have DNS labels. See DNS in Your Virtual Cloud Network.
    • Public IP Type: Whether to assign a public IP address. Available only if the VNIC is in a public subnet. See Public IP Addresses.
  9. Click Assign.

The private IP address is moved from the original VNIC to the new VNIC.

To update the hostname for an existing private IP
  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs attached to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

  7. For the IP address you're interested in, click the Actions menu, and then click Edit.
  8. Make your changes and click Update.
To delete a secondary private IP from a VNIC
Caution

If the private IP is the target of a route rule, deleting it from the VNIC causes the route rule to blackhole and the traffic will be dropped.

Prerequisite: Oracle recommends removing the IP address from the OS configuration before deleting it from the VNIC. See Linux: Details about Secondary IP Addresses or Windows: Details about Secondary IP Addresses.

  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs attached to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

  7. For the private IP you want to delete, click the Actions menu, and then click Delete Private IP.
  8. Confirm when prompted.

The private IP address is returned to the pool of available addresses in the subnet.

To manage tags for a private IP
  1. Confirm you're viewing the compartment that contains the instance you're interested in.
  2. Open the navigation menu and click Compute. Under Compute, click Instances.
  3. Click the instance to view its details.

  4. Under Resources, click Attached VNICs.

    The primary VNIC and any secondary VNICs attached to the instance are displayed.

  5. Click the VNIC that you're interested in.

  6. Under Resources, click IP Addresses.

    The VNIC's primary private IP and any secondary private IPs are displayed.

  7. For the private IP you're interested in, click the Actions menu, and then click View Tags. From there you can view the existing tags, edit them, and apply new ones.

For more information, see Resource Tags.

Using the API

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

To manage private IPs on a VNIC, use these operations:

  • GetPrivateIp: Use this to get a single privateIp object by specifying its OCID.
  • ListPrivateIps: Use this to get a single privateIp object by specifying the private IP address (for example, 10.0.3.3) and the subnet's OCID. Or you can list all the privateIp objects in a given subnet, or just the ones assigned to a given VNIC.
  • CreatePrivateIp: Use this to assign a new secondary private IP to a VNIC.
  • UpdatePrivateIp: Use this to reassign a secondary private IP to a different VNIC in the same subnet, or to update the hostname or display name of a secondary private IP.
  • DeletePrivateIp: Use this to delete a secondary private IP from a VNIC. The private IP address is returned to the subnet's pool of available addresses.

Linux: Details about Secondary IP Addresses

After assigning a secondary private IP to a VNIC, you must configure the OS to use it.

Basic Commands (Not Persistent Through a Reboot)

On the instance, run the following command. It works on all variants of Linux, for both bare metal and VM instances:
ip addr add <address>/<subnet_prefix_len> dev <phys_dev> label <phys_dev>:<addr_seq_num>
where:
  • <address>: The secondary private IP address.
  • <subnet_prefix_len>: The subnet's prefix length. For example, if the subnet is 192.168.20.0/24, the subnet prefix length is 24.
  • <phys_dev>: The interface to add the address to (for example, ens2f0).
  • <addr_seq_num>: The sequential number in the stack of addresses on the device (for example, 0).
For example:
ip addr add 192.168.20.50/24 dev ens2f0 label ens2f0:0

Later if you want to delete the address, you can use:

ip addr del 192.168.20.50/24 dev ens2f0:0

Also make sure to delete the secondary IP from the VNIC. You can do that before or after executing the above command to delete the address from the OS configuration.

Note

If you've assigned a secondary IP to a secondary VNIC, and you're using policy-based routing for the secondary VNIC, configure the route rules for the instance to look up the same route table for the secondary IP address, using the ip rule add from <source address> lookup <table name> command.

Configuration File (Persistent Through a Reboot)

You can make the configuration persistent through a reboot by adding the information to a configuration file.

For Oracle Linux and CentOS

For Oracle Linux 7, create an ifcfg file named /etc/sysconfig/network-scripts/ifcfg-<phys_dev>:<addr_seq_num>. To continue with the preceding example, the file name would be /etc/sysconfig/network-scripts/ifcfg-ens2f0:0, and the contents would be:

DEVICE="ens2f0:0"
BOOTPROTO=static
IPADDR=192.168.0.50
NETMASK=255.255.255.0
ONBOOT=yes

For Oracle Linux 8 or Oracle Linux 9, the preferred method would be to use nmcli to configure the interface for NetworkManager.

If Network Manager overwrites the connections after reboot, the preferred solution is to run the ip addr add <address>/<subnet_prefix_len> dev <phys_dev> label <phys_dev>:<addr_seq_num> command at boot time. This can be done with a cron job, or using /etc/rc.d/rc.local etc. Alternatively, you can modify the kernel command line parameters so that dracut doesn’t overwrite NetworkManager connection profiles.

Note

If you've assigned a secondary IP to a secondary VNIC, and you're using policy-based routing for the secondary VNIC, configure the route rules for the instance to look up the same route table for the secondary IP address, using the ip rule add from <source address> lookup <table name> command.

For Ubuntu

Create or modify a netplan configuration stored at /etc/netplan/<filename>.yaml. To continue with the preceding example, the file name would be /etc/netplan/50-cloud-init.yaml, and it would be modified to disable DHCP (for all addresses) and replace it with manual configuration as shown:


network:
  ethernets:
    ens3: 
      dhcp4: no
    addresses: [192.168.64.223/24, 192.168.64.75/24]
    gateway4: 192.168.64.1
    nameservers:
      addresses: [169.254.169.254] 
    match:
      macaddress: 02:00:17:0e:66:7b
    set-name: ens3  
    version: 2

In this example, 192.168.64.223 is the primary IP address assigned to the VNIC and 192.168.64.75 is the secondary IP address. macaddress refers to the VNIC, and this can be found in the console or via oci-utils. More complex netplan configuration examples can be found at the netplan reference pages. See Attaching VLANs to network interfaces for an upstream example.

Note

If you've assigned a secondary IP to a secondary VNIC, and you're using policy-based routing for the secondary VNIC, configure the route rules for the instance to look up the same route table for the secondary IP address, using the ip rule add from <source address> lookup <table name> command.

Windows: Details about Secondary IP Addresses

After assigning a secondary private IP to a VNIC, you must configure the OS to use it. Here are instructions for using a PowerShell script or the Network and Sharing Center UI.
Using a PowerShell Script

You must run PowerShell as an administrator. The script configures two things: static IP addressing on the instance and the secondary private IP. The configuration persists through a reboot of the instance.

  1. In your browser, go to the Console, and note the secondary private IP address that you want to configure on the instance.

  2. Connect to the instance, and run the following command at a command prompt:

    ipconfig /all

  3. Note the values for the following items so you can enter them into the script in the next step:

    • Default Gateway
    • DNS Servers

  4. Replace the variables in the following PowerShell script with your own values:

    $netadapter = Get-Netadapter -Name "Ethernet 2"
$netadapter | Set-NetIPInterface -DHCP Disabled
$netadapter | New-NetIPAddress -AddressFamily IPv4 -IPAddress <secondary_IP_address> -PrefixLength <subnet_prefix_length> -Type Unicast -DefaultGateway <default_gateway>
Set-DnsClientServerAddress -InterfaceAlias "Ethernet 2" -ServerAddresses <DNS_server>

    For example:

    $netadapter = Get-Netadapter -Name "Ethernet 2"
$netadapter | Set-NetIPInterface -DHCP Disabled
$netadapter | New-NetIPAddress -AddressFamily IPv4 -IPAddress 192.168.0.14 -PrefixLength 24 -Type Unicast -DefaultGateway 192.168.0.1
Set-DnsClientServerAddress -InterfaceAlias "Ethernet 2" -ServerAddresses 203.0.113.254

  5. Save the script with the name of your choice and a .ps1 extension, and run it on the instance.

    This image shows the PowerShell script for configuring a secondary private IP address.

    If you run ipconfig /all again, you'll see that DHCP has been disabled and the secondary private IP address is included in the list of IP addresses.

Later if you want to delete the address, you can use this command:

Remove-NetIPAddress -IPAddress 192.168.11.14 -InterfaceAlias Ethernet

Also make sure to delete the secondary IP from the VNIC. You can do that before or after executing the above command to delete the address from the OS configuration.

Using the Network and Sharing Center UI

The following instructions configure two things: static IP addressing on the instance and the secondary private IP. The configuration persists through a reboot of the instance.

  1. In your browser, go to the Console, and note the secondary private IP address that you want to configure on the instance.

  2. Connect to the instance, and run the following command at a command prompt:

    ipconfig /all
    This image shows the results of the ipconfig /all command.

  3. Note the values for the following items so you can enter them elsewhere in a later step:

    • IPv4 Address
    • Subnet Mask
    • Default Gateway
    • DNS Servers
  4. In the instance's Control Panel, open the Network and Sharing Center (see the image below for the set of dialog boxes you'll see in these steps).
  5. For the active networks, click the connection (Ethernet).
  6. Click Properties.
  7. Click Internet Protocol Version 4 (TCP/IPv4), and then click Properties.

  8. Select the radio button for Use the following IP address, and then enter the values you noted earlier for the IP address, subnet mask, default gateway, and DNS servers.

    This image shows the series of dialog boxes you'll encounter.
  9. Click Advanced....
  10. Under IP addresses, click Add....

  11. Enter the secondary private IP address and the subnet mask you used earlier and click Add.

    This image shows the dialog box for adding the secondary private IP address.
  12. Click OK until the Network and Sharing Center is closed.

  13. Verify the changes by returning to the command prompt and running ipconfig /all.

    You should now see that DHCP is disabled (static IP addressing is enabled), and the secondary private IP address is in the list of addresses displayed. The address is now configured on the instance and available to use.

    This image shows the results of the ipconfig /all command after you've added the secondary private IP address.
    Note

    You might not see the primary private IP address when you again view the properties for Internet Protocol Version 4 (TCP/IPv4) in the Network and Sharing Center UI. The best way to confirm your changes is to use ipconfig /all at the command line.