NAS-127428 / 24.10 / Installer HTTP API

API.md

@@ -0,0 +1,243 @@
+# API Specification
+
+This API uses JSON-RPC 2.0: https://www.jsonrpc.org/specification
+
+# Server methods
+
+## adopt
+
+“Adopt” the system. It will return an access key that must be used to authenticate on this system when
+re-connecting.
+
+### Result jsonschema
+
+    {
+      "type": "string"
+    }
+
+## authenticate
+
+Authenticate the connection on the “adopted” system.
+
+### Parameter jsonschema
+
+    {
+      "type": "string"
+    }
+
+## install
+
+Performs system installation.
+
+### Parameter jsonschema
+
+    {
+      "type": "object",
+      "required": [
+        "disks",
+        "create_swap",
+        "set_pmbr",
+        "authentication"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "disks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "create_swap": {
+          "type": "boolean"
+        },
+        "set_pmbr": {
+          "type": "boolean"
+        },
+        "authentication": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "required": [
+            "username",
+            "password"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "username": {
+              "type": "string",
+              "enum": [
+                "admin",
+                "root"
+              ]
+            },
+            "password": {
+              "type": "string",
+              "minLength": 6
+            }
+          }
+        },
+        "post_install": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "network_interfaces": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "name"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "aliases": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "type",
+                        "address",
+                        "netmask"
+                      ],
+                      "additionalProperties": false,
+                      "properties": {
+                        "type": {
+                          "type": "string"
+                        },
+                        "address": {
+                          "type": "string"
+                        },
+                        "netmask": {
+                          "type": "integer"
+                        }
+                      }
+                    }
+                  },
+                  "ipv4_dhcp": {
+                    "type": "boolean"
+                  },
+                  "ipv6_auto": {
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+## is_adopted
+
+Returns `true` if the system in question is “adopted”, false otherwise.
+
+The system is “adopted” when the adopt method is called. Subsequent connections to the system must call the
+`authenticate` method before trying to do anything else.
+
+### Result jsonschema
+
+    {
+      "type": "boolean"
+    }
+
+## list_disks
+
+Provides list of available disks.
+
+### Result jsonschema
+
+    {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "size": {
+            "type": "number"
+          },
+          "model": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "removable": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+
+## list_network_interfaces
+
+Provides list of available network interfaces.
+
+### Result jsonschema
+
+    {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    }
+
+## reboot
+
+Performs system reboot.
+
+## shutdown
+
+Performs system shutdown.
+
+## system_info
+
+Provides auxiliary system information.
+
+### Result jsonschema
+
+    {
+      "type": "object",
+      "properties": {
+        "installation_running": {
+          "type": "boolean"
+        },
+        "version": {
+          "type": "string"
+        },
+        "efi": {
+          "type": "boolean"
+        }
+      }
+    }
+
+# Client methods
+
+## installation_progress
+
+Server calls this method on the client to report installation progress. This method will only be called 
+after the client initiates system installation and before the server reports its result.
+
+### Parameter jsonschema
+
+    {
+      "type": "object",
+      "properties": {
+        "progress": {
+          "type": "number"
+        },
+        "message": {
+          "type": "text"
+        }
+      }
+    }
+

debian/control

@@ -5,10 +5,13 @@ Maintainer: Vladimir Vinogradenko <[email protected]>
 Build-Depends: debhelper-compat (= 12),
                dh-python,
                python3-all,
+               python3-aiohttp-rpc,
                python3-ixhardware,
+               python3-jsonschema,
                python3-licenselib,
                python3-humanfriendly,
                python3-psutil,
+               python3-pyroute2,
                python3-setuptools
 Standards-Version: 4.4.0
 
@@ -20,10 +23,13 @@ Depends: ${misc:Depends},
          gdisk,
          openzfs,
          parted,
+         python3-aiohttp-rpc,
          python3-ixhardware,
+         python3-jsonschema,
          python3-licenselib,
          python3-humanfriendly,
          python3-psutil,
+         python3-pyroute2,
          setserial,
          squashfs-tools,
          util-linux

debian/rules

@@ -4,3 +4,5 @@ export PYBUILD_NAME=truenas_installer
 %:
 	dh $@ --with python3 --buildsystem=pybuild
 
+override_dh_installsystemd:
+	dh_installsystemd --no-start -r --no-restart-after-upgrade --name=truenas-installer

debian/truenas-installer.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=TrueNAS Installer
+
+[Service]
+ExecStart=/usr/bin/python3 -m truenas_installer --server
+
+[Install]
+WantedBy=multi-user.target

truenas_installer/__main__.py

@@ -1,13 +1,44 @@
+import argparse
+import asyncio
+
+from aiohttp import web
+
 from ixhardware import parse_dmi
 
 from .installer import Installer
+from .installer_menu import InstallerMenu
+from .server import InstallerRPCServer
+from .server.doc import generate_api_doc
 
 
-if __name__ == "__main__":
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--doc", action="store_true")
+    parser.add_argument("--server", action="store_true")
+    args = parser.parse_args()
+
     with open("/etc/version") as f:
         version = f.read().strip()
 
     dmi = parse_dmi()
 
     installer = Installer(version, dmi)
-    installer.run()
+
+    if args.doc:
+        generate_api_doc()
+    elif args.server:
+        rpc_server = InstallerRPCServer(installer)
+        app = web.Application()
+        app.router.add_routes([
+            web.get("/", rpc_server.handle_http_request),
+        ])
+        app.on_shutdown.append(rpc_server.on_shutdown)
+        web.run_app(app, port=80)
+    else:
+        loop = asyncio.get_event_loop()
+        loop.create_task(InstallerMenu(installer).run())
+        loop.run_forever()
+
+
+if __name__ == "__main__":
+    main()

truenas_installer/install.py

@@ -14,7 +14,7 @@
 BOOT_POOL = "boot-pool"
 
 
-async def install(disks, create_swap, set_pmbr, authentication, sql, callback):
+async def install(disks, create_swap, set_pmbr, authentication, post_install, sql, callback):
     with installation_lock:
         try:
             if not os.path.exists("/etc/hostid"):
@@ -27,7 +27,7 @@ async def install(disks, create_swap, set_pmbr, authentication, sql, callback):
             callback(0, "Creating boot pool")
             await create_boot_pool([get_partition(disk, 3) for disk in disks])
             try:
-                await run_installer(disks, authentication, sql, callback)
+                await run_installer(disks, authentication, post_install, sql, callback)
             finally:
                 await run(["zpool", "export", "-f", BOOT_POOL])
         except subprocess.CalledProcessError as e:
@@ -108,7 +108,7 @@ async def create_boot_pool(devices):
     await run(["zfs", "create", "-o", "canmount=off", "-o", "mountpoint=legacy", f"{BOOT_POOL}/grub"])
 
 
-async def run_installer(disks, authentication, sql, callback):
+async def run_installer(disks, authentication, post_install, sql, callback):
     with tempfile.TemporaryDirectory() as src:
         await run(["mount", "/cdrom/TrueNAS-SCALE.update", src, "-t", "squashfs", "-o", "loop"])
         try:
@@ -117,6 +117,7 @@ async def run_installer(disks, authentication, sql, callback):
                 "disks": disks,
                 "json": True,
                 "pool_name": BOOT_POOL,
+                "post_install": post_install,
                 "sql": sql,
                 "src": src,
             }

truenas_installer/installer.py

@@ -1,16 +1,8 @@
-import asyncio
-
-from .installer_menu import InstallerMenu
+import os
 
 
 class Installer:
     def __init__(self, version, dmi):
         self.version = version
         self.dmi = dmi
-
-    def run(self):
-        loop = asyncio.get_event_loop()
-
-        loop.create_task(InstallerMenu(self).run())
-
-        loop.run_forever()
+        self.efi = os.path.exists("/sys/firmware/efi")