network

14 minute read.

Last Modified 2023-11-16 10:20 EST

The TrueNAS CLI guide for SCALE is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

network commands are based on network functions found in the SCALE API and web UI. Use these commands to create and manage global network setting, interfaces, static routes, and IPMI connections.

Enter commands from the main CLI prompt or from the network namespace prompt.

Interactive Arguments Editor

The interactive argument editor is a text user interface (TUI) that can help enter complex commands with multiple configurable properties. It shows expected properties, defaults, input types (string, boolean, integer, or array), and can include command instructions or warnings.

Optional properties, indicated by the # symbol, are disabled by default. Required properties are enabled. Do not disable properties that are enabled by default.

To configure required properties, enter a space after the colon then add the value.

To enable optional properties, delete # from the corresponding line.

Some required properties are disabled if they are part of a pair of properties where one or the other is required. Select one property to enable and enter a value.

Press F2 or click Save to save the modified file.

Press F10, Esc, or click Quit to exit the TUI. The command automatically executes upon exit.

Enter network ls to view the list of available commands and namespaces.

network configuration config

The network configuration config command displays the current system configuration network settings.

network configuration config does not require entering a property argument.

Enter the command then press Enter. The command returns a list of network configuration settings including the system-assigned id, hostname, domain, IPv4 and IPv6 gateways, nameservers 1-3, HTTP proxy, hosts, domains, service announcement, activity, local hostname and state.

Command Example

network configuration config

>>>

+----------------------+--------------+
|                   id | 1            |
|             hostname | truenas      |
|               domain | local        |
|          ipv4gateway |              |
|          ipv6gateway |              |
|          nameserver1 |              |
|          nameserver2 |              |
|          nameserver3 |              |
|            httpproxy |              |
|                hosts | <empty list> |
|              domains | <empty list> |
| service_announcement | <dict>       |
|             activity | <dict>       |
|       hostname_local | truenas      |
|                state | <dict>       |
+----------------------+--------------+

network configuration update

Use the network configuration update command to change global network configuration settings.

network configuration update has 14 properties you can change. See Update Properties below for details.

Enter the command string then press Enter or enter – to open the interactive command editor if changing multiple property values. The command returns an empty line. Use network configuration config to verify any changes made.

network configuration update Properties

Enter property arguments using the = delimiter to separate property and value. Double-quote values that include special characters. For example:

Enter property arguments enclosed in curly brackets {} with double-quoted properties and values separated by the : delimiter. Separated multiple property arguments with a comma.

Property	Description	Syntax Example
`hostname`	Enter the hostname for the TrueNAS SCALE system. Default hostname is `truenas`.	`hostname="hostName"`
`domain`	Enter the domain for the TrueNAS system. For example, mycompany.com.	`domain="domainName"`
`ipv4gateway`	Enter the IP address to use instead of the DHCP-provided IP address, if DHCP is enabled. Entering an IP address overrides the default gateway provided by DHCP.	`ipv4gateway="IPaddress"`
`ipv6gateway`	Enter the IP address to use instead of the DHCP-provided IP address, if DHCP is enabled on and IPV6 network. Entering an IP address overrides the default gateway provided by DHCP.	`ipv6gateway="IPaddress"`
`nameserver1`	Enter the IP address of the primary DNS server.	`nameserver1="IPaddress"`
`nameserver2`	Enter the IP address of the secondary DNS server.	`nameserver2="IPaddress"`
`nameserver3`	Enter the IP address for the third DNS server.	`nameserver3="IPaddress"`
`httpproxy`	Required if using a proxy for network operations.	`httpproxy="proxyName"`
`hosts`	Enter the host IP(s) as the value for the `host` property argument. Enter the property argument inside the `[]`, with each host IP address separated by a comma.	`hosts="HostName"`
`hostname_b`	Used in HA-licensed systems to enter the IP address or host name for controller 2.	`hostname_b="HostName"`
`hostname_virtual`	Used in HA-licensed systems as the virtual IP address or host name for access to the web UI regardless of which controller is active.	`hostname_virtual="HostName"`

Command Example

network configuration update nameserver1=“10.123.0.11”

network dns query

The network dns query command displays a table listing the current DNS nameserver IP addresses configured on the system.

network dns query does not require entering a property argument.

Enter the commmand then press Enter. The command returns the current DNS nameserver IP addresses configured on the system.

Command Example

[truenas]> network dns query
+-------------+
| nameserver  |
+-------------+
| 10.123.0.45 |
| 10.123.0.46 |
| 10.123.45.1 |
+-------------+

network general summary

The network general summary command lists network default routes and nameserver IP addresses.

network general summary does not require entering property arguments.

Enter the command then press Enter. The command returns a table with default routes, nameserver IP addresses, and a dictionary for IPs configured on the system.

Command Example

Command: network general summary
Output:
+----------------+-------------+
|            ips | <dict>      |
| default_routes | 10.234.24.1 |
|    nameservers | 10.220.0.11 |
+----------------+-------------+

network interfaces

The TrueNAS CLI guide for SCALE is a work in progress! This command has not been fully tested and validated. Full documentation is still being developed. Check back for updated information.

network ipmi channels

The network ipmi channels command displays a list of available IPMI channels.

network ipmi channels does not require entering property arguments.

Enter the command, then press Enter. The command returns the number of IPMI channels the system has available.

Command Example

network ipmi channels
1

network ipmi get_instance

The network ipmi get_instance command displays the settings for the IPMI channel ID entered.

Use the network ipmi query command to obtain the channel ID.

network ipmi get_instance has one required property, id. id is the system-assinged number for an IPMI channel found in the output of the network ipmi query command.

Enter the command string, then press Enter. The command returns a table with the specified IPMI channel settings, including the IP address type, IP address, MAC address, subnet mask, gateway IP address, gateway MAC address, backup gateway IP, address, backup gateway MAC address, VLAN ID, VLAN ID status, and VLAN ID priority.

Command Example

network ipmi get_instance id=1
+-----------------------------+-------------------+
|                     channel | 1                 |
|                          id | 1                 |
|           ip_address_source | static            |
|                  ip_address | 10.10.10.10       |
|                 mac_address | 3c:ec:de:5b:5e:58 |
|                 subnet_mask | 255.255.255.0     |
|  default_gateway_ip_address | 10.200.0.1        |
| default_gateway_mac_address | 00:00:00:00:00:00 |
|   backup_gateway_ip_address | 0.0.0.0           |
|  backup_gateway_mac_address | 00:00:00:00:00:00 |
|                     vlan_id | 0                 |
|              vlan_id_enable | false             |
|               vlan_priority | 0                 |
+-----------------------------+-------------------+

network ipmi query

The network ipmi query command displays a table of all IPMI channels and their settings.

network ipmi query does not require entering properties or arguments.

Enter the command, then press Enter. The command returns a table of all IPMI instances and their settings, including IP addresses type, IP addresses, MAC addresses, subnet masks, gateway IP addresses, gateway MAC addresses, backup gateway IP addresses, backup gateway MAC addresses, VLAN IDs, VLAN ID statuses, and VLAN ID priorities.

Command Example

network ipmi query
+---------+----+-------------------+-------------+-------------------+---------------+----------------------------+-----------------------------+---------------------------+----------------------------+---------+----------------+---------------+
| channel | id | ip_address_source | ip_address  | mac_address       | subnet_mask   | default_gateway_ip_address | default_gateway_mac_address | backup_gateway_ip_address | backup_gateway_mac_address | vlan_id | vlan_id_enable | vlan_priority |
+---------+----+-------------------+-------------+-------------------+---------------+----------------------------+-----------------------------+---------------------------+----------------------------+---------+----------------+---------------+
| 1       | 1  | static            | 10.10.10.10 | 3c:ec:de:5b:5e:70 | 255.255.255.0 | 10.200.0.1                 | 00:00:00:00:00:00           | 0.0.0.0                   | 00:00:00:00:00:00          | 0       | false          | 0             |
+---------+----+-------------------+-------------+-------------------+---------------+----------------------------+-----------------------------+---------------------------+----------------------------+---------+----------------+---------------+

network ipmi update

The network ipmi update command allows you to update the settings for a specified IPMI instance.

Use the network ipmi query command to obtain the system-assigned channel ID, and to verify changes made.

network ipmi update has one required property, channel, and six configuration properties. See Update Properties below for details. channel is the ID number assigned to a network channel found in output of the network ipmi query command.

Enter the command string then press Enter. The command returns a blank line.

network ipmi update Properties

Property	Description	Syntax Example
`ipaddress`	Enter the IPv4 address to assign to the channel.	`ipaddress="ipaddress"`
`netmask`	Enter the subnet mask associated with the IP address.	`netmask="nest-expandednetmask"/i>"`
`gateway`	Enter the IPv4 address the IPMI `ipaddress` uses to reach outside the local subnet.	`gateway="gateway"`
`password`	Enter a password to assign to the channel. The password must be between 8 and 16 characters and contain at least 3 of the following categories: lowercase character, uppercase character, digits 0-9, special characters (!, $, #, %, etc.)	`password=password`
`dhcp`	Enter `false` to define `ipaddress`, `netmask`, and `gateway`.	`dhcp=true/false`
`vlan`	Enter a numeric VLAN ID.	`vlan=integer`

Command Example

network ipmi update channel=1 ipaddress="10.230.0.10" netmask="255.255.240.0" gateway="10.230.0.1"

network route ipv4gw_reachable

The network route ipv4gw_reachable verifies the ipv4 gateway is reachable by an interface.

Use the network route static_routes command to locate the gateway (ipv4 gateway) configured on the system.

network route ipv4gw_reachable has one required property, ipv4_gateway. ipv4_gateway is the IP address for the ipv4 gateway.

Enter the property argument using the = delimiter to separate property and double-quoted value. Enter the command string then press Enter. The command returns true if the gateway is reachable, false if not.

Command Example

network route ipv4gw_reachable ipv4_gateway="10.123.24.1"
true

network route system_routes

The network route system_routes command lists network default routes and nameserver IP addresses.

network route system_routes does not require entering property arguments.

Enter the command then press Enter The command returns a table with network,

network route system_routes -------------------------+-------------+---------------+--------------+----------+-------+------------------+ | gateway     | interface     | flags        | table_id | scope | preferred_source | -------------------------+-------------+---------------+--------------+----------+-------+------------------+ | <null>      | kube-bridge   | <empty list> | 77       | 253   | 172.16.0.1       | | <null>      | lo            | <empty list> | 78       | 254   | <null>           | | 10.234.24.1 | enX0          | <empty list> | 254      | 0     | <null>           | | <null>      | enX0          | <empty list> | 254      | 253   | 10.234.27.252    | | <null>      | kube-bridge   | <empty list> | 254      | 253   | 172.16.0.1       | | <null>      | enX0          | <empty list> | 255      | 254   | 10.234.27.252    | | <null>      | enX0          | <empty list> | 255      | 253   | 10.234.27.252    | | <null>      | lo            | <empty list> | 255      | 254   | 127.0.0.1        | | <null>      | lo            | <empty list> | 255      | 254   | 127.0.0.1        | | <null>      | lo            | <empty list> | 255      | 253   | 127.0.0.1        | | <null>      | kube-bridge   | <empty list> | 255      | 254   | 172.16.0.1       | | <null>      | kube-bridge   | <empty list> | 255      | 253   | 172.16.0.1       | | <null>      | kube-dummy-if | <empty list> | 255      | 254   | 10.234.27.252    | | <null>      | kube-dummy-if | <empty list> | 255      | 254   | 10.234.27.252    | | <null>      | kube-bridge   | <empty list> | 77       | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | lo            | <empty list> | 254      | 0     | <null>           | | <null>      | enX0          | <empty list> | 254      | 0     | <null>           | | <null>      | kube-bridge   | <empty list> | 254      | 0     | <null>           | | <null>      | kube-dummy-if | <empty list> | 254      | 0     | <null>           | | <null>      | veth400353c2  | <empty list> | 254      | 0     | <null>           | | <null>      | veth35f76096  | <empty list> | 254      | 0     | <null>           | | <null>      | veth5473be81  | <empty list> | 254      | 0     | <null>           | | <null>      | veth6ecbbda6  | <empty list> | 254      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | lo            | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | enX0          | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | veth35f76096  | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | veth400353c2  | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | kube-dummy-if | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | kube-bridge   | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | veth6ecbbda6  | <empty list> | 255      | 0     | <null>           | ffff:ffff:ffff:ffff:ffff | <null>      | veth5473be81  | <empty list> | 255      | 0     | <null>           | | <null>      | enX0          | <empty list> | 255      | 0     | <null>           | | <null>      | kube-bridge   | <empty list> | 255      | 0     | <null>           | | <null>      | kube-dummy-if | <empty list> | 255      | 0     | <null>           | | <null>      | veth400353c2  | <empty list> | 255      | 0     | <null>           | | <null>      | veth35f76096  | <empty list> | 255      | 0     | <null>           | | <null>      | veth5473be81  | <empty list> | 255      | 0     | <null>           | | <null>      | veth6ecbbda6  | <empty list> | 255      | 0     | <null>           | -------------------------+-------------+---------------+--------------+----------+-------+------------------+ .anchor-link{display:none}.expand-details:hover .anchor-link{display:inline}
network static_route create
The
network static_route create

command adds a single static route IP address and gateway to the system.
network static_route create

has three required properties, destination, gateway, and description.
See network static_route create Properties below for details.
Enter the property arguments using the = delimiter to separate property and value. Double-quote values with special characters.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query

command to verify creation of the static route.
network static_route create Properties
Property Required Description Syntax Example
destination Yes Enter the IP address in the format a.b.c.d/e for the static route you want to create. destination="a.b.c.d/e"
gateway Yes Enter the IP address for the gateway for the destination IP address in the format a.b.c.d. gateway="a.b.c.d"
description No Enter optional text to describe the static route. description="test"

Command Example
network static_route create destination="10.123.0.123/20" gateway="10.123.0.1" description="test"
network static_route delete
The
network static_route delete

command deletes the static route matching the ID entered.
network static_route delete

has one required property, id.
id is the system-assigned ID for the static route found in the output of the
network static_route query

command.
Enter the property argument using the = delimiter to separate property and value.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query

command to verify deletion of the static route.

Command Example
network static_route delete id=1
network static_route query
The
network static_route query

command lists details on static routes added to the system.
network static_route query

does not require entering a property argument, but you can enter any one of the three properties as a flag to narrow the information returned to list just that property for all static routes.
Properties are id, destination, gateway, and description.
Enter the command then press Enter.
The command returns the values for all static routes configured on the system.

Command Example
network static_route query
+----+-----------------+------------+-------------+
| id | destination     | gateway    | description |
+----+-----------------+------------+-------------+
| 1  | 10.123.0.123/20 | 10.123.0.1 | TEST        |
+----+-----------------+------------+-------------+
network static_route update
Use the
network static_route update

command to change the properties of the static route matching the ID entered.
network static_route update

has one required property, id, and three optional properties.
id is the system-assigned ID for the static route found in the output of the
network static_route query

command.
See Update Properties below for details.
Enter the property arguments using the = delimiter to separate property and value. Double-quote values with special characters.
Enter the command string then press Enter.
The command returns an empty line. Enter the
network static_route query

command to verify updates to the static route.
network static_route update Properties
Property Description Syntax Example
destination Enter the IP address in the format a.b.c.d/e for the static route you want to create. destination="a.b.c.d/e"
gateway Enter the IP address for the gateway for the destination IP address in the format a.b.c.d. gateway="a.b.c.d"
description Enter optional text to describe the static route. description="test"

Command Example
network static_route update id=1 description="test route"

Property	Required	Description	Syntax Example
`destination`	Yes	Enter the IP address in the format a.b.c.d/e for the static route you want to create.	`destination="a.b.c.d/e"`
`gateway`	Yes	Enter the IP address for the gateway for the destination IP address in the format a.b.c.d.	`gateway="a.b.c.d"`
`description`	No	Enter optional text to describe the static route.	`description="test"`