Add a new OpenAPI v3 REST API to warewulfd at /api

Co-authored-by: jason yang <jasonyangshadow@gmail.com>

Signed-off-by: Jonathon Anderson <janderson@ciq.com>

userdocs/server/api.rst

@@ -0,0 +1,75 @@
+========
+REST API
+========
+
+On-line documentation for the API is available at ``/api/docs``.
+
+Authentication
+==============
+
+Authentication is managed at ``/etc/warewulf/auth.conf``. This is a
+YAML formatted file with a single key: ``users:``, that is a list of user names
+and passwords able to authenticate to the API.
+
+.. warning::
+
+   Because ``warewulfd`` runs as ``root`` by default, and because ``warewulfd``
+   can run effectively arbitrary code via overlay templates, API access is
+   tantamount to ``root`` access on the Warewulf server. For this reason, the
+   API is only accessible via localhost by default. Still, handle API
+   credentials with care.
+
+.. code-block:: yaml
+
+   users:
+     - name: admin
+       password hash: $2b$05$5QVWDpiWE7L4SDL9CYdi3O/l6HnbNOLoXgY2sa1bQQ7aSBKdSqvsC
+
+Passwords are stored as bcrypt2 hashses, which can be generated with ``mkpasswd``.
+
+.. code-block:: console
+
+   $ mkpasswd --method=bcrypt
+   Password: # admin
+   $2b$05$5QVWDpiWE7L4SDL9CYdi3O/l6HnbNOLoXgY2sa1bQQ7aSBKdSqvsC
+
+Node
+====
+
+* ``GET /api/nodes/``: Get nodes
+* ``POST /api/nodes/overlays/build``: Build all overlays
+* ``DELETE /api/nodes/{id}``: Delete an existing node
+* ``GET /api/nodes/{id}``: Get a node
+* ``PATCH /api/nodes/{id}``: Update an existing node
+* ``PUT /api/nodes/{id}``: Add a node
+* ``GET /api/nodes/{id}/fields``: Get node fields
+* ``POST /api/nodes/{id}/overlays/build``: Build overlays for a node
+* ``GET /api/nodes/{id}/raw``: Get a raw node
+
+Profile
+=======
+
+* ``GET /api/profiles/``: Get node profiles
+* ``DELETE /api/profiles/{id}``: Delete an existing profile
+* ``GET /api/profiles/{id}``: Get a node profile
+* ``PATCH /api/profiles/{id}``: Update an existing profile
+* ``PUT /api/profiles/{id}``: Add a profile
+
+Image
+=====
+
+* ``GET /api/images``: Get all images
+* ``DELETE /api/images/{name}``: Delete an image
+* ``GET /api/images/{name}``: Get an image
+* ``PATCH /api/images/{name}``: Update or rename an image
+* ``POST /api/images/{name}/build``: Build an image
+* ``POST /api/images/{name}/import``: Import an image
+
+Overlay
+=======
+
+* ``GET /api/overlays/``: Get overlays
+* ``DELETE /api/overlays/{name}``: Delete an overlay
+* ``GET /api/overlays/{name}``: Get an overlay
+* ``PUT /api/overlays/{name}``: Create an overlay
+* ``GET /api/overlays/{name}/file``: Get an overlay file

userdocs/server/configuration.rst

@@ -333,6 +333,26 @@ Configuration for the ``wwclient`` service on cluster nodes.
   ``wwclient`` will use the TCP port "987" by default if ``secure: true``; but,
   if that port is otherwise in use, a different port may be specified.
 
+api
+===
+
+*New in Warewulf v4.6.1* 
+
+Configuration for the REST API of the ``warewulfd`` service.
+
+.. code-block:: yaml
+
+   api:
+     enabled: true
+     allowed subnets:
+       - 127.0.0.0/8
+       - ::1/128
+
+* ``api:enabled``: Whether the ``warewulfd`` service should provide access via a
+  REST interface.
+* ``api:allowed subnets``: Which subnets are allowed to access the REST API. By
+  default, only localhost has access.
+
 hostfile
 ========