Manifest Syntax

Manifest files in Mesh Hypervisor tell the system how to set up files on remote nodes. They live in /host0/machines/ or /host0/groups/ on the central orchestration node, alongside source files they reference, and get compiled into APKOVLs during mesh system configure. This section explains the syntax—actions, fields, and rules—so you can tweak nodes even if you just know ssh and cat. For usage, see Manifest Files.

Overview

A manifest is a text file named manifest inside a folder like /host0/machines/my-server/. It lists actions—one per line—like copying a file or making a link. Each line starts with a letter (the action) and has fields (like permissions or paths). That same folder holds the files it calls (e.g., hostname next to manifest). When you run mesh system configure, Mesh Hypervisor reads these lines, applies them in order, and builds the node’s filesystem. If a machine folder uses groups (e.g., baseline), their manifests run first, then the machine’s overrides.

Think of it like a recipe: “Copy hostname to /etc/hostname,” “Make /mnt/data.” The compile-apkovl script checks every line—miss a file or botch the syntax, and the whole mesh system configure stops with an error. That’s on purpose: no silent failures allowed. You fix it, then rerun.

Syntax

Each line starts with an action letter, followed by space-separated fields (FIELD=value). Paths must be full (e.g., /host0/machines/my-server/hostname) since relative paths aren’t supported yet.

Actions

  • O (Overwrite):
    • Purpose: Copies a file from the folder (e.g., /host0/machines/my-server/) to the remote node, replacing what’s there.
    • Fields:
      • MODE=<user:group:perms> (Required): Sets ownership and permissions (e.g., root:root:0644—read-write for owner, read for others).
      • SRC=<full-path> (Required): Source file in the folder (e.g., /host0/machines/my-server/hostname).
      • TGT=<full-path> (Required): Target on the remote node (e.g., /etc/hostname).
    • Example: O MODE=root:root:0644 SRC=/host0/machines/my-server/hostname TGT=/etc/hostname
      • Copies hostname from my-server/ to /etc/hostname with rw-r--r--.
  • A (Append):
    • Purpose: Adds a file’s contents from the folder to the end of a target file (creates it if missing).
    • Fields: Same as O—MODE, SRC, TGT.
    • Example: A MODE=root:root:0644 SRC=/host0/machines/my-server/packages TGT=/etc/apk/world
      • Appends packages to /etc/apk/world, sets rw-r--r--.
  • D (Directory):
    • Purpose: Makes a directory on the remote node.
    • Fields:
      • MODE=<user:group:perms> (Required): Sets ownership and permissions (e.g., root:root:0755—read-write-execute for owner, read-execute for others).
      • TGT=<full-path> (Required): Directory path (e.g., /mnt/data).
    • Example: D MODE=root:root:0755 TGT=/mnt/data
      • Creates /mnt/data with rwxr-xr-x.
  • L (Soft Link):
    • Purpose: Creates a symbolic link on the remote node.
    • Fields:
      • SRC=<full-path> (Required): What to link to (e.g., /usr/share/zoneinfo/EST).
      • TGT=<full-path> (Required): Link location (e.g., /etc/localtime).
    • Example: L SRC=/usr/share/zoneinfo/EST TGT=/etc/localtime
      • Links /etc/localtime to /usr/share/zoneinfo/EST—perms come from the target.
  • R (Remove):
    • Purpose: Deletes a file or directory on the remote node.
    • Fields:
      • TGT=<full-path> (Required): Path to remove (e.g., /etc/init.d/hostname).
    • Example: R TGT=/etc/init.d/hostname
      • Removes /etc/init.d/hostname.

Fields Explained

  • MODE=<user:group:perms>:
    • Format: user:group:octal (e.g., root:root:0644).
    • Purpose: Sets who owns the file and what they can do—0644 is owner read-write, others read; 0755 adds execute.
    • Used In: O, A, D—not L (links use target perms) or R (no perms to set).
    • Must Have: Yes for O, A, D—skip it, and the script errors out.
  • SRC=<full-path>:
    • Format: Complete path on the central node (e.g., /host0/machines/my-server/hostname).
    • Purpose: Points to a file in the same folder as manifest—must exist when mesh system configure runs.
    • Used In: O, A, L—not D (no source) or R (nothing to copy).
    • Must Have: Yes for O, A, L—missing file stops the build.
  • TGT=<full-path>:
    • Format: Complete path on the remote node (e.g., /etc/hostname).
    • Purpose: Where the action happens—parent dirs are auto-created.
    • Used In: All actions (O, A, D, L, R).
    • Must Have: Yes—every action needs a target.

Example Manifest

/host0/machines/my-server/manifest:

# Set a custom hostname from this folder
O MODE=root:root:0644 SRC=/host0/machines/my-server/hostname TGT=/etc/hostname
# Add packages from this folder
A MODE=root:root:0644 SRC=/host0/machines/my-server/packages TGT=/etc/apk/world
# Make a mount point
D MODE=root:root:0755 TGT=/mnt/data
# Remove default hostname service
R TGT=/etc/init.d/hostname
  • Source files hostname and packages live in /host0/machines/my-server/ with manifest.

How It Works

When you run mesh system configure, the compile-apkovl script processes every manifest:

  1. Compilation: Reads group manifests (from groups) first, then the machine’s—later lines override earlier ones.
    • Example: baseline sets /etc/motd, my-server overwrites it, my-server wins.
  2. Actions: For each line:
    • O: Copies SRC to TGT, sets MODE.
    • A: Appends SRC to TGT (creates if missing), sets MODE, adds a newline if needed.
    • D: Makes TGT dir, sets MODE.
    • L: Links TGT to SRC.
    • R: Deletes TGT (recursive for dirs).
  3. Validation: Checks SRC exists (for O, A), MODE is valid, and paths are full—any error (e.g., missing hostname) stops the entire build.
    • Fix it, rerun mesh system configure, or no APKOVLs get made.

The result lands in /srv/pxen/http/, and nodes grab it on boot.

Notes

Source files sit in the same folder as manifest (e.g., /host0/machines/my-server/hostname)—keep them together. Paths must be full (e.g., /host0/...)—relative paths like hostname won’t work until a future update. A is safer than O for files like /etc/apk/world—it adds, doesn’t wipe. For examples, see Configuring Nodes; for network configs, see Network Config.

This concludes the Configuration Reference.