Installation

This page covers installing and configuring the Warewulf Pro web interface. For a tour of what you can do once it's running, see Using the web interface.

Requirements

• Warewulf server v4.6.3 or later (the REST API is required).
• Enterprise Linux 9 (Rocky Linux 9 or compatible).
• Cockpit installed and running on the Warewulf server (or another host that has network access to warewulfd).

Installation

# depot enable warewulf-pro
# dnf -y install cockpit warewulf-cockpit
# systemctl enable --now cockpit.socket

The interface is then available at https://<your-server>:9090/warewulf.

Enabling the REST API

The web interface communicates with warewulfd over the REST API, which is disabled by default. Enable it in /etc/warewulf/warewulf.conf:

api:
  enabled: true
  allowed subnets:
    - 127.0.0.0/8
    - ::1/128

Configure a server-side authentication user in /etc/warewulf/auth.conf:

users:
  - name: admin
    password hash: $2b$05$5QVWDpiWE7L4SDL9CYdi3O/l6HnbNOLoXgY2sa1bQQ7aSBKdSqvsC

And the matching client credentials in ~/.wwapi.json for whoever runs Cockpit:

{
  "user": "admin",
  "password": "your-password",
  "address": "localhost",
  "port": 9873
}

For the upstream REST API reference (endpoints, auth options, examples), see the Warewulf API documentation.

After installing

Restart warewulfd so the API configuration takes effect:

# systemctl restart warewulfd

Then open https://<your-server>:9090 and select Warewulf in the left sidebar. See Using the web interface for what to do next.

Common gotchas

• Image import does not auto-build. When you import an image from the UI, you must explicitly click Build to make it provisionable. CLI users hit the same gotcha unless they pass --build to wwctl image import.
• Cockpit's self-signed cert. First-load browsers prompt about the certificate. Replace the cert in /etc/cockpit/ws-certs.d/ for production use.
• API token errors. If the UI shows "401 Unauthorized" on every action, re-check that /etc/warewulf/auth.conf and ~/.wwapi.json agree on user, password, and address.