Skip to content

CLI — import-eveng-templates

Wrapper script: deploy/scripts/import-eveng-templates.sh Underlying module: backend/scripts/import_eveng (run as python -m scripts.import_eveng).

The wrapper is the normal operator entrypoint. It sources /etc/nova-ve/backend.env when readable, asserts root for mutating imports, then execs the venv'd Python module with the same argv. The default repo path is /var/lib/nova-ve/nova-ve-git; set NOVA_VE_REPO_DIR if the checkout lives elsewhere. --dry-run and --help may be run without sudo.

On a standard installed host, the one-shot flow is:

cd "${NOVA_VE_REPO_DIR:-/var/lib/nova-ve/nova-ve-git}"
./deploy/scripts/import-eveng-templates.sh --dry-run
sudo ./deploy/scripts/import-eveng-templates.sh

Synopsis

sudo deploy/scripts/import-eveng-templates.sh
    [--source PATH] [--dest PATH] [--manifest PATH]
    [--templates-dir PATH|-]
    [--move-symlink | --copy-only | --delete-source | --move]
    [--log-file PATH] [--dry-run] [--force] [--json] [--verbose]

Flags

The four copy-strategy flags are mutually exclusive — they are competing answers to "what happens to the source file". Since #271 the default is move + symlink back: image files are renamed into the destination and a symlink is left at the original /opt/unetlab path, so the bytes exist exactly once and EVE-NG keeps working.

Flag Type Default Behaviour
(no mode flag) — --move-symlink Move image files into --dest and leave a symlink at the original path. Same-filesystem moves rename (zero bytes copied); cross-filesystem sources fall back to copy + sha256 verify + symlink.
--move-symlink mode flag on Explicit spelling of the default.
--copy-only mode flag off Conservative opt-out: copy + sha256 verify; sources preserved (the pre-#271 default).
--delete-source mode flag off Copy + sha256 verify, then delete the source file. The explicit opt-in for destructive moves.
--move mode flag off Copy + delete source; skips sha256 verify. Unsafe.
--source path /opt/unetlab EVE-NG / UNetLab install root to walk.
--dest path /var/lib/nova-ve/images nova-ve images destination.
--manifest path /var/lib/nova-ve/import-manifest.json Where the run manifest JSON is written. Not written when --dry-run.
--templates-dir path or - /var/lib/nova-ve/templates Where generated nova-ve template YAML is written. Pass - to skip template generation.
--log-file path /var/log/eve-ng-importer.log Appending run log: every step line plus the final summary, with timestamps. Size-capped rotation (5 MiB × 3 backups).
--dry-run flag off Plan the run without touching the destination filesystem. Narrates each planned step (would be moving ...). Does not require root.
--force flag off Overwrite an existing destination on sha256 mismatch. Combinable with all copy modes.
--json flag off Machine-readable output: one JSON log event per line on stderr instead of the human step-by-step stdout.
--verbose flag off DEBUG-level logging in the log file (and on stderr under --json).

Output and logs

Every run prints numbered, human-readable step lines to stdout — one per file, docker build, template generation, and the final permission fixup pass — each with the size and elapsed time:

[1/8] qemu/vyos-1.4 — moving hda.qcow2 (2.1 GiB) ... done (0.3s, symlinked back to /opt/unetlab/addons/qemu/vyos-1.4/hda.qcow2)
[6/8] iol/i86bi-linux-l2 — copying iourc (8 B) ... done (0.0s)
[8/8] applying ownership + permission fixups ... done (0.1s)

The same narration plus the run summary is appended to /var/log/eve-ng-importer.log (override with --log-file), so post-run debugging never depends on terminal scrollback. The summary references the log path, and any error points at it. Pass --json to swap the step lines for the machine-readable stderr event stream.

Exit codes

Code Meaning
0 Success (including dry-run).
2 Tried to run non---dry-run without root.
3 Could not resolve the service user for chown.
Non-zero (other) Walker or copy engine raised. The manifest's errors[] lists specific files that failed without aborting the run; an entire run only aborts on argv parse failure or unrecoverable I/O.

Examples

# Dry-run plan first. This may be run without sudo:
cd "${NOVA_VE_REPO_DIR:-/var/lib/nova-ve/nova-ve-git}"
./deploy/scripts/import-eveng-templates.sh --dry-run

# Real run (move + symlink back default):
sudo ./deploy/scripts/import-eveng-templates.sh

# Conservative copy instead of move + symlink:
sudo ./deploy/scripts/import-eveng-templates.sh --copy-only

# Reclaim source disk after verification succeeds:
sudo ./deploy/scripts/import-eveng-templates.sh --delete-source

# Only QEMU images, by trimming the source tree first:
sudo rsync -a /opt/unetlab-from-eveng/addons/qemu/ /tmp/eveng-qemu-only/addons/qemu/
sudo ./deploy/scripts/import-eveng-templates.sh --source /tmp/eveng-qemu-only

# Import images only, without generating templates:
sudo ./deploy/scripts/import-eveng-templates.sh --templates-dir -

# Machine-readable event stream for CI / scripts:
sudo ./deploy/scripts/import-eveng-templates.sh --json