Skip to main content
The REST API was introduced in Warewulf v4.6.1. It is disabled by default and must be explicitly enabled in warewulf.conf.

​
Enabling the API

Add an api section to /etc/warewulf/warewulf.conf and set enabled: true: 
api:
  enabled: true
  allowed subnets:
    - 127.0.0.0/8
    - ::1/128
After editing the configuration, restart the Warewulf daemon to apply the change: 
systemctl restart warewulfd

​
Allowed subnets

By default, the API only accepts connections from localhost (127.0.0.0/8 for IPv4 and ::1/128 for IPv6). To allow access from additional subnets, add them to the allowed subnets list: 
api:
  enabled: true
  allowed subnets:
    - 127.0.0.0/8
    - ::1/128
    - 10.0.0.0/8
API access is equivalent to root access on the Warewulf server. warewulfd runs as root by default and can execute arbitrary code via overlay templates. Keep the allowed subnet list as restrictive as possible and handle API credentials with care.

​
Base URL

The API is served on port 9873, the same port used by the Warewulf provisioning server: 
http://<server>:9873
The interactive API documentation (Swagger UI) is available at /api/docs on the running server.

​
Authentication

Authentication is configured in /etc/warewulf/auth.conf. This is a YAML file that lists users and their bcrypt2 password hashes: 
users:
  - name: admin
    password hash: $2b$05$5QVWDpiWE7L4SDL9CYdi3O/l6HnbNOLoXgY2sa1bQQ7aSBKdSqvsC
All API requests use HTTP Basic Auth — pass the username and password with each request.

​
Generating a password hash

Use mkpasswd to generate a bcrypt2 hash for a new password: 
mkpasswd --method=bcrypt
Password:
$2b$05$5QVWDpiWE7L4SDL9CYdi3O/l6HnbNOLoXgY2sa1bQQ7aSBKdSqvsC
Copy the resulting hash into auth.conf under password hash.

​
Example request

curl -u admin:admin http://localhost:9873/api/nodes/

​
TLS / HTTPS

To require TLS for API connections, first enable TLS for warewulfd in warewulf.conf: 
warewulf:
  tls: true
  tls port: 9874
Then enable TLS specifically for the API: 
api:
  enabled: true
  tls: true
When api: tls is set, the API rejects plain HTTP requests. Generate a self-signed key and certificate with: 
wwctl configure tls
Or import your own key and certificate: 
wwctl configure tls --import
Keys and certificates are stored in /etc/warewulf/tls/ by default.
The kernel and system image are always transferred unencrypted, regardless of TLS configuration. TLS only applies to overlay delivery and API traffic.

Build docs developers (and LLMs) love

Get started for freeTalk to us