Updating a Node's IPv4 Address and Domain Name

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.

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 key that onboarded the node (Method 2) — the node_operator_private_key.pem file, or the Nitrokey HSM for nodes onboarded with one.

Method 1 — IC-OS reinstall

Use this method if you no longer have the node operator key — neither the PEM file nor the 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.

Method 2 — icp call (no redeployment)

Use this method when you still have the node operator key, whether a PEM file or a Nitrokey HSM. The change is applied directly in the registry, without a proposal or a reinstall.

Step 1 — Set up the node operator identity

Both variants create an icp identity named node_operator, which the commands below use.

PEM key (nodes onboarded without an HSM):

icp identity import --storage plaintext \
  --from-pem node_operator_private_key.pem node_operator

Nitrokey HSM (nodes onboarded with an HSM): retrieve the HSM that signed the node operator record, plug it into your workstation, and link it. The PKCS#11 library path differs by operating system:

# macOS
icp identity link hsm node_operator \
  --key-id 01 \
  --pkcs11-module /Library/OpenSC/lib/opensc-pkcs11.so

# Linux
icp identity link hsm node_operator \
  --key-id 01 \
  --pkcs11-module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so

Enter the HSM PIN when icp prompts for it during the calls below. For OpenSC installation and locating the library, see the NitroKey HSM Installation Runbook.

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

icp canister call -n ic --identity node_operator \
  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\" })"

icp canister call -n ic --identity node_operator \
  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:

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

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

Related

• Node Provider Maintenance Guide — the parent runbook.
• Node Provider Networking Guide — why IPv4 is required on the first two nodes.
• Node Provider Domain Name Guide — registering and validating the domain.
• Changing the IPv6 Addresses of Nodes — the IPv6 counterpart, which is more disruptive.