TrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Setting Up Static IPs

7 minute read.

Last Modified 2024-04-02 12:05 EDT

This article describes setting up a network interface with a static IP address or changing the main interface from a DHCP-assigned to a manually-entered static IP address. You must know the DNS name server and default gateway addresses for your IP address.

Disruptive Change!
You can lose your TrueNAS connection if you change the network interface that the web interface uses!
Command line knowledge and physical access to the TrueNAS system are often required to fix misconfigured network settings.

Multiple interfaces connected to a single TrueNAS system cannot be members of the same subnet.
You can combine multiple interfaces with link aggregation (LAGG) or a network bridge. Alternatively, you can assign multiple static IP addresses to a single interface by configuring aliases.
Click for more information
When multiple network interface cards (NICs) connect to the same subnet, users might incorrectly assume that the interfaces automatically load balance. However, ethernet network topology allows only one interface to communicate at a time. Additionally, both interfaces must handle broadcast messages since they are listening on the same network. This configuration adds complexity and significantly reduces network throughput.
If you require multiple NICs on a single network for performance optimization, you can use a link aggregation (LAGG) configured with Link Aggregation Control Protocol (LACP). A single LAGG interface with multiple NICs appears as a single connection to the network.
While LACP is beneficial for larger deployments with many active clients, it might not be practical for smaller setups. It provides additional bandwidth or redundancy for critical networking situations. However LACP has limitations as it does not load balance packets.
On the other hand, if you need multiple IP addresses on a single subnet, you can configure one or more static IP aliases for a single NIC.
In summary, we recommend using LACP if you need multiple interfaces on a network. If you need multiple IP addresses, define aliases. Deviation from these practices might result in unexpected behavior.
For a detailed explanation of ethernet networking concepts and best practices for networking multiple NICs, refer to this discussion from National Instruments.

DHCP or Static IP?

By default, during installation, TrueNAS SCALE configures the primary network interface for Dynamic Host Configuration Protocol (DHCP) IP address management. However, some administrators might choose to assign a static IP address to the primary network interface. This choice may be made if TrueNAS is deployed on a system that does not allow DHCP for security, stability, or other reasons.

In all deployments, only one interface can be set up for DHCP, which is typically the primary network interface configured during the installation process. Any additional interfaces must be manually configured with one or more static IP addresses.

One Static IP Address or Multiple Aliases?

One or More Aliases?

Static IP addresses set a fixed address for an interface that external devices or websites need to access or remember, such as for VPN access.

Use aliases to add multiple internal IP addresses, representing containers or applications hosted in a VM, to an existing network interface without having to define a separate network interface.

In the UI, you can add aliases when adding or editing an existing interface using the Add button to the right of the Aliases. To add a static IP. Click Add again to add an additional alias.

From the Console Setup menu, select option 1 to configure network settings and add alias IP addresses.

Before You Begin

Have the DNS name server addresses, the default gateway for the new IP address, and any static IP addresses on hand to prevent lost communication with the server while making and testing network changes. You have only 60 seconds to change and test these network settings before they revert back to the current settings, for example back to DHCP assigned if moving from DHCP to a static IP.

Back up your system to preserve your data and system settings. Save the system configuration file and a system debug.

As a precaution, grab a screenshot of your current settings in the Global Configuration widget.

If your network changes result in lost communication with the network and you need to return to the DHCP configuration, you can refer to this information to restore communication with your server. Lost communication might require reconfiguring your network settings using the Console Setup menu.

Changing to a Static IP Address

To view a demonstration of this procedure see the tutorial video in the Managing Global Configuration article.

To change an interface from using DHCP to a static IP address:

Click on the Edit icon for the interface on the Interfaces widget to open the Edit Interface screen, then clear the DHCP checkbox.
Figure 1: Clear DHCP Checkbox
Click Add to the right of Aliases to add IP address fields, then enter the new static IP. Select the CIDR number from the dropdown list.
Figure 2: Add Alias IP Address
Multiple interfaces cannot be members of the same subnet.
If an error displays or the Save button is inactive when setting the IP addresses on multiple interfaces, check the subnet and ensure the CIDR numbers differ.
Click Save. A dialog opens where you can select to either Test Changes or Revert Changes. If you have only one active network interface the system protects your connection to the interface by displaying the Test Changes dialog.
You have 60 seconds to test and save the change before the system discards the change and reverts back to the DHCP-configured IP address.
Check the name servers and default router information in the Global Information widget. If the current settings are not on the same network, click Settings and modify each setting as needed to allow the static IP to communicate over the network.
Add the IP addresses for the DNS name servers in the Nameserver 1, Nameserver 2, and Nameserver 3 fields.
Figure 3: Add Name Server and Default Gateway
For home users, use 8.8.8.8 for a DNS name server address so you can communicate with external networks.
Add the IP address for the default gateway in the appropriate field. If the static network is IPv4 enter the gateway in IPv4 Default Gateway, if the static network is IPv6 use IPv6 Default Gateway.
Click Save.
Test the network changes. Click Test Changes. Select Confirm to activate Test Changes button.
Figure 4: Test Changes
The system attempts to connect to the new static IP address. If successful the Save Changes dialog displays.
Figure 5: Save Changes
Click Save Changes to make the change to the static IP address permanent or click Revert Changes to discard changes and return to previous settings. The Save Changes confirmation dialog displays. Click SAVE. The system displays a final confirmation that the change is in effect.
Figure 6: Network Change Made Permanent

Returning to DHCP from Static IP

Only one interface can use DHCP to assign the IP address and that is likely the primary network interface. If you do not have an existing network interface set to use DHCP you can convert an interface from static IP to DHCP.

To switch/return to using DHCP:

Click Settings on the Global Configuration widget.
Clear the name server fields and the default gateway, and then click Save.
Click on the Edit icon for the interface to display the Edit Interface screen.
Select DHCP.
Remove the static IP address from the IP Address field.
Click Apply.
Click Settings to display the Global Configuration screen, then enter the name server and default gateway addresses for the new DHCP-provided IP address.
Home users can enter 8.8.8.8 in the Nameserver 1 field.
Click Test Change. If the network settings are correct, the screen displays the Save Changes widget. Click Save Changes.
If the test network operation fails or the system times out, your system returns to the network settings before you attempted the change. Verify the name server and default gateway information to try again.