§ Wiki · Wiki entry

Updating a Node's IPv4 Address and Domain Name

Two procedures — IC-OS reinstall and a non-disruptive dfx call — for updating the public IPv4 address and domain name of an existing node.

·May 4, 2026·3 min read

Each node provider is asked to deploy at least two nodes with public IPv4 addresses and registered domain names in every data center they operate in — specifically on the first two nodes of the first rack at each site. Beyond that pair, additional nodes can run on IPv6 only. See the Node Provider Networking Guide for the underlying rule.

This entry covers what to do when an IPv4 address or domain name has to change for an existing node. There are two methods. Pick the one that matches how the node was onboarded.

[!NOTE] Each IPv4 address must be unique to one node. Do not reuse an IPv4 address across machines.

Prerequisites

  • The IPv4 address, prefix length, and gateway provided by the data center.
  • A registered domain name for the node — see the Node Provider Domain Name Guide.
  • Either physical access to the node and its installation USB (Method 1), or the node_operator_private_key.pem file (Method 2).

Method 1 — IC-OS reinstall

Use this method for nodes onboarded with a Nitrokey HSM. The change requires a fresh IC-OS install.

  1. Follow the deployment guide for your generation: Gen-2 or Gen-1.
  2. At step 6 of the guide, configure the new IPv4 address, prefix length, gateway, and domain name.
  3. Reinstall IC-OS from the USB stick.
  4. Repeat for each node, reconfiguring the USB stick between deployments — each node must have a unique IPv4 address, so a single USB image cannot be reused.

[!TIP] Always use the latest IC-OS release for the reinstall. Older images may fail to deploy.

Method 2 — dfx call (no redeployment)

Use this method for nodes onboarded without a Nitrokey HSM, using a PEM-based node operator key.

Step 1 — Import the node operator identity

dfx upgrade
dfx identity import node_operator node_operator_private_key.pem \
  --storage-mode=plaintext

Step 2 — Set the variables

NODE_ID="xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx"
IPV4_PREFIX_LENGTH="xx"
IPV4_ADDRESS="xxx.xxx.xxx.xxx"
IPV4_GATEWAY="xxx.xxx.xxx.xxx"
DOMAIN="node.example.com"

Step 3 — Update the IPv4 configuration and domain

dfx canister --network ic --identity node_operator \
  call rwlgt-iiaaa-aaaaa-aaaaa-cai update_node_ipv4_config_directly \
  "(record { ipv4_config = opt record { gateway_ip_addr = \"$IPV4_GATEWAY\"; prefix_length = $IPV4_PREFIX_LENGTH : nat32; ip_addr = \"$IPV4_ADDRESS\"}; node_id = principal \"$NODE_ID\" })"

dfx canister --network ic --identity node_operator \
  call rwlgt-iiaaa-aaaaa-aaaaa-cai update_node_domain_directly \
  "(record { node_id = principal \"$NODE_ID\"; domain = opt \"$DOMAIN\" })"

The target canister rwlgt-iiaaa-aaaaa-aaaaa-cai is the registry canister.

Removing IPv4 and domain settings

To clear the IPv4 configuration or domain (for example, when retiring the public IPv4 role on a node), pass null:

dfx canister --network ic --identity node_operator \
  call rwlgt-iiaaa-aaaaa-aaaaa-cai update_node_ipv4_config_directly \
  "(record { ipv4_config = null; node_id = principal \"$NODE_ID\" })"

dfx canister --network ic --identity node_operator \
  call rwlgt-iiaaa-aaaaa-aaaaa-cai update_node_domain_directly \
  "(record { node_id = principal \"$NODE_ID\"; domain = null })"

Related