migrate
The full pipeline: inventory → resolve → translate → evaluate conditionals → emit an Ansible role plus a JSON attestation.
vrtmv migrate --image centos7.vmdk --target rocky9 -o out/
vrtmv migrate --root /mnt/vm --target rhel9 --preflight
vrtmv migrate --image leap.qcow2 --target leap15 --format image \
--target-base https://download.opensuse.org/.../install --firmware uefi -o out/
| Flag | Purpose |
|---|---|
--root / --image / --ssh | The source (see Sources). |
--ssh-port, --ssh-key, --jump, --sudo | SSH collection options. |
--target <spec> | Target OS (default rocky9). See Supported targets. |
-o, --out <dir> | Output directory (default vrtmv-out). |
--format <list> | Output format(s): any of ansible, terraform, container, image (comma-separated; default ansible). |
--entrypoint <cmd> | Required by --format container: the one command the image runs (vrtmv never chooses it). Split on whitespace; quoting inside the value is not interpreted. |
--entrypoint-unit <unit> | For --format container: the unit on the source that --entrypoint stands for, as you assert it. Must be one of the source's enabled units, or the run stops with nothing written. vrtmv does not derive it; it notes on stderr when the unit's ExecStart runs another program than the entrypoint. The attestation records it and names every other unit the plan would have enabled as not started. See Enabled units. |
--chart-name <name> | For --format container: the name of the Helm chart written beside the Containerfile, under container/chart/<name>/. Lowercase letters, digits and -, starting and ending with a letter or digit, at most 53 characters; anything else is an error. Without the flag the name is made from the file name of the entrypoint's program (/usr/sbin/nginx gives nginx), and when none can be made the run stops before the source is read and asks for the flag. It names the chart's directory and nothing in the cluster. Without --format container the flag is an error. See The Helm chart. |
--chart-image <image> | For --format container: the image the Helm chart runs, written into its values.yaml, as <repository>:<tag> or <repository>@sha256:<digest>. A reference with neither a tag nor a digest is an error. vrtmv builds no image and pushes none; without the flag the chart names no image and does not render until a values file gives one. Without --format container the flag is an error. |
--preserve <path> | For --format container, repeatable: carry this path into the image unchanged, with the libraries it loads. For software the target has no package for. A path the target carries a package for is refused, and without --format container the flag is an error. The image is graded preserved-as-is by verify, never equivalent. vrtmv never sets it; the untranslatable-software check prints the arguments a source has. See Containerize as-is. |
--bake-secret <path> | For --format container, repeatable, one path per flag: copy this file into the image although vrtmv classed it as secret material or could not classify it. Without the flag such a file is not added to the image. Anyone who can pull the image can read a file copied this way. The attestation lists each named path under container_secrets.baked_in. A path that was not classed secret or unclassified on this source is an error that lists the paths the flag could name, and without --format container the flag is an error. See Secret material. |
--data <path>=<class> | For --format container, repeatable: where a data directory of the source goes. volume writes a VOLUME line and the volume is filled outside the build; disposable means not carried. A declaration covers everything under its path and the most specific one decides. vrtmv never picks a class: while a directory data discover lists has none, no Containerfile is written and the run lists them. image copies the path into the image: its files are listed and hashed, the script written beside the Containerfile stages them, and verify checks them in the built image. A database directory is never image-class. Without --format container the flag is an error. See Data directories. |
--assume-undetermined <check> | For --format container: proceed although the named feasibility check (kernel-modules, entrypoint, local-state, scheduled-jobs; comma-separated) could not be determined. untranslatable-software is accepted as a name and always has nothing to assume, because that check never reports itself as not determined. The attestation keeps the check as not determined and marks it assumed by the operator, and verify names it in its report. Never overrides a blocking finding, and records nothing on a source that is blocked. Without --format container it does nothing and says so on stderr. Naming a check that did answer changes nothing and prints a note on stderr naming it (--assume-undetermined scheduled-jobs had nothing to assume: the check was determined), so one flag works across a fleet and a stale one is visible. An unknown check name is an error. |
--no-base-digest | For --format container: write the Containerfile's FROM with the base image's tag and do not ask its registry for the digest. Without it migrate asks the registry, with no credentials, what the tag names now, writes FROM with that digest and records it in the attestation as container_target.base_image_resolution; when the registry does not answer it keeps the tag and says why in both files. With the flag the attestation says the registry was not asked. See Base image per target. |
--container-base <ref> | For --format container: the image FROM starts from, in place of the one the Index names, or for a target it names none for, where migrate otherwise writes no Containerfile. <ref> is NAME[:TAG], or NAME[:TAG]@sha256:DIGEST to pin it yourself. No registry is asked about it, with or without --no-base-digest, and a pinned base stays that image until you re-pin it. The packages are still the target's, so name an image of that distribution. The attestation records it as container_target.operator_base, your assertion with its provenance unverified, in place of base_image. See Base image per target. |
--target-base <ref> | Required by --format image: the boot substrate / install source the qcow2 is built from. |
--firmware <bios|uefi> | Required by --format image: the boot mode. Boot-critical and never guessed. |
--preflight | Report counts and blocking steps only; write no files and consume no usage credit. |
--no-passthrough | Install only the packages the Index has curated. By default a package the target publishes under the same name, in the same family, and that the Index has not curated is installed too, as a distinct, lower-confidence outcome. |
--remap-colliding-ids | When a pinned service-account uid or gid is held on the target by a different account, create the account at a system-allocated id instead of refusing. Its carried config is owned by name, so only the id that collided is renumbered. The role names the one step left: a later data copy uses rsync --numeric-ids, so chown the account's data to it by name. Without the flag a collision is refused and named. |
--with-patterns <dir> | Apply matched patterns from your own local pattern store (patterns/<kind>/<name>.yaml, with files/ and units/ beside them). Pass the same directory as vrtmv_pattern_store when you run the role. |
--allow-unsigned | Accept an attestation the signing service did not sign: a warning, and exit 0. Without it such a run writes every file and exits 6. See Signing. |
--json | Also print the attestation JSON on stdout; the status lines go to stderr. |
--deploy-image <image> | Also write a KubeVirt VirtualMachine manifest for the migrated workload, from a containerDisk image, to <out>/deploy/. It is not applied; see deploy. |
--deploy-disk-url <url>, --deploy-disk-size <size>, --deploy-storage-class <class> | Boot that manifest from a disk imported from an http(s) URL (a CDI DataVolume) instead of a containerDisk. --deploy-disk-size (for example 40Gi) is required with the URL; the storage class is optional. |
--deploy-namespace <ns>, --deploy-name <name> | Namespace (default default) and VM name (default vrtmv-migrated) of that manifest. |
--customer-roles <dir> | A directory of your own Ansible roles and collections, installed by you: read the roles --customer-role names against the source, without running them. See Your own Ansible roles. Needs at least one --customer-role. |
--customer-role <name> | Repeatable: a role in --customer-roles, by its name (geerlingguy.nginx) or a collection's role by its full name (devsec.hardening.os_hardening). A name that is not there stops the run before anything is written. |
--customer-vars <file> | Repeatable: a YAML file of variables for those roles, read as group or host variables are. A later file wins. A file encrypted with Ansible Vault, or holding a vaulted value, is refused. |
--run-customer-roles-in-copy | Also run each role of --customer-roles in check and diff mode in a throwaway copy of the source, and give each a verdict. This runs your roles' code, in the copy only. Needs podman, ansible-playbook on PATH, and --root or --image. See Checking the roles in a copy. |
--try-customer-roles-on <image> | With --run-customer-roles-in-copy: also run each role the check reads as matches or partly-matches, for real, in a throwaway container of <image>, the target's base image, and read what it manages there. <image> must be in podman's local images; vrtmv pulls nothing. With --format ansible alone, the output then calls each role that passed, before the role vrtmv writes. See Trying the roles on the target's base image and Calling the roles from the output. |
--try-customer-roles-with-network | With --try-customer-roles-on: give each trial container outbound network, so that a role can install what <image> does not have. The roles' code then reaches what this machine reaches. The check in a copy of the source still has no network. The attestation's customer_roles.trial.network says outbound; without the flag it says none. See Outbound network for the trial. |
Retired: engagement tagging
--engagement, --vm-id and --migration-type last worked in v0.7.0-beta.6 and have been removed. They are still accepted, and migrate now exits with an error naming the change rather than reporting an unknown flag.
The API endpoint they wrote to bound the authenticated account and then discarded it, so any account could create or overwrite migration records under any engagement it could name. An engagement has no owner column in any schema, so the endpoint could not be authorised and was removed rather than gated.
There is no replacement flag, and the migration itself is unaffected — re-run without them.
The host's identity
migrate bills the host by its identity: the stamp /etc/vrtmv/instance-id, else /etc/machine-id, else /var/lib/dbus/machine-id. A host with none is refused (a host with neither systemd nor dbus, such as Debian 7, has no machine-id file), and the refusal names the vrtmv identity command that gives it a stamp; for a host read with --ssh, the command for that host. When the identity is /var/lib/dbus/machine-id (there is no /etc/machine-id, as on OpenRC Gentoo) or a stamp, it is one that image clones copy, and migrate prints a one-line note: on stderr after the Source: line. It is a warning: if the host was cloned, run vrtmv identity on it (--force if the stamp came from the template) before you migrate it. For a host read with --ssh, the note gives the vrtmv identity --ssh command for that host, to run from where you run vrtmv.
The migrated target keeps the source's identity, so it is the same VM to vrtmv: its seat follows it, and cve-scan, drift and verify on the target count under the seat the source already holds. A stamp on the source is carried to the target with the other config. When the source's identity is its machine-id, the Ansible role writes it to the target's stamp, /etc/vrtmv/instance-id, as machine-id=<id>; the target's own /etc/machine-id is not touched. The terraform, image and container outputs do not write it.
Output
A non-preflight run always writes vrtmv-attestation.json (the host-specific parity report) and vrtmv-attestation.sig.json, a Vrtmv-signed signature over that report (see Signing). It then writes the runbook in each requested --format:
ansible(default) →roles/vrtmv_migration/tasks/main.yml— an Ansible role that installs the translated packages and reconciles config.terraform→terraform/cloud-init.yaml+terraform/main.tf— the translated workload packaged as cloud-init, wrapped in acloudinit_configwhose rendered output attaches to a compute resource asuser_data. This is the reusable foundation for the coming cloud targets (EC2 and friends); today it targets a VM you attach the cloud-init to.container→container/Containerfile— a buildable OCI image from the translated target. Requires--entrypoint(vrtmv never chooses the primary service) and a provenance'd base image in the Index for that target. Blocked / NotDeterminable / missing Index row / missing--entrypoint/ a data directory with no--dataclass refuse rather than emit. Operator runspodman build. Opt-in: default remains ansible. A whole machine is a supported source, as the extraction of one workload you name: one image runs one process, and other enabled services, scheduled jobs and local data are reported and not carried. Software the target has no package for is not in the image either: the run names it on stderr with the--preserveargument that would carry it, and sets nothing. Container output: scope, checks and base images has the scope statement, every feasibility check with what it reads, and the base image per target.image→image/— a qcow2 build recipe for a fresh bootable target: the target-native unattended install (vrtmv.kskickstart for rpm-family targets,preseed.cfgfor dpkg-family) plusbuild-image.sh, a driver that runs the target distro's own installer undervirt-install. Requires--target-base(the boot substrate) and--firmware bios|uefi; a missing base, an unrecognised firmware, or a target family the backend cannot build (only rpm and dpkg are supported) refuse rather than emit. vrtmv does not assemble image bytes — the one privileged step (root + qemu-kvm) runs on a builder host you control, viabuild-image.sh. Shipped in v2 for openSUSE Leap (an rpm-family target, so it uses the kickstart recipe).
Request ansible and terraform with --format ansible,terraform. Add container with --format ansible,container --entrypoint '/usr/sbin/httpd -DFOREGROUND', or image with --format ansible,image --target-base <ref> --firmware uefi.
How the image and container backends behave
Three properties hold for both artifact backends, and they are the same discipline the Ansible role already follows:
- A fresh build from the plan, not a clone of the disk. Each backend builds a fresh target from the migration plan — the translated package set and the carried config, installed onto a target base. vrtmv emits each carried file's path and never its contents: for the container,
migratewritescontainer/stage-carried.sh, which copies the files from the source into the build context (Staging the carried config); for the image, you place them. The image recipe also lists the service enable/mask decisions; theContainerfiledoes not, because a container image starts one command and no services. The source's kernel, initramfs, bootloader and vendor plumbing are the target's to provide and are never carried; for the image they come from the target distro's own install machinery. An image that copied the source disk would be the wrong machine and would earnverify'sfailedverdict against its own attestation. - Refusal-first, and non-fatal. When a backend cannot stand behind what it would emit, it refuses and says why on stderr rather than emitting a placeholder — a container with no
--entrypointor no Index base image, an image with no--target-baseor unknown--firmware. A refusal is the designed outcome of a gate, not a crash: the other requested formats still write. - A signed parity attestation, always. Every non-preflight run writes
vrtmv-attestation.jsonregardless of--format, and the Vrtmv-signedvrtmv-attestation.sig.json, or exits 6 when it could not get the signature (see Signing). After the image is built, prove it matches the promise withverify:vrtmv verify --attestation out/vrtmv-attestation.json --image <built.qcow2>.
Signing
migrate asks the signing service to sign vrtmv-attestation.json and writes the signature beside it as vrtmv-attestation.sig.json (see Attestation → Signing). When it gets no signature, because the service answers that it is not signing (HTTP 503) or the request fails, it still writes the attestation and every --format, writes no vrtmv-attestation.sig.json (and removes one an earlier run left in the directory), prints why on stderr, and exits 6:
error: vrtmv-attestation.json is not signed (the signing service answered 503: it is not signing). It is written unsigned, and the run fails; --allow-unsigned accepts it unsigned
With --allow-unsigned the same line is a warning and the run exits 0. A run that already fails, a BLOCKED plan for one, exits 1 as before. attest-image records such an attestation's signature as absent in its statement.
Services the target will not start
The role enables what the source had enabled, where it can name the target's unit. For some services it cannot, and those the role does not attempt:
- an OpenRC or SysV init script linked into a runlevel, unless the Index maps it onto a unit of the target: by the package that owns it, or by a row for that very script, described under A package's OpenRC script. A script that no package owns never maps. The role writes a unit for one such script only: a declarative OpenRC script, described under A unit written from an OpenRC script.
- a systemd unit you enabled that has no translation onto the target, or whose package is not in the install list, or whose enablement link pointed somewhere vrtmv could not identify.
migrate prints how many there are:
note: 35 service(s) the source started at boot will NOT start on the target. vrtmv-attestation.json names each with its reason, under aspects.services.refused as `enabled:<name>`. The role's last task lists them and fails the play until it is run with -e vrtmv_services_not_started_acknowledged=true.
The role lists them in a comment in its services section, and its last task, Report services the source started at boot that this target will not start, prints the same list with the reason for each and fails the play. So a play over a source like this ends with exit code 2 until you have read the list. Start each service on the target by hand or decide it is not needed, then run the play with -e vrtmv_services_not_started_acknowledged=true: the list is still printed, by the task before, and no longer fails. The variable accepts that list and nothing else.
On an OpenRC source the list is long, because it holds the init system's own boot steps (hostname, fsck, localmount and the like) beside your workload: vrtmv does not decide which of them the target needs. Scripts that no package owns come first, then the rest grouped by owning package.
A package's OpenRC script
A script with a start() of its own is a program, and vrtmv reads none. What such a script does is known of the file its package installs, so the Index says it, one row for a script: the package that installs it, its name, the software it starts, and the unit on the target that does the same. Three kinds of script need a row of their own:
- a script whose package is not the daemon's. Gentoo's
/etc/init.d/php-fpmis installed byapp-eselect/eselect-phpand starts thephp-fpmofdev-lang/php. On Rocky Linux 9 the row namesphp-fpm.service. - a script that serves several services through links. Gentoo's
/etc/init.d/openvpnis one script, andopenvpn-1194 -> openvpnis an instance of it that reads/etc/openvpn/openvpn-1194.conf. On Rocky Linux 9 the row names the templateopenvpn-server@%i.service, which reads/etc/openvpn/server/%i.conf. The instance is the one the script derives from its name: the text after the first dot, or the whole name when it has no dot. Soopenvpn-1194becomesopenvpn-server@openvpn-1194.service, andopenvpn.officebecomesopenvpn-server@office.service. - a script of a package that installs more than one. The Index names one unit for a package's software, its daemon. Gentoo's
net-misc/dhcpinstallsdhcpd,dhcrelayanddhcrelay6, and on Rocky Linux 9 the unit for its software isdhcpd.service, a DHCP server. Of such a package only the script named as the unit takes it (dhcpd). Any other is in the list above, with the package's scripts and the unit named, unless the Index has a row for it. A package that installs one script has its software's unit whatever the script is called:cronieiscrond.service. The scripts counted, enabled or not, are those in/etc/init.dor/etc/rc.d/init.dthat the package database lists among the package's files, on the source or deleted from it, together with those on the source it records as the package's; where it cannot list the package's files, only those on the source it records as the package's count. Gentoo'snfs(net-fs/nfs-utils) starts the NFS server, which isnfs-server.service, andlvm-monitoring(sys-fs/lvm2) islvm2-monitor.service. Neither is named as its unit, so each has a row.
Every row is for a Gentoo source. Each target has one only where the Index translates the script's package to it, its unit file was read from the package the migration installs, and the unit starts what the script starts, with the files the script reads at the same paths:
| Script | Unit | Targets |
|---|---|---|
php-fpm (app-eselect/eselect-php) | php-fpm.service | Rocky Linux 9 |
openvpn (net-vpn/openvpn) | openvpn-server@%i.service | Rocky Linux 9 |
nfs (net-fs/nfs-utils) | nfs-server.service | Rocky Linux and AlmaLinux 9 and 10 |
lvm-monitoring (sys-fs/lvm2) | lvm2-monitor.service | Rocky Linux, AlmaLinux and Red Hat Enterprise Linux 8, 9 and 10; Debian 12 and 13; Ubuntu 22.04 and 24.04 |
dhcpd (net-misc/dhcp) | isc-dhcp-server.service | Ubuntu 22.04 and 24.04 |
Some targets have no row on purpose:
nfson Debian and Ubuntu: their/etc/nfs.confsetsmanage-gids=y, so the server takes a user's groups from its own group database and not from the request, and who can open a file on an export can change. On Red Hat Enterprise Linux, nfs-utils was not read. Rocky Linux 8 and AlmaLinux 8 have no row because the Index does not translate net-fs/nfs-utils from Gentoo to them, so the migration does not install it.dhcpdon Debian 12 and 13: the package ships no unit, and its init script starts an IPv6 server too when/etc/default/isc-dhcp-servernames no interfaces, as installed. Gentoo's script starts the IPv4 server alone. On an EL targetdhcpdneeds no row: it is named as its unit,dhcpd.service.
Such a script stays in the list, and the reason names its package's scripts and the unit.
On Ubuntu the row maps dhcpd to isc-dhcp-server.service, which starts the IPv4 server alone. The package also enables isc-dhcp-server6.service, the IPv6 server. It reads the packaged /etc/dhcp/dhcpd6.conf, which has no subnet6, so it fails at start and the host boots degraded. vrtmv does not map that unit, and the role disables it, as described under Units the target's packages enable. It leaves it when the source enables a separate IPv6 server (a dhcpd6 script or dhcpd6.service), or when the migration carries a dhcpd6.conf and the source starts its DHCP server and leaves no service of it off.
The role enables the unit, and the script is not in the list above, when all of this holds:
- the script is the file its package installed: the checksum the source's package database recorded for it matches. For a link, that is the script it leads to, in
/etc/init.dand one step away; - it is started in the
defaultrunlevel and no other; - each file OpenRC reads before the script (the same files as for a declarative script) is absent, holds only comments, or is a file the same package installed and nobody changed. Gentoo's openvpn installs
/etc/conf.d/openvpnwith its defaults set, and that file as installed is no obstacle; - the software the row names is in this migration's install list. Rocky Linux 9 has openvpn in EPEL alone, so an openvpn instance is mapped only with
--target-repos, whichmigrateandvrtmv runboth take; - for an instance: its file is on the source and is a regular file; no line of it starts with a word the row lists, written plainly, with a leading
--or in quotes (cd,remoteandconfigfor openvpn: withcdorremoteGentoo's script does what the target's unit does not, and a file withremoteis a client's; withconfigthe file reads another, whose lines are not checked, so an instance that shares options through a file is not mapped either); and it does not name a path under the directory the source's script ran in (/etc/openvpn/).
Anything else keeps the script in the list, and its reason there names the row and the check that was not met.
The role does not put an instance's file where the target's unit reads it. It copies a carried file to the path it had on the source (/etc/openvpn/openvpn-1194.conf), and the unit reads /etc/openvpn/server/openvpn-1194.conf and runs in /etc/openvpn/server/. The role names each move in its comment Config files that move on the target: the instance's file, and each carried file beside it that it names (a word of one of its lines, after the first, that is a file in /etc/openvpn/ when read as a path from there, so ca ca.crt and also ifconfig-pool-persist ipp.txt). Nothing else under /etc/openvpn/ is said to move: not the file of an instance that was not mapped (a client's stays at the path it had, and on Rocky Linux 9 belongs in /etc/openvpn/client/), and not a file only that one names. vrtmv run copies a file its plan lists as moving to that path as well as to its own. For openvpn on Rocky Linux 9 its plan lists the moves only in a run --target-repos; without the flag run maps no openvpn instance, writes nothing into /etc/openvpn/server/, and you move the files. The role's task Check what each unit mapped from an init script reads on this target looks for the instance's file at the unit's path, and the role's last task fails the play and names the file while it is not there, with or without -e vrtmv_services_not_started_acknowledged=true: the unit is enabled and would fail at boot. Move the file, and with it what it names beside itself (ca ca.crt, key server.key); the check does not look for those. A private key is never carried, so it is in no move and you bring it; for a certificate the role asks for your decision, as for any other. An instance is not mapped when the source already has a file at the unit's path (/etc/openvpn/server/openvpn-1194.conf).
For php-fpm the row names the unit and nothing else. Gentoo keeps its pool files under /etc/php/fpm-php<version>/, and Rocky Linux 9 reads /etc/php-fpm.conf and /etc/php-fpm.d/: the role does not move them, so the unit starts with the pool the target's package ships until you bring yours.
A migrate run against an API that has no answer for scripts prints warning: the Index could not be asked for the units of init scripts, maps what the owning package's canonical maps, as before, and names a link to a package's script with that reason.
A unit written from an OpenRC script
An openrc-run script that only sets variables tells OpenRC to start one command. For a script like that, the Ansible role writes a systemd unit to /etc/systemd/system/<script>.service, enables it, and the script is not in the list above. migrate says so:
The role writes 1 systemd unit(s) from declarative OpenRC init scripts and enables them: hadoop-datanode -> hadoop-datanode.service. It does not bring the program a script starts or its account, and its last task fails when one is missing.
vrtmv reads the script and does not run it. A unit is written when all of this holds:
- the source is OpenRC, no package owns the script, and some other init script on the source does have an owner (otherwise vrtmv cannot tell your script from a package's);
- the script is a regular file, started in the
defaultrunlevel and no other; - each file under
/etc/conf.dthat OpenRC reads before the script holds only comments and assignments (see Variables). For the script<script>OpenRC reads/etc/conf.d/<script>.defaultin thedefaultrunlevel and/etc/conf.d/<script>only when that is absent, and for a script with a dot in its name, such ashadoop.datanode, it reads/etc/conf.d/hadoop.defaultor/etc/conf.d/hadoopfirst. When both of a pair are there and the plain one sets something, the script stays in the list: which of them a start reads then depends on the runlevel; - its first line is
#!/sbin/openrc-run, and it has nothing but comments, assignments,: ${NAME:=word}lines, and adepend()ofneed,use,want,after,beforeandprovidelines that the table below maps. A name with a lower-case letter is OpenRC's, and onlydescription,name,command,command_args,command_user,command_background,pidfileanddirectoryare read; an upper-case name is the script's own variable; - once the variables are expanded,
commandandpidfileare set,command,pidfileanddirectoryare each one absolute path, neitherpidfilenordirectoryhas a..component (systemd does not load a unit with such a working directory, and ignores such aPIDFile=; the rule holds withcommand_backgroundtoo, where the unit has noPIDFile=line), and no word ofcommand_argshas a quote, an escape or a character the shell would act on; descriptionandnameare printable ASCII.
| In the script | In the unit |
|---|---|
description | Description= |
command, command_args | ExecStart= |
command_user="user:group" | User=, Group= |
command_background="yes" and pidfile | Type=simple. systemd runs the command itself, and nothing writes the pidfile. |
pidfile without command_background | Type=forking and PIDFile= |
directory | WorkingDirectory= |
name, with no description | Description=<name> (from the source's OpenRC init script) |
the default runlevel | WantedBy=multi-user.target |
Variables
OpenRC sources /etc/rc.conf, the script's files under /etc/conf.d, and then the script, and start-stop-daemon runs eval over the command line it builds from command, pidfile, command_user, directory and command_args. So a value is expanded once where it is assigned and again by that eval. vrtmv does the first expansion itself, in the same order, for these forms only, in a double-quoted value or a bare word:
$NAMEand${NAME};${NAME:-word}: the value ofNAMEwhen it is set and not empty, and otherwise the word, which is text (no$, quote, backquote, backslash or});- in the script, a line
: ${NAME:=word}(or: "${NAME:=word}"):NAMEis set to the word when it is unset or empty.
A single-quoted value is text. $RC_SVCNAME and $SVCNAME are the script's name. A name that nothing before the script sets is unset, and the unit's comment names it. The value is then checked as above, so whatever a variable holds, what eval would read means only its text: a ;, *, |, quote or $ that a variable brings into command_args keeps the script in the list. A key set in a file under /etc/conf.d and not in the script, such as command_user, is carried as OpenRC honoured it, and the unit's comment names each file that was read.
These keep the script in the list, and the reason names the line: every other expansion ($(...), a backquote, $((...)), $1, $@, $?, ${#NAME}, ${NAME%...}, ${NAME:+...}, ${NAME-...}, ${NAME:=...} inside a value); a line of a file under /etc/conf.d that is not a one-line assignment (export, if, a function, a second command after ;); reading or setting a name that OpenRC or the environment it passes on sets (PATH, IFS, LANG, TERM, HOME, RC_* other than RC_SVCNAME, EINFO_*, LC_*, XDG_*, SVCNAME, and a name that starts with _), or that the shell running the script sets itself (busybox ash on Alpine and bash on Gentoo set BB_ASH_VERSION, HOSTNAME, RANDOM, SECONDS, SHLVL, UID, EUID, GROUPS, OSTYPE, HOSTTYPE, MACHTYPE, FUNCNAME, PIPESTATUS, OPTERR, EPOCHSECONDS, EPOCHREALTIME, SRANDOM, BASH* and COMP_*, among others); reading a lower-case name before anything set it; reading a name nothing else set that /etc/rc.conf or a file in /etc/rc.conf.d sets, or any such name when one of those files has a line that is not a one-line assignment; and any variable at all where one of those files sets rc_env_allow, since OpenRC then passes variables of its own environment on to the script.
In depend(), use, want and after are orderings and need is a requirement. A name there is one of OpenRC's facilities, or a service:
In depend() | In the unit |
|---|---|
need net | Wants= and After=network-online.target |
use net, want net, after net | After=network-online.target |
dns (need or an ordering) | After=nss-lookup.target |
clock (need or an ordering) | After=time-set.target |
use firewall, want firewall, after firewall | After=network-pre.target, and After= on firewalld, nftables, iptables, ip6tables, ufw and netfilter-persistent: each of those units starts before network-pre.target, except ufw on Debian 10 and Ubuntu 18.04 and 20.04, which starts only before network.target. An After= on a unit the target does not have orders nothing |
need dbus | Requires= and After=dbus.service |
use dbus, want dbus, after dbus | After=dbus.service |
localmount, hostname, logger (need or an ordering) | nothing: systemd starts a service after the local file systems, sets the hostname first, and the journal reads /dev/log from the start |
provide <name> | nothing: a unit has no names for others |
use, want or after a service | After= the unit the role enables for that service |
before a service | Before= the unit the role enables for that service |
A service is named in depend() by its OpenRC name, and its unit on the target can have another (Gentoo's cronie is crond.service on Rocky Linux). The unit is the one the role enables for that service: the unit the Index maps its script onto, or one the role writes from another declarative script in the same run. Where the role enables no unit for the service, the ordering is left out, as OpenRC leaves out a use of a service that is not in the runlevel. Each line left out is named in a comment at the top of the unit, with the reason.
Anything else keeps the script in the list, and its reason there says what was found: a shell function such as start(), a variable not in the table (start_stop_daemon_args, supervisor, chroot), a need of a service (the unit would start without what the script required), need firewall, before one of the facilities, a keyword or config line in depend(), a symbolic link that does not lead to a package's script, a variable or a file under /etc/conf.d that Variables does not read.
The unit is not the whole service. The role does not copy the program the script starts and does not create its account. It does not create the directory the script names either. After writing the unit it checks that the user and group exist, that the command is an executable file and that the directory is one the service can enter, and its last task fails the play and names what is missing: an enabled unit whose command is absent fails at boot. Put the program, the account and the directory in place and run the play again. /etc/rc.conf and the environment OpenRC gave the command are not carried. To stop the service systemd signals every process in it, where start-stop-daemon signalled the one in the pidfile. systemd enters the script's directory as the service's user, where start-stop-daemon entered it as root, so a directory only root can enter starts the service on the source and fails it on the target. For a script with a command_user the role therefore has systemd run both checks, in a transient unit with the same User= and Group= (systemd-run --wait, then systemctl reset-failed so a check that fails leaves no unit behind), so each check has the groups the service will have, the user's other groups among them, and a number is taken where the script gives one for the user or the group. A command the user cannot execute and a directory it cannot enter are named in the same list, as its command <path> is not an executable file for <user> here and its directory <path> is not a directory <user> can enter here. Where the user or the group is absent, the list names the account and nothing else for that unit, and the next run checks the rest. The check reads permissions. It does not start the command, so a file system mounted noexec, a script whose interpreter is absent and an SELinux denial are still found at boot. It needs systemd running on the target and the role applied as root; where it cannot run, the list names the command and the directory. systemd-run --wait needs systemd 232, so for a script with a command_user vrtmv writes no unit when the target ships an older systemd, and the script stays in the list with a reason that names it: CentOS Linux, Red Hat Enterprise Linux and Oracle Linux 7 and Amazon Linux 2 ship 219, Debian 8 215, Ubuntu 16.04 229 and SUSE Linux Enterprise 12 228. A target whose systemd vrtmv has not read is refused the same way. A script without a command_user is checked as root, without systemd-run, and its unit is written on any target.
A command that a package of the source records is that package's program, and the unit runs it with the source's arguments. So where the migration installs another package for it, vrtmv writes no unit: Alpine's dcron becomes cronie on Rocky Linux, whose /usr/sbin/crond takes -p for something else, and the script stays in the list with a reason that names the package and what it becomes. Bring the source's program and write the unit by hand, or start the target package's own unit. Where the package keeps its name (a Gentoo atom by its name after the category), the role also checks, as root, that the command is a file of one of the packages the migration installs for it, with rpm -qf or dpkg-query -S (which is asked for both /bin/x and /usr/bin/x where /bin is a link to /usr/bin), and names it as its command <path> is not a file of <package> here. A target of another package family gets no unit for such a script. A command no package records is checked only as an executable file.
A path does not name a daemon: Ubuntu's ua-timer.service and apt-news.service run python3. The program's own package does, when it ships one unit for the program: that unit runs the daemon the written unit runs, and Rocky Linux enables crond.service, cronie's, beside which a written cronie.service fails with can't lock /var/run/crond.pid. A package that ships two runs the program for two purposes, beside each other by design: EL 9's dhcp-server has dhcpd.service and dhcpd6.service (-6), and redis has redis.service and redis-sentinel.service. Before the units are enabled, the role asks systemd for every service unit of the target, other than a template, a masked unit and an alias, one of whose ExecStart= paths leads to the same file as the written unit's command. A unit of the program's own package is one that is not Type=oneshot and whose file a package records that also records the command, as written or the file it leads to (rpm -qf, dpkg-query -S). When there is exactly one, counting those the role itself enables, and the role does not enable it (written or the target's, since the source ran those beside the script), it gets Conflicts= and After= in /etc/systemd/system/<unit>.d/vrtmv-same-program.conf, and that file is removed when there is none. After= makes the one stop before the other starts: without an ordering systemd runs both jobs at once, and the daemon that starts meets the lock the other still holds. At boot systemd then starts the written unit and not the other, since of a start and a stop that a conflict asks for it drops the start; an operator who starts the other by name stops the written unit. Every other unit of the same program, each unit of a package that ships more than one, and every one on a target whose package database vrtmv cannot ask, is only named in a message: it may run the program for another purpose, and a Conflicts= on it would stop the written unit whenever it ran (a timer starts ua-timer.service). The role disables none of them, so if one runs the same daemon, disable the one the host does not run. Where systemd cannot be asked, the role's last task fails and says so. A unit of the program that systemd reads from somewhere other than ExecStart=, such as a wrapper script, is not found.
The role does not write over a unit it did not write. If a unit file of that name is already on the target, in /etc/systemd/system with other content or in one of systemd's other unit directories, the play stops before the write and names the file.
Only the Ansible role writes unit files, so this happens only when --format has ansible and has neither container nor image. In any other run the script stays in the list, and its reason says its script is declarative. cluster-migrate does not write these units.
The attestation promises the unit as enabled:<script>.service, as it does for a unit a package provides, and verify looks for that. It does not record that vrtmv wrote the unit.
Not in the list: a unit enabled by the source distribution's own preset or by an image build. The target applies its own presets, so vrtmv does not know that the target will leave those off; the attestation names them as refused.
coupled-migrate writes this role for each node and asks for the same variable before its runbook touches the first node.
The same task reports a unit the role did try to enable and could not. That always fails the play, with or without the variable. If the unit's file is one the role copies from the source (/etc/systemd/system/<unit>) and vrtmv_source_root was not set, the report says the file was not copied, which is why systemctl could not find the unit.
Units the target's packages enable
Installing a package can enable units besides the one the role enables for its software. On Debian and Ubuntu a package's install script enables every unit it ships unless its packager said otherwise. Nearly always those units are what the software needs: openssh-server on Ubuntu 24.04 enables only ssh.socket, and postgresql enables postgresql.service, which starts the clusters. vrtmv leaves them as the package left them.
Where the Index has measured that a package enables a unit that the source's workload did not run, and what that unit does on the target as installed, the role disables it. One package has such a row so far:
| Package of | Target | Unit | Why |
|---|---|---|---|
cpkg:dhcp-server (isc-dhcp-server) | Ubuntu 22.04, 24.04 and 26.04 | isc-dhcp-server6.service | The IPv6 server. The packaged /etc/dhcp/dhcpd6.conf has no subnet6, so the unit fails at start and the host boots degraded. |
The role names each unit with the Index's reason in a comment in its services section and disables it with enabled: false in the task Disable units the target's packages enabled that the source did not run. Nothing is stopped: a unit that the package started at install and that failed then stays failed until the next boot. If a unit cannot be disabled, the role's report at the end names it and fails the play. A preseed or kickstart from --format image disables the same units, after the units it enables. A run that writes only a Containerfile disables nothing.
The role leaves the unit as the package left it, and says why in a [CAVEAT] comment, when the source ran what it serves:
- the source enables a service of the same software that the role does not start: a Gentoo
/etc/init.d/dhcpd6linked todhcpd, or an ELdhcpd6.service; - the migration carries a file to the path the unit reads its configuration from (
/etc/dhcp/dhcpd6.conf), and the source starts a service of the same software and leaves none of its services off. Then what read the file on the source may be a service the source started, as Debian's oneisc-dhcp-serverscript runs the IPv6 server whenINTERFACESv6is set.
A carried file is configuration, not a server that ran. The services of the software are those its source packages install:
- on a systemd source, the
.serviceunits in their file lists, started when enabled, and their init scripts that have no unit of the same name, started when an/etc/rc<N>.d/S##<name>link is there for a runlevel from 2 to 5 (Debian 12'sisc-dhcp-serverhas only a script;update-rc.d isc-dhcp-server disableleavesKlinks, which do not start it). A script whose<name>.serviceis masked, a link to/dev/nullthatsystemctl mask isc-dhcp-serverwrites and that leaves theSlinks, is off; - on an OpenRC or SysV source, their init scripts and the links to them, started when in a runlevel.
Where one of them is off (an EL dhcpd6.service not enabled, an Ubuntu isc-dhcp-server6.service disabled, a Debian isc-dhcp-server script with no S link or masked, a Gentoo dhcpd6 in no runlevel), it cannot be told whether the file was in use, and the role disables the unit all the same. So it does where the source starts no service of the software, or where the package database could not tell. A second [CAVEAT] names the carried file and why: enable the unit on the target if the file is in use.
A unit the role enables, because the source ran it, or masks, because the source masked it, is not touched.
migrate prints a line when it disables or leaves such a unit:
note: the migration disables 1 unit(s) that the target's packages enable on install: isc-dhcp-server6.service (cpkg:dhcp-server). vrtmv-attestation.json says why, under aspects.services.package_enabled.
The attestation records each under aspects.services.package_enabled, with unit, canonical, action (disabled or left) and why, and caveat for a unit disabled although the migration carries the file it reads. That is a statement about the target, not a promise about the source, and verify does not look for it. cluster-migrate does not disable these units; coupled-migrate does, in the role it writes for each node.
Your own Ansible roles
If you already manage hosts with Ansible roles of your own, or roles from Galaxy, migrate can read them beside the migration and say what of them the source already has:
ansible-galaxy install -r requirements.yml -p ./roles # in your environment, as you do now
vrtmv migrate --root /mnt/vm --target rocky9 -o out/ \
--customer-roles ./roles --customer-role geerlingguy.nginx \
--customer-role devsec.hardening.os_hardening --customer-vars group_vars/web.yml
vrtmv runs none of their code: no task, no lookup, no filter or module plugin. It reads the roles' files. It fetches nothing: resolving requirements.yml is yours, in your environment. It sends none of it: the roles, your vars and what was read stay on the machine (the attestation is signed by its digest alone). And the output does not change: the role vrtmv writes, and every other file, is the same as without the flags. The roles are not called by it.
What it writes is customer-roles.txt in the output directory, and the same in the attestation under customer_roles. --preflight prints one line with the counts. For each role:
-
The lock. The version and where it came from, from the install record
ansible-galaxywrote (meta/.galaxy_install_infofor a role,MANIFEST.jsonandGALAXY.ymlfor a collection), and a sha256 over the files Ansible reads:tasks,handlers,defaults,vars,templates,files,metawithout the install record,library,module_utilsand any*_pluginsdirectory. It issha256sum's lines for those files, sorted by path, hashed again, so it is the same wherever the role is installed. A.pycin a__pycache__in a plugin directory (library,module_utils,*_plugins, a collection'splugins) is left out: Python writes it when a plugin is imported, and it differs from one install to the next. Python may run it in place of its.py, so the lock counts the files left out, and how many of them Python may run: a hash-based.pyc, or a timestamp-based one that records its.py's mtime and size. Any other file in that__pycache__, and a__pycache__anywhere else (underfilesortemplates, for example), is in the digest. For a collection, the collections it requires and whether each is installed beside it, and how many plugin files it has: those are Python that runs whereansible-playbookruns. -
The census. How many tasks change the host, how many only set variables or read the host, how many are commands whose effect is not in their arguments, and what they depend on: facts, results registered at run time, check mode, loops, lookups, plugins, and the roles it depends on (which are not read).
-
The comparison with the source. Four kinds of task are compared with the source root:
Task Compared with package,apt,yum,dnf,dnf5,zypper,apkthe source's package database: installed, or provided by an installed package service,systemd,systemd_service, theirenabledandmaskedthe units enabled and masked on the source. A unit whose file has nothing in its [Install]section isstatic, whichsystemctlcalls enabledsysctlthe role's sysctl_file, and the value that wins among the filessysctl --systemreadsuser,group/etc/passwdand/etc/group: present or absent, and theuid,group,shell,homeorgidthe task names. A password is never readEach finding is
sameordifferent, with what the role asks for and what the source has. A sysctl value is strong evidence; a package installed, a unit enabled and an account are weak, because a distribution's own package leaves the same state whether or not the role ran. Every other task that changes the host, a template's content among them, is listed as not compared, with the reason. So is acommandorshelltask, whose effect is not in its arguments, and a task delegated to another host, run withconnection: localor as alocal_action, which does not run on the source.
The tasks are read in the order Ansible runs them, with the variables Ansible would give them: the role's defaults, then your vars files, then the role's vars/, then what include_vars and set_fact set along the way, in that order of precedence. The files are read as Ansible reads YAML, so a plain no is false, 0644 is a number, 1:30 is 90 and << merges a mapping. An alias is read as a copy, and a file whose aliases copy more than 100,000 nodes is not read. include_tasks, import_tasks, blocks and loops (loop, with_items, with_list, with_dict) are followed; a block's or an import's condition is evaluated on each task inside it, as Ansible does, and its ignore_errors and check_mode apply to them; an include_tasks keeps its own. A fail, an assert that does not hold, or a meta: end_play (end_host, end_role, end_batch) that is decided to run on the source ends the reading there, and the report says where. After a fail or an assert, the always: of the blocks around it is read first, as Ansible runs it; after a meta: end_* it is not. A failure under ignore_errors does not, and one inside a block with a rescue: ends that block: its rescue is read, and what follows the block. When a failure's ignore_errors is not known, what the failure would skip is kept under the condition that it is ignored: the rest of the block, up to the first block around it with a rescue:, or the rest of the role when there is none. The always: around it is not, nor what follows a block with a rescue:: those run either way. That holds when the rescue, which runs when the failure is not ignored, is tasks only. When it has a fail, an assert, a meta, a task with failed_when, an include, a block or a task whose module is not decided, it may end the run, and vrtmv does not decide what it does: whether a task after the failure runs, the always: around it included, is not decided, to the end of the role, the always: and what follows of the blocks around it included, and each finding there says so. A rescue: of a block around it is listed as not compared, and says that whether it runs is not decided. A task's module is its key that is not a keyword of an ansible-core task, and a with_ of any lookup is a keyword. When more than one of its keys is neither a keyword nor a module vrtmv knows, which one Ansible runs is not decided: the task is listed as not compared, and as it may end the run, whether a task after it runs is not decided either, to the end of the role. A task with check_mode: true changes nothing in a run, and is listed as not compared. A file of the role that leads outside the role directory, by .. or by a link, is not read. The source's facts are supplied from its os-release: distribution, os_family and distribution_major_version, under the names Ansible gives them (Rocky and RedHat for Rocky Linux). A condition on those is decided, and a task whose condition is false on them is listed as skipped. Any other fact is unknown, and so is a result a task registers: a condition that names one is not taken as true or as false, and is kept beside each finding under it (only if …). Templates are evaluated for the subset of Jinja that roles use for variables and conditions; a filter, test or lookup outside it makes that value unknown, and the task is listed as not compared. The only lookup evaluated is varnames with ^name$, which asks whether a name is defined; every other lookup would run on the machine that runs ansible-playbook, and none runs here.
The sysctl reading follows sysctl --system: the *.conf files of /etc/sysctl.d, /run/sysctl.d, /usr/local/lib/sysctl.d, /usr/lib/sysctl.d and /lib/sysctl.d together, in the order of their file names, a name in an earlier directory of that list hiding the same name in a later one, and /etc/sysctl.conf last. A key with *, ? or [ is a glob: it sets the keys it matches that no file names, in whatever order, and not a key a -key line takes out; of two globs the later wins. That is what sysctl --system (procps-ng 4.0) and systemd-sysctl both do. (At boot systemd-sysctl reads /etc/sysctl.conf only through /etc/sysctl.d/99-sysctl.conf, which Debian, Ubuntu and EL make a link to it.) A key is same when the task's sysctl_file holds the role's value, compared as ansible.posix.sysctl compares it, and no file applied after it sets another. A sysctl_file that sysctl --system does not read is read on its own, and its value never takes effect. A running kernel is not read: there is none in a source root.
Without --run-customer-roles-in-copy there is no verdict on whether a role is applied. A cold reading cannot see what the role's templates render or what facts it gathers, and a package that a role installs reads the same as one installed by hand. That needs the role's own check run in a copy of the source, which the flag adds.
A role that is not in the directory, a vars file that is not a YAML mapping, and a vaulted vars file or value each stop the run before the API is asked anything, with nothing written. A role file that cannot be read is named in the report, and the reading is short by what it holds.
Checking the roles in a copy
vrtmv migrate --root /mnt/vm --target rocky9 -o out/ \
--customer-roles ./roles --customer-role geerlingguy.nginx --customer-vars group_vars/web.yml \
--run-customer-roles-in-copy
With --run-customer-roles-in-copy, each role also runs in Ansible's check and diff mode, ansible-playbook --check --diff, in a copy of the source. The flag is your consent to run your roles' code there. It never runs against the source, in any mode, and none of it runs on the machine that runs vrtmv:
- The copy. The source root is the lower layer of a podman overlay (
podman run --rootfs <root>:O). The copy writes to a layer of its own, which podman discards, and the source root is never written. The copy has no network. When the source has systemd, the copy boots it, so a unit's enablement is read assystemctlreads it. Each role gets a copy of its own, removed when its check ends, and a check is stopped after 30 minutes. The copy's files have the owners they have in the root: a root unpacked by a user who is not root has that user as the owner of every file, which the copy shows asroot, and a role's tasks that set an owner then read as different. Mount or unpack the source as root. The copy runs with SELinux separation off (--security-opt label=disable), and the role's code runs as the copy's root: with rootful podman that is root on your machine with podman's default capabilities, so prefer rootless podman, inpodman unsharefor a root unpacked as root. A run that is interrupted (Ctrl-C, a signal) leaves its copy running and its run directory in place: remove them withpodman rm -fon thevrtmv-role-check-*containers andpodman unshare rm -rfon thevrtmv-role-check-*directories in$TMPDIR(/tmpwhen it is not set). - Ansible runs inside the copy.
ansible-playbookruns in the copy with-c local, by the source's ownpython3, from the ansible-core of theansible-playbookon your PATH, mounted read-only. A role's lookups, filters and plugins run whereansible-playbookruns, so they run in the copy. The roles directory is mounted read-only. No home directory, credential or environment variable of yours is given to the copy, and none of the source'sansible.cfgis read. Abecomeusessu: Ansible is root in the copy, and the source need not havesudo. The ansible-core must run on the source's Python (ansible-core 2.19 needs 3.11 or later; for an older Python, put an older ansible-core first on your PATH). - The source's facts. The copy gathers its own facts, and vrtmv then sets the ones it read from the source over them:
distribution,os_familyanddistribution_major_versionfrom its os-release, andhostnameandnodenamefrom/etc/hostname. The copy also runs under the source's hostname. The facts of the machine the copy runs on are not the source's: processors, memory, virtualization, kernel. The report names them with their values, because a role that branches on one of them, or renders one (aworker_processesthat defaults to the processor count), read this machine's value. - Your vars. The
--customer-varsfiles are the copy's host variables, in the order given, as in the reading above.
Each role gets one of four verdicts, from its tasks' results, with handlers left out:
| Verdict | When |
|---|---|
matches | at least one task with strong evidence is as the role leaves it, and no task differs |
partly-matches | at least one task with strong evidence is as the role leaves it, and at least one task differs |
does-not-match | no task with strong evidence is as the role leaves it, and at least one task differs |
inconclusive | the check failed at a task that no task that differs before it explains, it did not finish, or no task with strong evidence ran and none differ |
Strong evidence is a template, copy, lineinfile, blockinfile, replace, ini_file or assemble task, whose content is what the role renders, and a sysctl key. Weak evidence is every other task that changes the host: a package installed, a directory present, a unit enabled, an account. A distribution leaves those anyway, so a host that only has the role's packages is not called a match. The verdict says whether the source is in the state the role produces, not whether the role was ever run on it: a host put into that state by hand reads the same.
What a check in a copy reads wrong is not used:
- Sysctl.
ansible.posix.sysctlcompares the file and the running kernel together, and the copy's kernel is the machine's, not the source's. Its result is listed and not used; the sysctl keys come from the reading of the sysctl files above, as strong evidence. A key whose task runs under a condition the reading could not decide (a fact it does not have, such asvirtualization_type) is used when the check ran that task in the copy, and left out when the copy skipped it. - A unit's running state. Whether a unit runs in the copy says nothing about the source. Only its enablement is read, from what
systemctlsays of its unit file; a task that asks only for a running state is not used. - Commands. A
command,shell,scriptorrawtask's effect is not in its arguments, and check mode skips most of them. - A failure that follows a change. A role that installs software fails in check mode at the first task that needs it, because check mode installed nothing. A failure after a task that differs (a strong or a weak difference, such as a package that is not installed or a unit whose enablement differs) ends the check there; the report says so, and the verdict is read from what ran before it. A change that is not decided (a sysctl, a running state, a command) does not count: it is the copy's own. A failure with no task that differs before it makes the role
inconclusive.
A task skipped in check mode, such as one under when: not ansible_check_mode, is listed as skipped.
customer-roles.txt gains a "Checked in a copy" block for each role: the verdict and why, the counts, and every task the check reported, with the diff of each that differs. The attestation has the same under customer_roles.roles[].check, and customer_roles.check says how the check ran: the ansible-core and podman versions, the facts set, and the facts of the machine the copy ran on.
The flag needs podman, ansible-playbook on your PATH, and the source as --root or --image: an --ssh collection holds /etc and the package database, not a whole filesystem. Without podman or ansible-playbook, or with --ssh, the run stops before the source is read, with nothing written. A source with no python3 is not checked, and each role is inconclusive, with the reason.
Trying the roles on the target's base image
vrtmv migrate --root /mnt/vm --target debian12 -o out/ \
--customer-roles ./roles --customer-role geerlingguy.nginx --customer-vars group_vars/web.yml \
--run-customer-roles-in-copy --try-customer-roles-on localhost/golden-debian12:latest
A role that the output would call in place of what vrtmv writes has to leave alone what vrtmv writes, and vrtmv has to leave alone what the role writes: otherwise each run rewrites the other's files and the result never settles. What a role manages on the target is not in its text: its package names, paths and units come from variables, facts and loops. With --try-customer-roles-on, vrtmv runs each role the check reads as matches or partly-matches for real on the target's base image, and reads what it manages from its tasks' resolved arguments, as Ansible ran them. A check of the source cannot say this: check mode skips a task under when: not ansible_check_mode, and stops at the first task that needs software it did not install.
- The image.
<image>is the target's base image, as podman names it, and it must be in podman's local images: vrtmv pulls nothing (podman pullor build it first). vrtmv records its id and digest, and runs it by that id, so apodman tagor a build that moves the name during the run does not change what the roles are tried on. It asks the image's own/bin/shwhich Python and systemd it has, in a container with no network that is removed when it exits. An image with no/bin/shor nopython3stops the run before the source is read, with nothing written. - The trial. Each role runs in a container of its own made from
<image>, with no network unless you give--try-customer-roles-with-network, booted with the image's systemd when it has one, and removed when the trial ends; a trial is stopped after 30 minutes.ansible-playbookruns inside it as in the check:-c local, by the image's ownpython3, from the ansible-core on your PATH mounted read-only, with the roles directory read-only and your--customer-varsas host variables. It is a real run, not check mode. The facts are the image's, which are the target's; onlyhostnameandnodenameare the source's, because the migrated host keeps its name. The image's entrypoint,USERandENVare not used: the role runs as root, with podman's own environment, as in the check. An interrupted run leavesvrtmv-role-trial-*containers and directories, removed as in the check. - No network. A task that installs a package the image does not have fails, because no repository can be reached, and so does the trial. A base image that already holds what the roles install (a golden image of your own) is tried as it is. Or give the trial outbound network, below.
Outbound network for the trial
vrtmv migrate --root /mnt/vm --target debian12 -o out/ \
--customer-roles ./roles --customer-role geerlingguy.nginx --customer-vars group_vars/web.yml \
--run-customer-roles-in-copy --try-customer-roles-on docker.io/library/debian:12 \
--try-customer-roles-with-network
--try-customer-roles-with-network gives each trial container outbound network, so that a role tried on a plain base image can install what the image does not have, from the repositories it names or adds. It is a flag of its own, and it needs --try-customer-roles-on: on its own it is refused before anything runs. Without it, the trial has no network.
- What it gives. The container gets podman's own private network (
podman run --network private): with rootless podman, slirp4netns or pasta; with rootful podman, podman's bridge. The roles' code can then reach whatever this machine can reach: package repositories, and also hosts on your networks. With rootless podman 4.3.1 and slirp4netns, the only setup vrtmv was run with, this machine's own loopback (10.0.2.2in the container) was not reachable; with rootful podman the bridge's gateway is this machine, so a service listening on it can be reached. The container is still removed when its trial ends, and runs as described above. - What it does not change. The check in a copy of the source has no network, with or without the flag, and so does the probe of
<image>'s Python and systemd. vrtmv itself still pulls no image and sends nothing. - What it records. The attestation's
customer_roles.trial.networkisoutbound, where it isnonewithout the flag, and the note undercustomer_rolessays the trial had outbound network.customer-roles.txtsays it on itsTrial:line. - What it means for the result. A role that installs a package now installs it as it would on the target, from the repositories the container can reach at the time of the run. What it manages is read the same way. A later run can install other versions.
Each role tried gets one result:
| Result | When |
|---|---|
passed | the run ended, and no task failed that the role does not ignore. A failure that a rescue recovers from counts as failed |
failed | a task failed; the report names it and the error. The output does not call the role |
did not finish | the run did not end: it was stopped after 30 minutes, or ansible-playbook exited without a failed task |
not run | the container did not start, or its results could not be read |
not tried | the check reads the role as does-not-match or inconclusive |
What a role manages is read from each task that ran, a handler included, and from each item of a loop:
| Module | What it manages |
|---|---|
apt, dnf, dnf5, yum, package, zypper, apk | each package it names, as given (name or pkg, a list or a comma-separated string) |
template, copy, lineinfile, blockinfile, replace, ini_file, assemble, file, pam_limits | the path, as the module reports the file it wrote (a dest that is a directory is resolved), or its dest or path |
service, systemd, systemd_service, sysvinit | the unit, by its full name (nginx is nginx.service) |
user, group | the account, the group |
sysctl | the key, and the sysctl_file it writes as a path |
cron | the entry, as user: name, and its cron_file as a path (under /etc/cron.d/ when relative). A task with env sets a variable, and is listed as cron_env: the module writes no #Ansible comment for a variable |
mount | the mount point |
A task skipped on the image manages nothing there. A task that sets variables, reads the host or controls the run (set_fact, include_*, stat, assert and the like) manages nothing. These are listed as not read, because what they manage is not in their arguments: a command, shell, script, raw or expect task that reported a change, or that set its own changed_when (one that reported none without it, such as one skipped by creates or removes, is taken at its word); a package task that names no package, that upgrades the host (upgrade other than no), that autoremoves, whose state is not present, installed, latest, absent or removed, or whose type is not package; a package name that is not a bare name (letters, digits and ._+-, not led by ., + or - and not ending in -, and for apt alone an optional :arch): *, a URL or a path, a package file, a @ group or module stream, a glob, a version, release or repository such as nginx=1.22.1-9, nginx~1.24, nginx/bookworm-backports or nginx@edge, a provide such as perl(DBI) or apk's cmd:bash, a kind such as zypper's pattern:lamp_server, any other name with a : outside apt, a remove or install mark such as zypper's -nginx, apk's !nginx or apt's nginx-, and for dnf, dnf5, yum, zypper and package a name whose last --separated part starts with a digit, such as nginx-1.20.1 (an architecture such as nginx:amd64 on apt or kernel.x86_64 is kept); a package task that installs a .deb file; a task whose arguments are not in its result (no_log), a path that is not absolute, and a module vrtmv does not read.
An object that two roles whose trial passed both manage is listed under "Managed by more than one role", with the roles: the output cannot call both and leave that object to either. Objects are compared by name as written: libc6:amd64 and libc6, or kernel.x86_64 and kernel, are not found as one package.
What the role installs, against vrtmv's plan
A role can pass its trial and still install something other than what vrtmv's plan installs: a repository of its own, and a package from it at another version. vrtmv's plan is the Index's answer for the target: each source package translated to the target's packages, or installed under its own name. For each role whose trial passed, vrtmv compares the two, and flags what differs. A flag never refuses the role and never changes it: the output calls it as it is.
- What is read. vrtmv reads the trial container twice, before the role and after it and its handlers: the package database (rpm or dpkg) and the repository files (
/etc/yum.repos.d,/etc/zypp/repos.d, apt'ssources.list,*.listand*.sources, and apk'srepositories). For each package the role installed or changed, it also reads where it came from: dnf's repository for it, or the sources apt lists for the installed version. zypper does not say, so on SUSE no package's origin is read and only the repositories and vendors are compared. An RPM's vendor is compared with the vendors the image's packages had before the role. The reads change nothing in the container. - What is flagged. An enabled repository the role adds or changes, with the packages installed from it and whether their signatures are checked (
gpgcheck=0, apt'strusted=yes). A package the role installs or changes that came from a repository the role added, or that came from no repository the image already had and whose vendor no package on the image had before the role: it is not the version vrtmv's plan installs. A target's own repositories may ship more than one vendor's builds (openSUSE Leap ships SUSE's, AlmaLinux 8 some of CloudLinux's), so a vendor the image already had is not flagged. A package the role installs that vrtmv's plan does not install, with what the Index maps the source's package of that name to. A package the role manages and leaves not installed, where vrtmv's plan installs it. - What is not flagged. A package the image already had at the same version: the role did not put it there. A package from the target's own repositories: that is what vrtmv's plan installs, at the time of the trial. A role's units and paths: a path the target does not have fails the trial, and that is a refusal.
- Not compared. On an image with neither rpm nor dpkg, packages are not compared, and the report says so; repositories still are. Nor when the role ends the play before vrtmv's read after it.
customer-roles.txt gives each role's flags under "Target fit, against vrtmv's plan", with each package the role manages: its version before and after the role, where it came from, and what vrtmv's plan has for it. The attestation has the same under customer_roles.roles[].trial.target_fit (packages, repositories, flags). For a role the output calls, each flag is also a caveat in the attestation: material, or minor for a package vrtmv's plan does not install.
customer-roles.txt gains a "Trial" block that names the image, and a "Tried on the target's base image" block for each role: the result and why, every object it manages with the task that manages it, and each task not read. The attestation has the same under customer_roles.roles[].trial, customer_roles.trial and customer_roles.overlaps.
Calling the roles from the output
With --try-customer-roles-on and --format ansible alone (the default), the output calls your roles that passed, and the role vrtmv writes leaves to them what they manage.
- Which roles are called. A role is called when the check in a copy reads it as
matchesorpartly-matchesand its trialpassed. A role the source does not match (does-not-match,inconclusive) is not called: running it would change the host away from the source. A role whose trialfailed,did not finishor wasnot runis refused, and so is each role of an object two passed roles manage. site.yml. One play for the host (hosts: all,become: true): the roles that are called, by name, in the order of your--customer-roleflags, thenvrtmv_migration. Your roles are not copied into the output: put the directory they are installed in on Ansible's roles path, beside the output'sroles/. Neither are your--customer-varsfiles, which may hold decrypted values:site.ymlnames each one with its sha256, and you give them to the host as host variables, in that order, as the check and the trial had them.site.ymlalso names each role's version and digest from the lock. Nosite.ymlis written when no role is called.- What
vrtmv_migrationleaves to them. For eight kinds of object, vrtmv drops its own task when a called role manages the object on the target's base image: a package it installs (a translated package or a passthrough), a config file it carries (compared at its path on the target, after a relocation), a sysctl key it writes, when every file that sets the key on the source, in either spelling (net.ipv4.ip_forwardornet/ipv4/ip_forward), is a file the role manages (each such file's carried copy is dropped with it), a unit, a mount point, an account, a group and a cron entry. These are left out of the role vrtmv writes and out of what the attestation promises for vrtmv. A carried file that leaves is also left out of the ownership vrtmv's role restores on carried files.- A unit leaves every decision vrtmv makes about units. vrtmv does not enable, mask or disable it, does not disable it after a target package enables it on install, writes no unit file for it from an init script, does not carry the source's unit file (
/etc/systemd/system/<unit>) or its drop-ins (every file under/etc/systemd/system/<unit>.d/, compared at their path on the target), and does not list it among the services the target will not start, so the role's last task does not fail on it. A source unit is compared by its name on the target, and an init script by the unit the Index maps it to, or by<script>.servicewhen the Index maps it to none. - A mount point leaves the network shares vrtmv's role mounts. A local filesystem there stays on the
[BLOCKING]list of filesystems the target build must provide, with a line saying the role mounts it: the role writes the fstab line or mounts it, and does not create the volume. vrtmv never promised to mount it, and does not now. - An account leaves the service accounts vrtmv's role creates, and the accounts the attestation promises (
aspects.accounts). vrtmv's role still restores the owner of each carried file the account owns, by name, after the copy: the role runs first, so the account is there. Naming an account as a file's owner uses it; it does not manage it. - A group leaves the groups vrtmv's role creates: an account's primary group, at its gid, or a supplementary group, by name. An account that is still vrtmv's names the group as its group or among its groups, which uses it as well.
- vrtmv's accounts and their primary groups have the source's uid and gid, which the files carried and copied from the source are owned by. So an account or primary group is left to a role only when the role's trial left it at the source's ids: the user task's uid and primary gid, and the group task's gid. A role that left one at other ids, or whose result did not report them, is refused. After the role runs, vrtmv's role checks the same on the host (task
Probe whether each account and group a customer role creates holds the source's id): the play stops when nothing holds the source's id, or another account or group does. A supplementary group is created by name, and has no id to check. An account or group vrtmv's role does not create is not compared. - A cron entry is found on the source by the
#Ansible: <name>comment thecronmodule writes directly above it, in the file the module looks in: the task'scron_file, or else the crontab of the task'suser. The job leaves the jobs vrtmv's role writes and the jobs the attestation promises (aspects.cron). Only the first entry of a name in a file is the task's, as the module reads it. Any other job of that user, with another marker or none, stays vrtmv's. - A job in a crontab the role writes whole (
template,copyorassemble) leaves with the file, and is recorded with it.
- A unit leaves every decision vrtmv makes about units. vrtmv does not enable, mask or disable it, does not disable it after a target package enables it on install, writes no unit file for it from an init script, does not carry the source's unit file (
- What refuses a role. Anything else a called role manages that the role vrtmv writes also names refuses that role: an account or a group that is a value of one of vrtmv's tasks (other than a file's
ownerorgroup, an account'sgrouporgroups, or agetentprobe), a sysctl key a file in its tasks sets, and an object of the kinds above, other than a cron entry, that another part of vrtmv's role writes. A.serviceunit is also looked for by its bare name, so a role that managesnginx.serviceand not thenginxpackage vrtmv installs is refused. vrtmv looks for each in its role as written after the drop; a comment is not looked at. A carried file's contents are copied from the source and are not in the tasks, so two more refuse a role: a sysctl key the role manages that the source sets in a file the role does not manage, in either spelling and whichever file wins (vrtmv keeps that file, or the key, and the source's value), and a file vrtmv carries below a directory the role manages, at any depth: vrtmv's copy runs after the role, and a role that sets the directory's contents or owner recursively would not keep them. A crontab a role only edits (withcron, or a module that changes part of a file, orfile) is left to it only when every job and variable in it is an entry of the role: the carried copy leaves with the file, and any other line would not reach the target. A variable is the role's when acrontask withenvsets it in that file. A cron entry with no#Ansiblecomment on the source refuses the role while vrtmv keeps any job of the workload: the job may be that entry, written by hand, and the module would write the entry beside vrtmv's copy, so that cron ran it twice. A refused role's objects stay vrtmv's, and the drop is made again without it, until no called role is refused. Two roles that would each change the other's object on every run never settle, so only a role vrtmv's role leaves alone is called. - Drift. For a role the source
partly-matches, each task whose result differs on the source is amaterialcaveat in the attestation: the role runs first and its result is kept, so the target is not the source there. The diff is in the role's check. To keep the source's value, give it to the role as one of its variables. - With another format. With
--format container,imageorterraform, alone or besideansible, nothing is called and nothing is dropped: those outputs do not call your roles, and the one attestation cannot promise an object as a role's for one output and as vrtmv's for another. The reason is in the report.
The attestation records it under customer_roles.combine: site (or not_written, with the reason), calls, not_called (each with refused or not matched, and why), and promises, one per object a called role manages, with promised_by (the role's name, version and sha256 from the lock) and dropped_from_vrtmv, what vrtmv had for it, when it had something. Every other promise in the attestation is vrtmv's. verify grades the roles' promises with the role's own check in a copy of the target, and without that it does not say equivalent. customer-roles.txt ends its trial block with an "Output" line, why each role is not called, and what vrtmv_migration dropped.
Files a carried config names
A file that matches what its package shipped is not carried: the target's packages bring their own. That does not hold across packaging families, where a carried config can name a file that only the source's packaging has. Gentoo's nginx.conf has include mime.types.nginx;, and no Rocky Linux package has that file, so nginx would stop at start.
So when the target is of another packaging family than the source, vrtmv reads the include lines of each carried file under /etc/nginx/, and carries an unchanged file under /etc that one of them names. A relative name is read from /etc/nginx/, and what the carried file includes is read in turn. The attestation classifies it named, and named_by gives the file that names it. If the target has a file at that path, the source's replaces it.
- What is not carried. A named file that is a symlink or is outside
/etcis listed among the files not carried, with the reason. - What is not read. An
includewith a glob, any other nginx directive that names a path, and the config of any other software. Those paths are carried only if they are carried for another reason.
Cron jobs
A carried /etc/crontab or /etc/cron.d file is copied to the same path, as the source has it: with its MAILTO=, PATH= and CRON_TZ= lines, its comments, and any line vrtmv could not read. Its jobs are not written a second time. The role writes with ansible.builtin.cron, into /etc/cron.d/vrtmv-<user>, only the jobs whose file it does not copy: a user crontab under /var/spool/cron, which is never carried, and a carried crontab whose disposition is not a copy. A comment above the role's cron task names the files whose jobs travel that way. The attestation promises every job, and verify reads them from the copy.
A cron entry of a customer role that site.yml calls is the role's: see Calling the roles from the output.
A role from a release before 2.7.0 also wrote each line of a copied file into /etc/cron.d/vrtmv-<user>, so cron ran it twice. On a target such a role was applied to, delete that file and apply the role again: the role writes back the jobs that belong in it.
Accounts the target will not have
The role creates the source's service accounts, at the source's uid and gid: an account below uid 1000, or with a nologin shell, that owns or group-owns a carried file, and an account a unit's User= names. It creates no other account, sets no password and never reads /etc/shadow.
The tasks file lists, in one [BLOCKING] comment under "Service accounts", each account the role does not create that is either at uid 1000 or above on the source (other than uid 65534), or the user a carried cron job runs as: a job in a carried /etc/crontab or /etc/cron.d file, or in a user crontab. Each line gives the uid, gid, home and shell the source's /etc/passwd gives it, and under it what names it: each such cron job, and each carried file it owns when it is an account at uid 1000 or above with a login shell. An account nothing names says so. A name the source's /etc/passwd does not hold is listed without ids; when a unit's User= names it too, that unit is among what names it, and it is not listed again with the units. Root and nobody are never listed: every target has them, and cron finds a job's user by name. Over --ssh the file owners are not read, so no file names an account.
Cron does not run a job whose user does not exist, and a carried file whose owner does not exist stays owned by root. Create each account before cutover, at the source's uid and gid, or confirm that a package the target installs creates it. The comment does not change migrate's exit status.
The attestation refuses each one under aspects.accounts, as account:<name>:<uid> (account:<name> without an entry), and its reason names what refers to it. When the attestation records that an image runs none of the cron jobs (container_target.jobs.cron_promise is replaced), a cron job does not name an account there.
Blocking steps
Some translations add a runbook step that the role cannot do for you. The role's tasks file lists them as comments under "Manual steps from conditional rules", a blocking one marked [BLOCKING], and the attestation records them. With a blocking step in the plan, migrate still writes its files and exits non-zero (migration is BLOCKED), --preflight counts it and exits non-zero too, and run stops before it applies anything. Do the step by hand and apply the role yourself, or change the source so the step does not fire.
For example, from AlmaLinux, CentOS, CentOS Stream, RHEL or Rocky Linux 8, 9 or 10 to Debian or Ubuntu, haproxy gets a blocking step when the source's /etc/haproxy/conf.d holds a file haproxy loads: a name that ends in .cfg, does not start with ., and is a regular file or a link to one. EL's haproxy.service loads that directory (-f $CFGDIR); the Debian and Ubuntu unit loads /etc/haproxy/haproxy.cfg only, so on the target haproxy would start without what those files define. The step gives the systemctl edit haproxy drop-in that adds -f /etc/haproxy/conf.d to the unit's command lines. An empty conf.d, as EL ships it, does not fire it, nor do names such as .cfg.rpmsave. To avoid the step, move what the conf.d files define into /etc/haproxy/haproxy.cfg on the source before you migrate.
Preflight vs full run
--preflight is the feasibility check: it runs the same analysis, prints the translatable/unresolved/untranslated counts and the number of blocking manual steps, and stops. It writes nothing and is not billable. A full run records one depersonalized migration usage event; whether that event is billable depends on your plan and target (see Accounts, quota & billing).
New to vrtmv? Sign up free for 10 migrations, or get a free assessment: run it on one hard host and we review the parity report with you.