Skip to main content
wwctl node manages cluster nodes stored in the Warewulf node registry (nodes.conf). Node names support hostlist syntax for operating on multiple nodes at once. 
wwctl node COMMAND [OPTIONS]
wwctl node can also be spelled wwctl nodes.
Add one or more new nodes to Warewulf.
wwctl node add [OPTIONS] NODENAME
When adding a range of nodes (e.g., n[2-4]) with --ipaddr, the IP address is automatically incremented for each node.Flags
FlagDescription
--ipaddrPrimary IP address of the node (or starting address for a range)
--netmaskNetwork mask for the primary interface
--gatewayDefault gateway for the primary interface
--hwaddrHardware (MAC) address of the primary interface
--netdevNetwork device name (e.g., eno1)
--netnameNamed network interface (default: default)
--discoverableEnable automatic MAC address discovery
--imageOS image to provision on this node
--profileComma-separated list of profiles to apply
--system-overlaysSystem overlays to apply at boot (replaces list)
--runtime-overlaysRuntime overlays applied by wwclient (replaces list)
--kernelargsKernel arguments (comma-separated or multiple flags)
Examples
# Add a single node
wwctl node add n1 --ipaddr=10.0.2.1

# Add a range of nodes; IPs are auto-incremented
wwctl node add n[2-4] --ipaddr=10.0.2.2

# Add a node with full network configuration
wwctl node add n1 \
  --netdev=eno1 \
  --hwaddr=00:00:00:00:00:01 \
  --ipaddr=10.0.2.1 \
  --netmask=255.255.255.0 \
  --image=rockylinux-9
List configured nodes and their attributes.
wwctl node list [OPTIONS] [PATTERN]
Flags
FlagShortDescription
--all-aShow all node configuration fields, including profile source
--net-nShow network interface configurations
--ipmi-iShow IPMI interface configurations
--long-lShow long/wide format
--yaml-yOutput in YAML format
--json-jOutput in JSON format
Examples
# List all nodes
wwctl node list

# List nodes matching a pattern
wwctl node list n[1-5]

# Show network configuration
wwctl node list --net n[1-4]
# NODE  NETWORK  HWADDR  IPADDR    GATEWAY  DEVICE
# ----  -------  ------  ------    -------  ------
# n1    default  --      10.0.2.1  <nil>    --
# n2    default  --      10.0.2.2  <nil>    --

# Show all fields with profile source
wwctl node list --all n1
# NODE  FIELD             PROFILE  VALUE
# ----  -----             -------  -----
# n1    Profiles          --       default
# n1    Ipxe              default  default
# n1    RuntimeOverlay    default  hosts,ssh.authorized_keys

# Show IPMI configuration
wwctl node list --ipmi
# NODE  IPMI IPADDR   IPMI PORT  IPMI USERNAME  IPMI INTERFACE
# ----  -----------   ---------  -------------  --------------
# n1    192.168.1.11  --         hwadmin        lanplus
Set configuration fields on one or more nodes.
wwctl node set [OPTIONS] PATTERN
Use UNDEF or UNSET as the value to clear a field. The PATTERN supports hostlist syntax. Use --all to target every node.Common flags
FlagDescription
--imageOS image name
--profileComma-separated list of profiles
--ipaddrPrimary IP address
--netmaskNetwork mask
--gatewayDefault gateway
--hwaddrMAC address
--netdevNetwork device name (e.g., eno1)
--netnameNamed network interface (default: default)
--typeNetwork interface type (e.g., ethernet, infiniband, vlan)
--kernelversionKernel version
--kernelargsKernel arguments (list value)
--system-overlaysSystem overlays (replaces list; short: -O)
--runtime-overlaysRuntime overlays (replaces list; short: -R)
--discoverableEnable/disable MAC auto-discovery
--tagaddAdd a key=value node tag
--tagdelRemove a node tag by key
--nettagaddAdd a key=value network tag
--nettagdelRemove a network tag by key
--ipmiaddrIPMI/BMC IP address
--ipminetmaskIPMI network mask
--ipmigatewayIPMI gateway
--ipmiuserIPMI username
--ipmipassIPMI password
--ipmiinterfaceIPMI interface type (e.g., lanplus)
--ipmiwriteWrite IPMI config to BMC during boot
--disknameBlock device path (e.g., /dev/vda)
--diskwipeWipe existing partition table
--partnamePartition label
--partcreateCreate the partition if it does not exist
--partnumberPartition number
--partsizePartition size in MiB
--fsnameFilesystem label
--fsformatFilesystem type (e.g., ext4, btrfs, xfs, swap)
--fspathMount path for the filesystem
--fswipeWipe existing filesystem on each boot
--assetkeyHardware asset tag for provisioning security
--all, -aApply to all nodes
--yes, -yAnswer yes to all confirmation prompts
List valuesFields that accept lists (such as --kernelargs, --system-overlays, --runtime-overlays) can be specified as a comma-separated string or repeated flags. To include a literal comma in a value, enclose it in inner quotes:
wwctl node set n1 \
  --kernelargs 'quiet,crashkernel=no,nosplash' \
  --kernelargs='"console=ttyS0,115200"'
Un-setting fieldsSet any field to UNDEF or UNSET to clear it:
wwctl node set n1 --image=UNDEF
Examples
# Assign an image
wwctl node set n1 --image=rockylinux-9

# Configure network interface
wwctl node set n1 \
  --netdev=eno1 \
  --hwaddr=00:00:00:00:00:01 \
  --ipaddr=10.0.2.1 \
  --netmask=255.255.255.0

# Add a second (InfiniBand) interface
wwctl node set n1 \
  --netname=infiniband \
  --type=infiniband \
  --netdev=ib1 \
  --ipaddr=10.0.3.1 \
  --netmask=255.255.255.0

# Enable automatic MAC discovery
wwctl node set n1 --discoverable

# Add a node tag
wwctl node set n1 --tagadd="localtime=UTC"

# Add a network tag
wwctl node set n1 --nettagadd="DNS1=1.1.1.1"

# Configure a scratch partition
wwctl node set n1 \
  --diskname /dev/vda --diskwipe \
  --partname scratch --partcreate --partnumber 1 \
  --fsname scratch --fsformat btrfs --fspath /scratch
The use of eth0, eth1, etc. as interface names is strongly discouraged. Use predictable interface names (e.g., eno1) as kernel-assigned names may conflict during boot.
Open a node’s full configuration in an interactive YAML editor.
wwctl node edit NODENAME
The editor used is determined by the $EDITOR environment variable. This is the only way to directly manage resources (complex YAML data used by overlays).
wwctl node edit n1
When nodes.conf is edited directly (outside of wwctl), warewulfd must be restarted to pick up the changes: systemctl restart warewulfd.service
Remove one or more nodes from the Warewulf node registry.
wwctl node delete NODENAME [...]

wwctl node delete n1
wwctl node delete n[5-10]
After deleting nodes, run wwctl clean to remove orphaned overlay images.
Import nodes from a YAML file into the node registry.
wwctl node import FILE
Importing a node configuration fully overwrites existing settings, including any customizations not present in the import file. Ensure the import file contains all desired options.
The YAML file is a mapping of node names to their attributes. Use wwctl node export to generate a valid template.Example YAML
n1:
  profiles:
    - default
  image name: rockylinux-9
  ipxe template: default
  kernel:
    args:
      - quiet
      - crashkernel=no
  network devices:
    default:
      type: ethernet
      device: eno1
      hwaddr: "00:00:00:00:00:01"
      ipaddr: 10.0.2.1
      netmask: 255.255.255.0
      gateway: 172.16.131.1
  primary network: default

wwctl node import /path/to/nodes.yaml
Export one or more nodes to a YAML file suitable for use with wwctl node import.
wwctl node export [NODENAME ...]

# Export a single node to stdout
wwctl node export n1

# Export all nodes to a file
wwctl node export > all-nodes.yaml
Display the current provisioning stage of each node.
wwctl node status [NODENAME ...]

# wwctl node status
NODENAME             STAGE                SENT                      LASTSEEN (s)
================================================================================
n1                   RUNTIME_OVERLAY      __RUNTIME__.img.gz        16
n2                   SYSTEM_OVERLAY       __SYSTEM__.img.gz         42
The LASTSEEN column shows how many seconds ago the node last contacted the Warewulf server. See provisioning stages for a description of each stage.
Connect to a node’s IPMI Serial over LAN (SOL) console.
wwctl node console NODENAME

wwctl node console n1
IPMI must be configured on the node (see --ipmiaddr, --ipmiuser, --ipmipass, --ipmiinterface). Warewulf uses ipmitool internally to establish the connection.
Query IPMI sensor information from cluster nodes.
wwctl node sensors [OPTIONS] PATTERN
Flags
FlagShortDescription
--full-FShow detailed sensor output
--show-sOnly print the IPMI command that would be executed
--fanoutNumber of commands to run in parallel (default: 50)
Examples
# Query sensors for a single node
wwctl node sensors n1

# Query with detailed output
wwctl node sensors --full n[1-4]

# Preview the IPMI command without executing
wwctl node sensors --show n1
IPMI must be configured on the target nodes. Node names support hostlist syntax.

Build docs developers (and LLMs) love

Get started for freeTalk to us