blib/lib/App/FuguVM/Guest.pm untested

filter: Statementstmt 0.0% 0 / 718 Branchbran 0.0% 0 / 318 Conditioncond 0.0% 0 / 171 MC/DCmcdc 0.0% 0 / 103 Subroutinesub 0.0% 0 / 87 Podpod 0.0% 0 / 64 totaltotal 0.0% 0 / 1461 CC 160 SCAR 58.5
CC
160
Cov
0%
up
1892.0
start
72.0
status
72.0
CRAP 348.2
1 # ex:ts=8 sw=4:
2 # $OpenBSD$
3 #
4 # Copyright (c) 2024 Dick Olsson <hi@senzilla.io>
5 #
6 # Permission to use, copy, modify, and distribute this software for any
7 # purpose with or without fee is hereby granted, provided that the above
8 # copyright notice and this permission notice appear in all copies.
9 #
10 # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17  
18 use v5.36;
19  
20 # App::FuguVM::Guest - the lifecycle of one OpenBSD guest.
21 #
22 # The module creates, starts, waits for, stops, and destroys one
23 # guest. It drives QEMU over QMP, so the lifecycle verbs report what
24 # the hypervisor says and not what a sleep guessed.
25  
26 package App::FuguVM::Guest;
27 our $VERSION = '0.3.1';
28  
29 use App::FuguVM::Arch;
30 use App::FuguVM::Autoinstall;
31 use App::FuguVM::Config;
32 use App::FuguVM::Miniroot;
33 use App::FuguVM::Mirror;
34 use App::FuguVM::DiskCache;
35 use App::FuguVM::Disk;
36 use App::FuguVM::Console;
37 use App::FuguVM::Proxy;
38 use App::FuguVM::QMP;
39 use App::FuguVM::State;
40  
41 use Fcntl qw(:flock);
42 use Fugu::File;
43 use Fugu::Random;
44 use Fugu::Process;
45 use Fugu::SSH;
46 use Fugu::Timeout;
47  
48 use constant {
49 EXIT_SUCCESS => 0,
50 EXIT_ERROR => 1,
51 EXIT_CONFIG_ERROR => 3,
52 EXIT_VM_RUNNING => 5,
53 EXIT_TIMEOUT => 7,
54 EXIT_EXPECT_FAILED => 9,
55  
56 MEMORY_DEFAULT => '1G',
57 CPU_COUNT => 2,
58  
59 # The port lock closes the window between the probe and the
60 # record of both ports. A probe is quick, so a long wait means
61 # a wedged holder, and the probe then runs without the lock.
62 PORT_LOCK_TIMEOUT => 30,
63  
64 # The bound on one 'qemu --version' run.
65 QEMU_VERSION_TIMEOUT => 10,
66 };
67  
68 sub new ( $class, %args )
69 {
70 my $self = bless {
71 config => $args{config},
72 state => $args{state},
73 log => $args{log},
74 emulate => $args{emulate} // 0,
75 no_cache => $args{no_cache} // 0,
76 }, $class;
77  
78 return $self;
79 }
80  
81 # The operation is idempotent. It makes sure that the VM runs.
82 sub up ($self)
83 {
84 my $config = $self->{config};
85 my $state = $self->{state};
86 my $log = $self->{log};
87  
88 # The QEMU binary of the architecture must be on PATH before
89 # any other work starts.
90 return EXIT_CONFIG_ERROR if !$self->_require_qemu;
91  
92 return EXIT_ERROR if !$self->_check_installed_arch;
93  
94 # Check if the VM already runs
95 if ( $self->_is_running ) {
96  
97 # The VM runs, but the SSH key is not installed or is not
98 # current. This occurs when the first boot failed, or when
99 # the key changed in the configuration.
100 if ( $state->is_installed && $self->_needs_ssh_key_update ) {
101 return $self->_complete_ssh_setup;
102 }
103  
104 $log->info("VM '$config->{name}' is already running");
105 return EXIT_SUCCESS;
106 }
107  
108 # The version gate runs one time for each invocation, before
109 # any expensive work starts.
110 my $failure = $self->_check_qemu_version;
111 return $failure if defined $failure;
112  
113 # Verify the backing chain of the disk before other checks read
114 # the disk. A base image that is missing from the cache is not
115 # corruption. The unclean-shutdown check below would report it as
116 # corruption and recommend 'fuguvm disk repair'. That command
117 # cannot make a missing backing file again.
118 if ( $state->disk_exists && !$self->_verify_backing_chain ) {
119 return EXIT_ERROR;
120 }
121  
122 # Check for an unclean shutdown. Then check the disk integrity.
123 if ( $state->was_unclean_shutdown ) {
124 $log->warning("Detected unclean shutdown, checking disk...");
125 my $disk = App::FuguVM::Disk->new( $state->state_dir );
126 my $check = $disk->check( $config->{name} );
127  
128 if ( defined $check && $check->{status} ne 'ok' ) {
129 $log->error(
130 "Disk corruption detected. Run 'fuguvm disk repair' to fix"
131 );
132 return EXIT_ERROR;
133 }
134 $state->clear_shutdown_state;
135 }
136  
137 # The mode decides the origin of the disk. The configuration
138 # loader derives the value, and no module compares the
139 # directives again.
140 my $mode = $config->{install_mode} // 'expect';
141  
142 # Derive the installed-image cache key one time only, before the
143 # installer runs. key() hashes its script at call time. An
144 # install takes tens of minutes. A key derived again after the
145 # install would publish the image the OLD installer made under
146 # the NEW digest.
147 my $cache = $self->_image_cache;
148 my $cache_key = defined $cache ? $cache->key($config) : undef;
149  
150 # An imported base lives in the cache, so the import mode
151 # cannot run without one. The configuration loader refuses
152 # 'image_cache no'; this check covers 'up --no-cache'.
153 if ( $mode eq 'import' && !defined $cache ) {
154 $log->error( "base_disk needs the image cache;"
155 . " run 'fuguvm up' without --no-cache" );
156 return EXIT_CONFIG_ERROR;
157 }
158 if ( $mode eq 'import' && !defined $cache_key ) {
159 $log->error("Cannot derive the cache key of the imported base");
160 return EXIT_ERROR;
161 }
162  
163 # Outside the expect mode the operator owns the credential.
164 # Seed the state from root_password_file, so the SSH key setup
165 # can authenticate. The state then behaves as after an expect
166 # install.
167 if ( $mode ne 'expect' && defined $config->{root_password_file} ) {
168 my $password = $self->_root_password;
169 $state->set_root_password($password) if defined $password;
170 }
171  
172 # Restore from the installed-image cache when there is no disk
173 # yet. A miss can mean that a sibling run installs this entry
174 # right now. The lock makes this run wait, and the second lookup
175 # then uses the entry that the sibling published. A run without
176 # the lock still installs correctly, because store() is
177 # write-once: it wastes an install, never the cache.
178 my $cache_lock;
179 if ( !$state->disk_exists && defined $cache_key ) {
180 if ( !$self->_cache_restore( $cache, $cache_key ) ) {
181  
182 # The wait can last as long as one installation,
183 # so the operator hears about it first.
184 $log->info("Taking the image-cache lock of $cache_key");
185 $cache_lock = $cache->lock_entry($cache_key);
186 if ( !defined $cache_lock ) {
187 $log->warning(
188 "Image-cache lock not acquired, installing without it"
189 );
190 }
191 elsif ( $self->_cache_restore( $cache, $cache_key ) ) {
192  
193 # The entry exists now, so nothing here
194 # installs. Release the lock at once: a
195 # sibling behind it needs only the entry.
196 close $cache_lock;
197 undef $cache_lock;
198 }
199  
200 # The import mode installs nothing: publish the
201 # outside file as the entry, then overlay it. The
202 # lock above serializes the publication, so a
203 # parallel fleet publishes one time.
204 if ( !$state->disk_exists && $mode eq 'import' ) {
205 my $imported =
206 $self->_import_base( $cache, $cache_key )
207 && $self->_cache_restore( $cache,
208 $cache_key );
209 if ( defined $cache_lock ) {
210 close $cache_lock;
211 undef $cache_lock;
212 }
213 return EXIT_ERROR if !$imported;
214 }
215 }
216 }
217  
218 # Start the caching proxy for the VM installation. The VM
219 # downloads its packages through the proxy. The first run also
220 # uses the proxy to download the miniroot image.
221 my $proxy = $self->_ensure_proxy;
222 my $proxy_vm_url; # For downloads inside the OpenBSD guest
223  
224 if ( defined $proxy ) {
225 $proxy_vm_url = $proxy->guest_url;
226 $log->info("Proxy started: $proxy_vm_url");
227 }
228 else {
229 $log->info(
230 "Proxy not available, VM downloads will not be cached");
231 }
232  
233 # Make sure that the miniroot is available. Download it through
234 # the proxy if necessary. Only the installer boots the miniroot.
235 # An installed system boots its own disk, whether it was freshly
236 # installed or restored from the image cache. Such a system must
237 # not fail here because the miniroot was pruned.
238 my $image_path;
239  
240 if ( !$state->is_installed ) {
241 $log->info("Checking OpenBSD image...");
242 my $mirror = $self->_mirror($proxy);
243 my $image = App::FuguVM::Miniroot->new( $self->_cache_dir,
244 $proxy, $mirror );
245 $image_path = $image->ensure;
246  
247 if ( !defined $image_path ) {
248 my $url = $image->url;
249 $log->error(
250 "Failed to get a verified image for OpenBSD $config->{version}"
251 );
252 $log->error( $mirror->error ) if defined $mirror->error;
253 $log->error("URL: $url");
254 return EXIT_ERROR;
255 }
256  
257 $log->info("Using cached image: $image_path");
258 }
259  
260 # Make sure that the disk exists
261 my $disk_path = $state->disk_path;
262  
263 if ( !$state->disk_exists ) {
264 $log->info("Creating disk image ($config->{disk_size})...");
265 my $disk = App::FuguVM::Disk->new( $state->state_dir );
266 my $result =
267 $disk->create( $config->{name}, $config->{disk_size} );
268 if ( !defined $result ) {
269 $log->error("Failed to create disk");
270 return EXIT_ERROR;
271 }
272 }
273  
274 # Resolve and record the ports directly before the spawn. An
275 # 'up' that failed above then reserves no port for a guest
276 # that never started.
277 $failure = $self->_resolve_ports;
278 return $failure if defined $failure;
279  
280 # Start the VM
281 $log->info("Starting VM...");
282  
283 # Attach the install media only when the system is not installed
284 my $boot_image = $state->is_installed ? undef : $image_path;
285 my $pid = $self->_start_qemu($boot_image);
286 if ( !defined $pid ) {
287 $log->error("Failed to start VM");
288 return EXIT_ERROR;
289 }
290  
291 $log->info("Started $config->{name} (PID: $pid)");
292  
293 # Install the system if necessary
294 if ( !$state->is_installed ) {
295  
296 # The proxy already runs. The code above started it for the
297 # image download. Use the VM-accessible URL for the
298 # installation. The VM connects to the host through the
299 # gateway.
300 my $install_proxy_url = $proxy_vm_url // 'none';
301  
302 # The tool owns the credential in the expect mode only.
303 # In the autoinstall mode the response file owns it, and
304 # the seeding above stored the operator's copy.
305 my $root_password;
306 if ( $mode eq 'expect' ) {
307 $root_password = $self->_root_password;
308 $state->set_root_password($root_password);
309 }
310 else {
311 $root_password = $state->get_root_password;
312 }
313  
314 $log->info("Installing OpenBSD...");
315 my $expect = App::FuguVM::Console->new(
316 host => $self->connect_address,
317 port => $self->console_port,
318 );
319  
320 if ( $mode eq 'autoinstall' ) {
321 my $failure =
322 $self->_run_autoinstall( $expect, $proxy_vm_url );
323 return $failure if defined $failure;
324 }
325 else {
326 # Use the generated password for the installation
327 my $ok = $expect->run_install(
328 $self->_install_config(
329 $root_password, $install_proxy_url
330 ) );
331 if ( !$ok ) {
332 $log->error("Installation failed");
333 return EXIT_EXPECT_FAILED;
334 }
335 }
336  
337 $state->mark_installed( $config->{arch} );
338 $log->info("Installation complete");
339  
340 # Stop the VM gracefully through QMP. The image cache
341 # captures the disk at exactly this point: installed,
342 # pristine, and without the per-checkout SSH key. Thus the
343 # capture must know that QEMU is really gone. It must not
344 # assume it.
345 $log->info("Stopping installation VM...");
346 $self->_qmp_quit;
347 my $clean_exit = $self->_wait_exit(30);
348  
349 if ( !$clean_exit ) {
350 $log->warning(
351 "Installation VM did not exit on request, force stopping"
352 );
353 $self->_force_stop;
354 $self->_wait_exit(10);
355 }
356 $state->clear_vm_pid;
357  
358 # The runtime record stays: the restart below uses the
359 # same ports, and a sibling that resolves ports in this
360 # window must still skip them.
361  
362 # Publish the installed disk as a cached base image. A VM
363 # that was force stopped can leave the disk mid-write. Thus
364 # the code skips that capture and does not publish it.
365 if ( defined $cache_key ) {
366 if ($clean_exit) {
367 $self->_cache_store( $cache, $cache_key,
368 $root_password );
369 }
370 else {
371 $log->warning(
372 "Skipping image cache: installation VM was force stopped"
373 );
374 }
375 }
376  
377 # The entry is published, or this run cannot publish it.
378 # Either way a waiting sibling can proceed now.
379 if ( defined $cache_lock ) {
380 close $cache_lock;
381 undef $cache_lock;
382 }
383  
384 # Restart the VM without the install media
385 $log->info("Restarting installed system...");
386 $pid = $self->_start_qemu; # No boot image, no exit_on_halt
387 if ( !defined $pid ) {
388 $log->error("Failed to restart VM");
389 return EXIT_ERROR;
390 }
391 $log->info("Started $config->{name} (PID: $pid)");
392  
393 # Install the SSH authorized key for future key-based
394 # authentication. Outside the expect mode a guest can
395 # carry no configured key: the image must trust the key
396 # of the operator already, and the wait below proves it.
397 if ( $mode eq 'expect' || $self->_needs_ssh_key_update ) {
398 return $self->_complete_ssh_setup;
399 }
400 }
401  
402 # The VM is installed. Check if the SSH key must be installed or
403 # updated.
404 if ( $self->_needs_ssh_key_update ) {
405  
406 # The SSH key is not installed, or it changed in the
407 # configuration. Use password authentication to wait for
408 # SSH. Then install the key.
409 return $self->_complete_ssh_setup;
410 }
411  
412 # Wait for SSH. An installed VM uses key-based authentication.
413 $log->info("Waiting for SSH...");
414 if ( !$self->wait_ssh(120) ) {
415 $log->error("Timeout waiting for SSH");
416 return EXIT_TIMEOUT;
417 }
418  
419 $log->info("VM ready");
420 return EXIT_SUCCESS;
421 }
422  
423 # $self->_image_cache:
424 # Return the installed-image cache for this VM's configured
425 # cache_dir. Return undef when caching is off. 'up --no-cache'
426 # turns caching off for a single invocation. 'image_cache no'
427 # turns it off in the configuration. Both stop restore and save
428 # together. A half-cached run would leave an overlay with a base
429 # that nothing published.
430 sub _image_cache ($self)
431 {
432 return if $self->{no_cache};
433  
434 my $enabled = $self->{config}{image_cache};
435 return if defined $enabled && !$enabled;
436  
437 return App::FuguVM::DiskCache->new( $self->_cache_dir );
438 }
439  
440 # $self->_verify_backing_chain:
441 # Make sure that the backing image of the working disk, if the
442 # disk has one, is present. Return true when the chain resolves.
443 # On a break, log the missing file and a remedy, and return
444 # false. Thus a pruned or evicted cache entry fails with an
445 # explanation, not with an opaque QEMU open error at boot.
446 sub _verify_backing_chain ($self)
447 {
448 my $config = $self->{config};
449 my $state = $self->{state};
450 my $log = $self->{log};
451  
452 my $disk = App::FuguVM::Disk->new( $state->state_dir );
453 my $backing = $disk->backing_file( $config->{name} );
454 return 1 if !defined $backing;
455 return 1 if -f $backing;
456  
457 $log->error("Backing image missing: $backing");
458  
459 my $cache_dir = $self->_cache_dir;
460 if ( index( $backing, "$cache_dir/" ) == 0 ) {
461 $log->error(
462 "The image cache no longer holds this disk's base image."
463 );
464 }
465 $log->error("Run 'fuguvm destroy' and 'fuguvm up' to rebuild the VM.");
466  
467 return 0;
468 }
469  
470 # $self->_cache_restore($cache, $key):
471 # Create the working disk as an overlay on a cached base image.
472 # Seed the state that the installation would have written. Return
473 # true on a cache hit. Return false on a miss or on any failure.
474 # In both cases the caller then installs from scratch.
475 sub _cache_restore ( $self, $cache, $key )
476 {
477 my $config = $self->{config};
478 my $state = $self->{state};
479 my $log = $self->{log};
480  
481 my $hit = $cache->lookup($key);
482 if ( !defined $hit ) {
483 $log->info("No cached image for $key, installing");
484 return 0;
485 }
486  
487 my $disk = App::FuguVM::Disk->new( $state->state_dir );
488 my $path =
489 $disk->create( $config->{name}, undef, $hit->{base} );
490 if ( !defined $path ) {
491 $log->warning(
492 "Cannot overlay cached image $key, installing instead");
493 return 0;
494 }
495  
496 # The base was captured from an installed system. Thus the state
497 # that the installer would have written comes from the metadata
498 # of the base. The later SSH key install authenticates with the
499 # root password. That password is baked into the image.
500 $state->mark_installed( $config->{arch} );
501 my $password = $hit->{meta}{root_password};
502 $state->set_root_password($password) if defined $password;
503 $state->data->{cached_from} = $key;
504 $state->save;
505  
506 $log->info("Using cached image $key");
507 return 1;
508 }
509  
510 # $self->_cache_store($cache, $key, $root_password):
511 # Publish the freshly installed disk as a cached base image. Then
512 # replace the working disk with an overlay on that image. The
513 # operation is best effort. On any failure it keeps the
514 # standalone disk in place and warns. 'up' must never fail
515 # because caching failed.
516 sub _cache_store ( $self, $cache, $key, $root_password )
517 {
518 my $config = $self->{config};
519 my $state = $self->{state};
520 my $log = $self->{log};
521  
522 $log->info("Caching installed image as $key...");
523  
524 my $base = $cache->store(
525 $key,
526 $state->disk_path,
527 {
528 root_password => $root_password,
529 version => $config->{version},
530 disk_size => $config->{disk_size},
531 } );
532 if ( !defined $base ) {
533 $log->warning("Could not cache installed image, continuing");
534 return 0;
535 }
536  
537 if ( !$self->_reparent_disk($base) ) {
538 $log->warning(
539 "Cached image saved but disk left standalone: $base");
540 return 0;
541 }
542  
543 $log->info("Cached installed image: $base");
544 return 1;
545 }
546  
547 # $self->_reparent_disk($base):
548 # Replace the working disk with a fresh overlay backed by $base.
549 # The method moves the old disk aside and does not delete it.
550 # Thus a failure to create the overlay cannot leave the VM
551 # without a disk.
552 sub _reparent_disk ( $self, $base )
553 {
554 my $config = $self->{config};
555 my $state = $self->{state};
556 my $log = $self->{log};
557  
558 my $disk_path = $state->disk_path;
559 my $saved = "$disk_path.replaced";
560  
561 unlink $saved if -f $saved;
562 rename $disk_path, $saved or do {
563 $log->warning("Cannot move $disk_path aside: $!");
564 return 0;
565 };
566  
567 # Disk::create returns early on an existing path. Thus the
568 # rename above is what makes this call create the overlay.
569 my $disk = App::FuguVM::Disk->new( $state->state_dir );
570 my $path = $disk->create( $config->{name}, undef, $base );
571 if ( !defined $path ) {
572 rename $saved, $disk_path
573 or $log->error("Cannot restore $disk_path: $!");
574 return 0;
575 }
576  
577 unlink $saved or $log->warning("Cannot remove $saved: $!");
578 return 1;
579 }
580  
581 # $self->_import_base($cache, $key):
582 # Publish the configured base_disk as the cache entry of $key.
583 # The publication costs one conversion of the whole image, and
584 # it happens one time for each host: the entry is write-once,
585 # and every guest of the project derives the same key. The tool
586 # only reads the source file. The metadata holds no root
587 # password, because the tool must not invent a credential for an
588 # image that it did not install. Return 1 on success.
589 sub _import_base ( $self, $cache, $key )
590 {
591 my $config = $self->{config};
592 my $log = $self->{log};
593 my $source = $config->{base_disk};
594  
595 if ( !-f $source ) {
596 $log->error( "The base_disk file is gone: $source"
597 . " (cache miss for $key)" );
598 return 0;
599 }
600  
601 $log->info("Publishing $source as $key...");
602 my $base = $cache->store(
603 $key, $source,
604 {
605 imported_from => $source,
606 install_mode => 'import',
607 version => $config->{version},
608 } );
609 if ( !defined $base ) {
610  
611 # store is write-once, so a sibling can have published
612 # the entry inside the window. A lookup decides.
613 return defined $cache->lookup($key) ? 1 : 0;
614 }
615  
616 $log->info("Published imported base: $base");
617 return 1;
618 }
619  
620 # $self->_install_config($root_password, $proxy_url):
621 # Return the configuration of one expect install. The verify
622 # flag rides along as the word that the script reads: 'yes' or
623 # 'no'.
624 sub _install_config ( $self, $root_password, $proxy_url )
625 {
626 return {
627 %{ $self->{config} },
628 root_password => $root_password,
629 proxy_url => $proxy_url // 'none',
630 verify => ( $self->{config}{verify} // 1 ) ? 'yes' : 'no',
631 };
632 }
633  
634 # $self->_mirror($proxy):
635 # Build the mirror of this guest over the cache of the proxy. A
636 # run without a proxy still verifies: the mirror then builds a
637 # cache over the same directory.
638 sub _mirror ( $self, $proxy = undef )
639 {
640 my $config = $self->{config};
641  
642 my $cache =
643 defined $proxy
644 ? $proxy->cache
645 : App::FuguVM::Proxy::Cache->new( $self->_cache_dir );
646  
647 return App::FuguVM::Mirror->new(
648 cache => $cache,
649 version => $config->{version},
650 arch => $config->{arch},
651 verify => $config->{verify} // 1,
652 log => $self->{log},
653 (
654 defined $config->{signify_dir}
655 ? ( keys_dir => $config->{signify_dir} )
656 : ()
657 ),
658 );
659 }
660  
661 # $self->_run_autoinstall($expect, $proxy_url):
662 # Start the responder, drive the autoinstall over the console,
663 # and stop the responder on every path out of the install.
664 # Return undef on success, and an exit code on failure.
665 sub _run_autoinstall ( $self, $expect, $proxy_url = undef )
666 {
667 my $log = $self->{log};
668  
669 my $responder = $self->_autoinstall($proxy_url);
670 if ( !defined $responder->start ) {
671 $log->error( 'Responder did not start: '
672 . ( $responder->error // 'unknown' ) );
673 return EXIT_ERROR;
674 }
675  
676 my $url = $responder->guest_url;
677 $log->info("Responder started: $url");
678  
679 my $ok = $expect->run_autoinstall(
680 { %{ $self->{config} }, autoinstall_url => $url } );
681  
682 $responder->stop;
683  
684 if ( !$ok ) {
685 $log->error("Autoinstall failed");
686 return EXIT_EXPECT_FAILED;
687 }
688  
689 return;
690 }
691  
692 # $self->_root_password:
693 # Return the root password of this guest. The tool owns the
694 # credential in the expect mode, so the method generates one
695 # there. In every other mode the operator owns it, and the
696 # method returns the first line of root_password_file, with no
697 # trailing newline, or undef without the directive. Thus the
698 # secret has a short life in the process, and no configuration
699 # hash carries it.
700 sub _root_password ($self)
701 {
702 my $config = $self->{config};
703 my $mode = $config->{install_mode} // 'expect';
704  
705 if ( $mode eq 'expect' ) {
706 $self->{log}->info("Generated secure root password");
707 return Fugu::Random->random_password(32);
708 }
709  
710 my $file = $config->{root_password_file};
711 return if !defined $file;
712  
713 my $bits = ( stat $file )[2];
714 $self->{log}->warning("The group or other users can read $file")
715 if defined $bits && $bits & 0044;
716  
717 open my $fh, '<', $file or do {
718 $self->{log}->error("Cannot read $file: $!");
719 return;
720 };
721 my $line = <$fh>;
722 close $fh;
723 return if !defined $line;
724  
725 chomp $line;
726 return $line;
727 }
728  
729 sub down ($self)
730 {
731 # Stop the responder and the proxy if they run
732 if ( $self->_stop_autoinstall ) {
733 $self->{log}->info("Autoinstall responder stopped");
734 }
735 if ( $self->_stop_proxy ) {
736 $self->{log}->info("Proxy stopped");
737 }
738  
739 return $self->stop;
740 }
741  
742 sub destroy ($self)
743 {
744 my $state = $self->{state};
745 my $log = $self->{log};
746 my $config = $self->{config};
747  
748 # Stop the responder and the proxy if they run
749 if ( $self->_stop_autoinstall ) {
750 $log->info("Autoinstall responder stopped");
751 }
752 if ( $self->_stop_proxy ) {
753 $log->info("Proxy stopped");
754 }
755  
756 # Stop the VM if it runs
757 if ( $self->_is_running ) {
758 $self->stop(1);
759 }
760  
761 # Remove the disk
762 my $disk_path = $state->disk_path;
763 if ( -f $disk_path ) {
764 $log->info("Removing disk image...");
765 unlink $disk_path or do {
766 $log->error("Cannot remove $disk_path: $!");
767 return EXIT_ERROR;
768 };
769 }
770  
771 # Remove the QMP socket
772 my $qmp_path = $self->_qmp_socket_path;
773 unlink $qmp_path if -S $qmp_path;
774  
775 # Clear the state
776 %{ $state->data } = ();
777 $state->save;
778  
779 $log->info("VM '$config->{name}' destroyed");
780 return EXIT_SUCCESS;
781 }
782  
783 sub start ($self)
784 {
785 my $state = $self->{state};
786 my $log = $self->{log};
787 my $config = $self->{config};
788  
789 return EXIT_CONFIG_ERROR if !$self->_require_qemu;
790  
791 return EXIT_ERROR if !$self->_check_installed_arch;
792  
793 if ( $self->_is_running ) {
794 $log->error("VM '$config->{name}' is already running");
795 return EXIT_VM_RUNNING;
796 }
797  
798 if ( !$state->disk_exists ) {
799 $log->error("No disk image. Run 'fuguvm up' first.");
800 return EXIT_ERROR;
801 }
802  
803 # The version gate and the port resolution run one time for
804 # each invocation, before the spawn.
805 my $failure = $self->_check_qemu_version;
806 return $failure if defined $failure;
807  
808 $failure = $self->_resolve_ports;
809 return $failure if defined $failure;
810  
811 my $pid = $self->_start_qemu;
812 if ( !defined $pid ) {
813 $log->error("Failed to start VM");
814 return EXIT_ERROR;
815 }
816  
817 $log->info("Started $config->{name} (PID: $pid)");
818 return EXIT_SUCCESS;
819 }
820  
821 sub stop ( $self, $force = 0 )
822 {
823 my $state = $self->{state};
824 my $log = $self->{log};
825 my $config = $self->{config};
826  
827 if ( !$self->_is_running ) {
828  
829 # A crashed guest cannot clear its own record and its
830 # own pid file, so the stop verb clears both here.
831 $state->clear_vm_pid;
832 $state->clear_runtime;
833 $log->info("VM '$config->{name}' is not running");
834 return EXIT_SUCCESS;
835 }
836  
837 if ($force) {
838 $log->warning(
839 "Force stopping VM (filesystem may be corrupted)");
840 return $self->_stop_unclean;
841 }
842  
843 # Try a graceful shutdown with a filesystem sync
844 $log->info("Shutting down VM gracefully...");
845 if ( $self->_graceful_shutdown ) {
846 $state->mark_clean_shutdown;
847 $state->clear_vm_pid;
848 $state->clear_runtime;
849 $log->info("VM stopped");
850 return EXIT_SUCCESS;
851 }
852  
853 # If the graceful shutdown times out, force stop the VM
854 $log->warning(
855 "Graceful shutdown timed out, force stopping (risk of corruption)"
856 );
857 return $self->_stop_unclean;
858 }
859  
860 # $self->_stop_unclean:
861 # Force-stop the VM and record the unclean shutdown, so the next
862 # 'up' checks the disk.
863 sub _stop_unclean ($self)
864 {
865 my $state = $self->{state};
866  
867 $state->mark_unclean_shutdown;
868 $self->_force_stop;
869 $state->clear_vm_pid;
870 $state->clear_runtime;
871 $self->{log}->info("VM stopped");
872  
873 return EXIT_SUCCESS;
874 }
875  
876 sub status ($self)
877 {
878 my $state = $self->{state};
879 my $config = $self->{config};
880  
881 my $running = $self->_is_running;
882 my $pid = $state->get_vm_pid;
883  
884 # Query the QEMU status through QMP if the VM runs
885 my $qemu_status;
886 if ($running) {
887 my $qmp = $self->_qmp_connect;
888 if ($qmp) {
889 my $status = $qmp->query_status;
890 $qemu_status = $status->{status} if $status;
891 $qmp->disconnect;
892 }
893 }
894  
895 return {
896 name => $config->{name},
897 state => $running ? ( $qemu_status // 'running' ) : 'stopped',
898  
899 # A dead process ID is not a fact of a stopped guest, so
900 # a pid file that a crash left behind reads as empty.
901 pid => $running ? $pid : undef,
902 arch => $config->{arch},
903 accel => $self->accel,
904 bind_address => $self->bind_address,
905 ssh_port => $self->ssh_port,
906 console_port => $self->console_port,
907 installed => $state->is_installed ? 1 : 0,
908 disk_exists => $state->disk_exists ? 1 : 0,
909  
910 # The proxy URL as the guest reaches it, or empty while
911 # the proxy does not run. The port changes between runs,
912 # so a consumer reads the value here and must not write
913 # it in a file. Scalar context: a bare return would
914 # collapse the pair.
915 proxy_url => scalar $self->_proxy->guest_url,
916 };
917 }
918  
919 sub is_running ($self)
920 {
921 return $self->_is_running;
922 }
923  
924 # $self->accel:
925 # Return the recorded accelerator while the guest runs: a guest
926 # that started under --emulate runs TCG whatever the host can do
927 # now. Return the accelerator that the tool selects now in every
928 # other case. App::FuguVM::Arch->accelerator owns the choice.
929 sub accel ($self)
930 {
931 if ( $self->{state} && $self->_is_running ) {
932 my $recorded = $self->{state}->get_runtime->{accel};
933 return $recorded if defined $recorded;
934 }
935  
936 return 'tcg' if $self->{emulate};
937  
938 return $self->_arch->accelerator( $^O, _host_arch(),
939 -w '/dev/kvm' ? 1 : 0 );
940 }
941  
942 # $self->bind_address:
943 # Return the host address of the forwarded ports. The
944 # configuration loader injects the value; the fallback only
945 # serves VM objects built without a configuration.
946 sub bind_address ($self)
947 {
948 return $self->{config}{bind_address}
949 // App::FuguVM::Config::DEFAULT_BIND_ADDRESS();
950 }
951  
952 # $self->connect_address:
953 # Return the address that the tool connects to. A bind address
954 # of 0.0.0.0 is not a destination, so the loopback address
955 # serves that one case.
956 sub connect_address ($self)
957 {
958 my $address = $self->bind_address;
959 return '127.0.0.1' if $address eq '0.0.0.0';
960  
961 return $address;
962 }
963  
964 # The resolved ports. Each method returns the recorded port, and
965 # falls back to the configured number. It returns undef for 'auto'
966 # with no record: the record dies with the run, so a stopped guest
967 # has no port.
968 sub ssh_port ($self)
969 {
970 return $self->_resolved_port('ssh_port');
971 }
972  
973 sub console_port ($self)
974 {
975 return $self->_resolved_port('console_port');
976 }
977  
978 sub _resolved_port ( $self, $directive )
979 {
980 # The record describes the current run, so it serves only
981 # while the guest runs. A crashed guest leaves a record
982 # behind. That record must not read as a live port.
983 if ( $self->{state} && $self->_is_running ) {
984 my $recorded = $self->{state}->get_runtime->{$directive};
985 return $recorded if defined $recorded;
986 }
987  
988 # The answer is one scalar, undef included: a caller builds a
989 # hash with it, and a bare return would collapse the pair.
990 my $configured = $self->{config}{$directive};
991 $configured = undef
992 if defined $configured
993 && $configured eq App::FuguVM::Config::AUTO_PORT();
994  
995 return $configured;
996 }
997  
998 # $self->wait_ssh($timeout, $password):
999 # Wait for SSH to become available. Without a password, the
1000 # connection uses the SSH agent for authentication. The initial
1001 # installation gives the root password, because the SSH key is
1002 # not in yet.
1003 sub wait_ssh ( $self, $timeout = 120, $password = undef )
1004 {
1005 my $ssh = Fugu::SSH->new(
1006 host => $self->connect_address,
1007 port => $self->ssh_port,
1008 user => 'root',
1009 ( defined $password ? ( password => $password ) : () ),
1010 );
1011  
1012 return $ssh->wait_available($timeout);
1013 }
1014  
1015 # $self->_needs_ssh_key_update:
1016 # Check if the SSH key must be installed or updated. Return true
1017 # if no key is installed. Also return true if the configured key
1018 # differs from the installed key.
1019 sub _needs_ssh_key_update ($self)
1020 {
1021 my $config = $self->{config};
1022 my $state = $self->{state};
1023  
1024 my $configured_key = $config->{ssh_pubkey};
1025 my $installed_key = $state->get_installed_ssh_pubkey;
1026  
1027 # No key is configured. There is nothing to install.
1028 return 0 if !defined $configured_key || $configured_key eq '';
1029  
1030 # No key is installed yet
1031 return 1 if !defined $installed_key;
1032  
1033 # Compare the keys. Normalize the whitespace for the comparison.
1034 my $configured_normalized = $configured_key =~ s/\s+/ /gr;
1035 my $installed_normalized = $installed_key =~ s/\s+/ /gr;
1036  
1037 return $configured_normalized ne $installed_normalized;
1038 }
1039  
1040 # $self->_complete_ssh_setup():
1041 # Install or update the SSH key on the VM. The method
1042 # authenticates with the stored root password. It runs to recover
1043 # from a failed first boot, or when the configured SSH key
1044 # changed.
1045 sub _complete_ssh_setup ($self)
1046 {
1047 my $state = $self->{state};
1048 my $config = $self->{config};
1049 my $log = $self->{log};
1050  
1051 my $root_password = $state->get_root_password;
1052 if ( !defined $root_password ) {
1053 $log->error(
1054 "No root password stored - cannot complete SSH setup");
1055 return EXIT_ERROR;
1056 }
1057  
1058 $log->info("Updating SSH key...");
1059  
1060 # Wait for SSH with password authentication
1061 $log->info("Waiting for SSH...");
1062 if ( !$self->wait_ssh( 120, $root_password ) ) {
1063 $log->error("Timeout waiting for SSH");
1064 return EXIT_TIMEOUT;
1065 }
1066  
1067 # Install the SSH authorized key
1068 if ( !$self->_install_ssh_key($root_password) ) {
1069 $log->error("Failed to install SSH key");
1070 return EXIT_ERROR;
1071 }
1072 $log->info("SSH key installed");
1073  
1074 $log->info("VM ready");
1075 return EXIT_SUCCESS;
1076 }
1077  
1078 # $self->_install_ssh_key($password):
1079 # Install the SSH public key from the configuration into
1080 # authorized_keys. The method uses password authentication,
1081 # because the key is not yet installed.
1082 sub _install_ssh_key ( $self, $password )
1083 {
1084 my $config = $self->{config};
1085 my $state = $self->{state};
1086 my $log = $self->{log};
1087  
1088 # Get the SSH public key from the configuration
1089 my $ssh_pubkey = $config->{ssh_pubkey};
1090 if ( !defined $ssh_pubkey || $ssh_pubkey eq '' ) {
1091 $log->error("No ssh_pubkey configured in ~/.fuguvmrc");
1092 return 0;
1093 }
1094  
1095 # Connect with the password
1096 my $ssh = Fugu::SSH->new(
1097 host => $self->connect_address,
1098 port => $self->ssh_port,
1099 user => 'root',
1100 password => $password,
1101 );
1102  
1103 # Create the .ssh directory
1104 my $result =
1105 $ssh->run_command('mkdir -p /root/.ssh && chmod 700 /root/.ssh');
1106 if ( $result->{exit_code} != 0 ) {
1107 return 0;
1108 }
1109  
1110 # Write the authorized_keys file
1111 my $authkeys_content = $ssh_pubkey . "\n";
1112 if (
1113 $ssh->write_file(
1114 '/root/.ssh/authorized_keys', $authkeys_content,
1115 0600
1116 ) != 0
1117 )
1118 {
1119 return 0;
1120 }
1121  
1122 # Store the installed pubkey for a future comparison
1123 $state->mark_ssh_key_installed($ssh_pubkey);
1124 return 1;
1125 }
1126  
1127 # Graceful shutdown with a filesystem sync: sync through SSH, then
1128 # power off through the ACPI power button, and report the result.
1129 sub _graceful_shutdown ($self)
1130 {
1131 my $log = $self->{log};
1132  
1133 # Do a best-effort filesystem sync over SSH before the code
1134 # pulls the power. The sync has a hard time bound. A wedged
1135 # guest must never stall the shutdown. Also, libssh2 does not
1136 # reliably obey its own timeout on the connect and handshake. A
1137 # failure or a timeout here is acceptable. The ACPI powerdown
1138 # below runs the orderly shutdown of the guest, which syncs. A
1139 # force stop is the ultimate fallback.
1140 $self->_bounded(
1141 Fugu::SSH::DEFAULT_TIMEOUT() + 5,
1142 sub {
1143 my $ssh = Fugu::SSH->new(
1144 host => $self->connect_address,
1145 port => $self->ssh_port,
1146 user => 'root',
1147 );
1148 return $ssh->run_command('sync; sync; sync');
1149 } );
1150  
1151 # Ask the guest to power off through the ACPI power button. Then
1152 # wait.
1153 if ( $self->_qmp_powerdown && $self->_wait_exit(60) ) {
1154 $log->info("Shutdown via ACPI powerdown");
1155 return 1;
1156 }
1157  
1158 return 0;
1159 }
1160  
1161 # $self->_bounded($seconds, $code):
1162 # Run $code under a hard wall-clock deadline, so a blocked guest
1163 # interaction cannot stall the caller. The guard itself is
1164 # Fugu::Timeout; this wrapper adds the log line.
1165 sub _bounded ( $self, $seconds, $code )
1166 {
1167 my $result = Fugu::Timeout::bounded( $seconds, $code );
1168 return $result if defined $result;
1169  
1170 $self->{log}->warning("Guest did not respond within ${seconds}s");
1171 return;
1172 }
1173  
1174 # $self->_ensure_proxy:
1175 # Start the caching proxy if it does not run, and return it. The
1176 # method returns undef when the proxy cannot start.
1177 #
1178 # The lifecycle lives here and not in App::FuguVM::State, because a
1179 # state file must not start a process. That split is what removed
1180 # the require cycle between the two modules.
1181 sub _ensure_proxy ($self)
1182 {
1183 my $proxy = $self->_proxy;
1184 return $proxy if $proxy->is_running;
1185  
1186 # The spawn passes a fixed argument list, so the distfile cap
1187 # reaches the child through the environment.
1188 $ENV{FUGUVM_DISTFILE_LIMIT} = $self->{config}{distfile_cache} // 0;
1189  
1190 unless ( defined $proxy->start ) {
1191 $self->{log}->warning(
1192 'Proxy did not start: %s',
1193 $proxy->error // 'unknown'
1194 );
1195 return;
1196 }
1197  
1198 return $proxy;
1199 }
1200  
1201 # $self->_stop_proxy:
1202 # Stop the proxy if it runs. The method returns 1 when it stopped
1203 # one, and 0 when there was none.
1204 sub _stop_proxy ($self)
1205 {
1206 my $proxy = $self->_proxy;
1207 return 0 unless $proxy->is_running;
1208  
1209 $proxy->stop;
1210  
1211 return 1;
1212 }
1213  
1214 # $self->_proxy:
1215 # Build the proxy supervisor over this VM's state.
1216 sub _proxy ($self)
1217 {
1218 my $state = $self->{state};
1219  
1220 return App::FuguVM::Proxy->new(
1221 cache => App::FuguVM::Proxy::Cache->new(
1222 $self->_cache_dir, $self->{config}{distfile_cache} // 0
1223 ),
1224 pidfile => $state->proxy_pidfile,
1225 store => $state->store,
1226 logfile => $state->vm_state_dir . '/proxy.log',
1227 log => $self->{log},
1228 );
1229 }
1230  
1231 # $self->_autoinstall($proxy_url):
1232 # Build the responder supervisor over this VM's state and the
1233 # guest URL of the mirror proxy.
1234 sub _autoinstall ( $self, $proxy_url = undef )
1235 {
1236 my $state = $self->{state};
1237  
1238 return App::FuguVM::Autoinstall->new(
1239 file => $self->{config}{autoinstall},
1240 pidfile => $state->autoinstall_pidfile,
1241 store => $state->store,
1242 proxy_url => $proxy_url,
1243 logfile => $state->vm_state_dir . '/autoinstall.log',
1244 log => $self->{log},
1245 );
1246 }
1247  
1248 # $self->_stop_autoinstall:
1249 # Stop the responder if it runs. The method returns 1 when it
1250 # stopped one, and 0 when there was none. It follows _stop_proxy.
1251 sub _stop_autoinstall ($self)
1252 {
1253 my $responder = $self->_autoinstall;
1254 return 0 unless $responder->is_running;
1255  
1256 $responder->stop;
1257  
1258 return 1;
1259 }
1260  
1261 # $self->_force_stop:
1262 # Stop the QEMU process deterministically. Send SIGTERM first:
1263 # QEMU exits and flushes its disk caches. Escalate to SIGKILL if
1264 # the process stays. Unlike a QMP 'quit', this method cannot hang
1265 # on an unresponsive monitor socket. Thus it is a safe last
1266 # resort.
1267 sub _force_stop ($self)
1268 {
1269 my $pid = $self->{state}->get_vm_pid;
1270 return 1 if !defined $pid;
1271 return Fugu::Process->terminate( $pid, grace_period => 5 );
1272 }
1273  
1274 # QMP methods
1275 sub _qmp_socket_path ($self)
1276 {
1277 return $self->{state}{vm_state_dir} . '/qmp.sock';
1278 }
1279  
1280 sub _qmp_connect ($self)
1281 {
1282 my $qmp = App::FuguVM::QMP->new( $self->_qmp_socket_path );
1283 return $qmp->open_connection ? $qmp : undef;
1284 }
1285  
1286 sub _qmp_powerdown ($self)
1287 {
1288 my $qmp = $self->_qmp_connect or return 0;
1289 my $result = $qmp->powerdown;
1290 $qmp->disconnect;
1291 return $result;
1292 }
1293  
1294 sub _qmp_quit ($self)
1295 {
1296 my $qmp = $self->_qmp_connect or return 0;
1297 return $qmp->quit;
1298 }
1299  
1300 sub _is_running ($self)
1301 {
1302 my $pid = $self->{state}->get_vm_pid;
1303 return 0 if !defined $pid;
1304  
1305 # A QEMU that became a zombie is not running. Fugu::Process
1306 # reaps it and says so; a bare kill(0) would call it alive.
1307 return Fugu::Process->is_alive($pid) ? 1 : 0;
1308 }
1309  
1310 # $self->_wait_exit($timeout):
1311 # Wait for the QEMU process to leave. The poll is sub-second, so
1312 # a VM that stops at once does not cost a whole second.
1313 sub _wait_exit ( $self, $timeout )
1314 {
1315 my $pid = $self->{state}->get_vm_pid;
1316 return 1 if !defined $pid;
1317  
1318 return Fugu::Process->wait_exit( $pid, $timeout );
1319 }
1320  
1321 # QEMU startup
1322 sub _start_qemu ( $self, $boot_image = undef )
1323 {
1324 my $config = $self->{config};
1325 my $state = $self->{state};
1326 my $arch = $self->_arch;
1327  
1328 my @cmd = ( $arch->qemu_binary );
1329  
1330 # Set the machine type of the architecture. Select the
1331 # accelerator by the host capability.
1332 push @cmd, '-M', $arch->machine;
1333 push @cmd, $self->_accel_args;
1334  
1335 # Memory and CPU
1336 push @cmd, '-m', $config->{memory} // MEMORY_DEFAULT;
1337 push @cmd, '-smp', CPU_COUNT;
1338  
1339 # EFI firmware of the architecture. Both machines boot through
1340 # EFI, so a start without a firmware file cannot work. Fail
1341 # with a message rather than boot into the wrong firmware.
1342 my $firmware = $self->_find_efi_firmware;
1343 if ( !defined $firmware ) {
1344 $self->{log}->error(
1345 sprintf( "No EFI firmware for %s guests found",
1346 $self->_arch->name ) );
1347 return;
1348 }
1349 my @args = $self->_firmware_args($firmware);
1350 return unless @args;
1351 push @cmd, @args;
1352  
1353 # The main disk with the safe cache mode. The writethrough mode
1354 # syncs on each write.
1355 my $disk_path = $state->disk_path;
1356 push @cmd, '-drive',
1357 "file=$disk_path,format=qcow2,if=virtio,cache=writethrough";
1358  
1359 # Boot image (CD-ROM) for installation
1360 push @cmd, $self->_media_args($boot_image);
1361  
1362 # Network with port forwarding, and the serial console on
1363 # telnet
1364 my $console_port = $state->get_runtime->{console_port};
1365 push @cmd, $self->_network_args;
1366 push @cmd, $self->_serial_args;
1367  
1368 # QMP control socket
1369 my $qmp_path = $self->_qmp_socket_path;
1370 unlink $qmp_path if -S $qmp_path;
1371 push @cmd, '-qmp', "unix:$qmp_path,server,nowait";
1372  
1373 # PID file for reliable tracking
1374 push @cmd, '-pidfile', $state->vm_pidfile->path;
1375  
1376 # No graphics display (headless)
1377 push @cmd, '-display', 'none';
1378  
1379 # Use Fugu::Process to spawn QEMU
1380 my $log_file = $state->vm_state_dir . '/qemu.log';
1381 my $result = Fugu::Process->spawn_command(
1382 cmd => \@cmd,
1383 daemonize => 1,
1384 stdout => $log_file,
1385 stderr => $log_file,
1386 );
1387  
1388 return unless $result->{success};
1389  
1390 # Wait until QEMU writes the PID file
1391 my $pid = Fugu::Timeout::wait_until(
1392 5, 0.1,
1393 sub {
1394 my $qemu_pid = $state->get_vm_pid;
1395 return $qemu_pid
1396 if defined $qemu_pid
1397 && Fugu::Process->is_alive($qemu_pid);
1398 return;
1399 } );
1400  
1401 unless ( defined $pid ) {
1402 $self->_dump_qemu_log($log_file);
1403 return;
1404 }
1405  
1406 # Arm the crash detection: was_unclean_shutdown reports true
1407 # when the state says running and the process is gone.
1408 $state->mark_running;
1409  
1410 # Make sure that QEMU accepts console connections before the
1411 # installer tries to attach. A QEMU that exited at startup, for
1412 # example with a bad accelerator or missing firmware, leaves the
1413 # port closed. This check fails fast with the QEMU log, not with
1414 # a long telnet timeout later.
1415 if ( defined $boot_image
1416 && !$self->_wait_console_ready( $console_port, 30 ) )
1417 {
1418 $self->{log}
1419 ->error( 'QEMU console port %d not listening after start',
1420 $console_port );
1421 $self->_dump_qemu_log($log_file);
1422 return;
1423 }
1424  
1425 return $pid;
1426 }
1427  
1428 # $self->_media_args($boot_image):
1429 # Return the QEMU arguments of the install media, or an empty
1430 # list when no media is attached. An autoinstall reboots
1431 # itself, and the miniroot is still attached. -no-reboot makes
1432 # the reboot an exit, so the guest cannot install a second
1433 # time.
1434 sub _media_args ( $self, $boot_image = undef )
1435 {
1436 return () if !defined $boot_image;
1437  
1438 my @args =
1439 ( '-drive', "file=$boot_image,format=raw,if=virtio,readonly=on" );
1440 push @args, '-no-reboot'
1441 if ( $self->{config}{install_mode} // '' ) eq 'autoinstall';
1442  
1443 return @args;
1444 }
1445  
1446 # $self->_network_args:
1447 # Return the QEMU network arguments. The ports come from the
1448 # record that _resolve_ports wrote before the spawn: the public
1449 # accessors serve a running guest only, and QEMU does not run
1450 # yet. The forwarded port binds to the configured host address,
1451 # and the default is loopback.
1452 sub _network_args ($self)
1453 {
1454 my $bind_address = $self->bind_address;
1455 my $ssh_port = $self->{state}->get_runtime->{ssh_port};
1456  
1457 return ( '-device', 'virtio-net-pci,netdev=net0', '-netdev',
1458 "user,id=net0,hostfwd=tcp:$bind_address:" . "$ssh_port-:22",
1459 );
1460 }
1461  
1462 # $self->_serial_args:
1463 # Return the QEMU serial-console arguments: a telnet listener on
1464 # the bind address and the recorded console port.
1465 sub _serial_args ($self)
1466 {
1467 my $bind_address = $self->bind_address;
1468 my $console_port = $self->{state}->get_runtime->{console_port};
1469  
1470 return ( '-serial',
1471 "tcp:$bind_address:$console_port,server,telnet,nowait" );
1472 }
1473  
1474 # $self->_wait_console_ready($port, $timeout):
1475 # Poll the console TCP port until it accepts a connection. Thus
1476 # the telnet of the installer attaches to a live console. QEMU
1477 # binds the port at startup, before the guest boots. Thus the
1478 # poll is quick when QEMU is healthy, and bounded when it is not.
1479 sub _wait_console_ready ( $self, $port, $timeout )
1480 {
1481 require IO::Socket::INET;
1482  
1483 my $ready = Fugu::Timeout::wait_until(
1484 $timeout, 0.2,
1485 sub {
1486 my $sock = IO::Socket::INET->new(
1487 PeerAddr => $self->connect_address,
1488 PeerPort => $port,
1489 Proto => 'tcp',
1490 Timeout => 2,
1491 );
1492 if ( defined $sock ) {
1493 $sock->close;
1494 return 'ready';
1495 }
1496  
1497 # Stop the wait early if QEMU already exited
1498 my $qemu_pid = $self->{state}->get_vm_pid;
1499 return 'gone'
1500 if defined $qemu_pid
1501 && !Fugu::Process->is_alive($qemu_pid);
1502  
1503 return;
1504 } );
1505  
1506 return defined $ready && $ready eq 'ready' ? 1 : 0;
1507 }
1508  
1509 # $self->_dump_qemu_log($log_file):
1510 # Show the tail of the QEMU log. Thus a startup failure is
1511 # visible in the CI output, and shell access to the runner is not
1512 # necessary.
1513 sub _dump_qemu_log ( $self, $log_file )
1514 {
1515 open my $fh, '<', $log_file or return;
1516 my @lines = <$fh>;
1517 close $fh;
1518  
1519 @lines = splice( @lines, -40 ) if @lines > 40;
1520 $self->{log}->error('QEMU log tail:');
1521 $self->{log}->error( ' %s', $_ ) for map { chomp; $_ } @lines;
1522  
1523 return;
1524 }
1525  
1526 # $self->_accel_args():
1527 # Return the accelerator arguments, with the matching CPU model.
1528 # Host CPU passthrough is only valid with hardware acceleration.
1529 # TCG needs the named model of the architecture. The choice
1530 # itself comes from accel.
1531 sub _accel_args ($self)
1532 {
1533 my $arch = $self->_arch;
1534 my $accel = $self->accel;
1535  
1536 $self->{log}->debug("Using QEMU accelerator: $accel")
1537 if $self->{log};
1538  
1539 return ( '-accel', $accel,
1540 '-cpu', $accel eq 'tcg' ? $arch->tcg_cpu : 'host' );
1541 }
1542  
1543 # $self->_arch:
1544 # Return the App::FuguVM::Arch object of the configured value,
1545 # and cache it. The configuration loader is the boundary of the
1546 # directive, so an unknown value here is a programming error.
1547 sub _arch ($self)
1548 {
1549 my $name = $self->{config}{arch};
1550  
1551 $self->{arch} //= App::FuguVM::Arch->new($name)
1552 // die 'unknown architecture: ' . ( $name // '(none)' ) . "\n";
1553  
1554 return $self->{arch};
1555 }
1556  
1557 # $self->_qemu_path:
1558 # Return the path of the QEMU binary of the architecture on
1559 # PATH, or undef.
1560 sub _qemu_path ($self)
1561 {
1562 my $binary = $self->_arch->qemu_binary;
1563  
1564 for my $dir ( split /:/, $ENV{PATH} // '' ) {
1565 next if $dir eq '';
1566 my $path = "$dir/$binary";
1567 return $path if -f $path && -x $path;
1568 }
1569  
1570 return;
1571 }
1572  
1573 # $self->_require_qemu:
1574 # Diagnose an absent QEMU binary, once for up and start. The
1575 # message names the binary and the architecture.
1576 sub _require_qemu ($self)
1577 {
1578 return 1 if defined $self->_qemu_path;
1579  
1580 my $arch = $self->_arch;
1581 $self->{log}->error(
1582 sprintf(
1583 "QEMU binary '%s' for %s guests is not on PATH",
1584 $arch->qemu_binary, $arch->name
1585 ) );
1586  
1587 return 0;
1588 }
1589  
1590 # $self->_check_qemu_version:
1591 # Enforce the optional qemu_version directive, once for up and
1592 # start. Return undef when the check passes, and when no
1593 # directive exists. Return EXIT_CONFIG_ERROR otherwise. A pinned
1594 # version that the tool cannot verify fails closed: an absent
1595 # binary, and output with no version in it, both refuse the
1596 # start. The match runs component by component, over the
1597 # components that the directive names: 9.0 accepts 9.0.4 and
1598 # refuses 9.1.0.
1599 sub _check_qemu_version ($self)
1600 {
1601 my $pinned = $self->{config}{qemu_version};
1602 return if !defined $pinned;
1603  
1604 my $reported = $self->_qemu_version;
1605 if ( !defined $reported ) {
1606 $self->{log}->error(
1607 "Cannot read the QEMU version to check against the pinned $pinned"
1608 );
1609 return EXIT_CONFIG_ERROR;
1610 }
1611  
1612 my @want = split /\./, $pinned;
1613 my @have = split /\./, $reported;
1614 for my $i ( 0 .. $#want ) {
1615 next if defined $have[$i] && $have[$i] == $want[$i];
1616  
1617 $self->{log}->error(
1618 "QEMU version $reported does not match the pinned $pinned"
1619 );
1620 return EXIT_CONFIG_ERROR;
1621 }
1622  
1623 return;
1624 }
1625  
1626 # $self->_qemu_version:
1627 # Return the version that the QEMU binary reports, or undef. The
1628 # version is the first dotted-decimal token of the first output
1629 # line.
1630 sub _qemu_version ($self)
1631 {
1632 my $binary = $self->_qemu_path;
1633 return if !defined $binary;
1634  
1635 my $result = Fugu::Process->run(
1636 cmd => [ $binary, '--version' ],
1637 timeout => QEMU_VERSION_TIMEOUT,
1638 );
1639 return if !$result->{success};
1640  
1641 my ($line) = split /\n/, $result->{stdout} // '';
1642 return if !defined $line;
1643  
1644 my ($version) = $line =~ /([0-9]+(?:\.[0-9]+)+)/;
1645  
1646 return $version;
1647 }
1648  
1649 # $self->_resolve_ports:
1650 # Resolve both host ports, and record them with the selected
1651 # accelerator, before the tool spawns QEMU. A number resolves to
1652 # itself, and 'auto' takes a free port of the fixed range of its
1653 # directive. Return undef on success, and EXIT_ERROR when a range
1654 # is exhausted.
1655 #
1656 # The port lock closes the window between the probe and the
1657 # record. One window stays open: a foreign process can take a
1658 # probed port before QEMU binds it. QEMU then fails to start, and
1659 # the tool reports that failure with the QEMU log.
1660 sub _resolve_ports ($self)
1661 {
1662 my $config = $self->{config};
1663  
1664 my %range = (
1665 ssh_port => App::FuguVM::Config::DEFAULT_SSH_PORT(),
1666 console_port => App::FuguVM::Config::DEFAULT_CONSOLE_PORT(),
1667 );
1668  
1669 my $lock = $self->_lock_ports;
1670 my $taken = $self->_taken_ports;
1671  
1672 # The fixed ports of every VM declaration of the project are
1673 # taken too, whether the declared guest runs now or not. The
1674 # loader injects the set, like cache_dir.
1675 %$taken = ( %$taken, %{ $config->{declared_ports} // {} } );
1676  
1677 # The fixed ports of this guest are taken too: a probe for one
1678 # directive must not select the number that the other directive
1679 # holds.
1680 for my $directive (qw(ssh_port console_port)) {
1681 my $configured = $config->{$directive};
1682 $taken->{$configured} = 1
1683 if defined $configured
1684 && $configured ne App::FuguVM::Config::AUTO_PORT();
1685 }
1686  
1687 my %resolved;
1688 for my $directive (qw(ssh_port console_port)) {
1689 my $configured = $config->{$directive};
1690  
1691 if ( defined $configured
1692 && $configured eq App::FuguVM::Config::AUTO_PORT() )
1693 {
1694 my $first = $range{$directive};
1695 my $last =
1696 $first + App::FuguVM::Config::AUTO_PORT_COUNT() - 1;
1697  
1698 my $port = $self->_free_port( $first, $last, $taken );
1699 if ( !defined $port ) {
1700 $self->{log}->error(
1701 "No free $directive in the range $first-$last"
1702 );
1703 close $lock if defined $lock;
1704 return EXIT_ERROR;
1705 }
1706 $resolved{$directive} = $port;
1707 }
1708 else {
1709 $resolved{$directive} = $configured;
1710 }
1711  
1712 $taken->{ $resolved{$directive} } = 1
1713 if defined $resolved{$directive};
1714 }
1715  
1716 $self->{state}->set_runtime( accel => $self->accel, %resolved );
1717 close $lock if defined $lock;
1718  
1719 return;
1720 }
1721  
1722 # $self->_free_port($first, $last, $taken):
1723 # Return the first port of the range that binds on the bind
1724 # address and that $taken does not hold. Return undef for an
1725 # exhausted range.
1726 sub _free_port ( $self, $first, $last, $taken )
1727 {
1728 require IO::Socket::INET;
1729  
1730 for my $port ( $first .. $last ) {
1731 next if $taken->{$port};
1732  
1733 my $sock = IO::Socket::INET->new(
1734 LocalAddr => $self->bind_address,
1735 LocalPort => $port,
1736 Proto => 'tcp',
1737 Listen => 1,
1738 );
1739 next if !defined $sock;
1740  
1741 $sock->close;
1742 return $port;
1743 }
1744  
1745 return;
1746 }
1747  
1748 # $self->_taken_ports:
1749 # Return the recorded ports of every guest of the project, as a
1750 # hash reference keyed by port. The method enumerates the state
1751 # directory, like App::FuguVM::CLI::_disks_backed_by: a record
1752 # counts whether a 'vm' block still declares its guest or not.
1753 sub _taken_ports ($self)
1754 {
1755 my %taken;
1756  
1757 my $state_dir = $self->{state}->state_dir;
1758 return \%taken if !-d $state_dir;
1759  
1760 opendir my $dh, $state_dir or return \%taken;
1761 my @names = sort grep { !/^\./ && -d "$state_dir/$_" } readdir $dh;
1762 closedir $dh;
1763  
1764 for my $name (@names) {
1765 my $sibling = App::FuguVM::State->new( $state_dir, $name )
1766 or next;
1767 my $runtime = $sibling->get_runtime;
1768 for my $directive (qw(ssh_port console_port)) {
1769 my $port = $runtime->{$directive};
1770 $taken{$port} = 1 if defined $port;
1771 }
1772 }
1773  
1774 return \%taken;
1775 }
1776  
1777 # $self->_lock_ports:
1778 # Return the locked handle of ports.lock, or undef on the
1779 # deadline. The lock file lives in the cache directory, so every
1780 # project that shares that directory probes one port at a time.
1781 # The record exclusion of _taken_ports covers this project only.
1782 # A collision with an other project surfaces when QEMU binds the
1783 # port, as a reported startup failure. The caller probes without
1784 # the lock when the deadline elapses: a wedged holder must not
1785 # fail a run.
1786 sub _lock_ports ($self)
1787 {
1788 my $dir = $self->_cache_dir;
1789 Fugu::File->ensure_dir($dir) or return;
1790  
1791 my $path = "$dir/ports.lock";
1792 open my $fh, '>>', $path or do {
1793 $self->{log}->warning("Cannot open $path: $!");
1794 return;
1795 };
1796  
1797 my $locked = Fugu::Timeout::bounded( PORT_LOCK_TIMEOUT,
1798 sub { flock $fh, LOCK_EX } );
1799 return $fh if $locked;
1800  
1801 close $fh;
1802 $self->{log}->warning("Port lock not acquired, probing without it");
1803  
1804 return;
1805 }
1806  
1807 # $self->_check_installed_arch:
1808 # Report if the configured architecture matches the installed
1809 # disk, once for up and start. A disk belongs to one
1810 # architecture, so a changed directive must not start the wrong
1811 # QEMU on an existing disk. An absent record cannot prove a
1812 # difference, so the check passes.
1813 sub _check_installed_arch ($self)
1814 {
1815 my $config = $self->{config};
1816  
1817 my $installed = $self->{state}->get_installed_arch;
1818 return 1 if !defined $installed || $installed eq $config->{arch};
1819  
1820 $self->{log}->error(
1821 "The disk of '$config->{name}' holds an $installed installation, not $config->{arch}"
1822 );
1823 $self->{log}->error("Run 'fuguvm destroy' to rebuild the VM.");
1824  
1825 return 0;
1826 }
1827  
1828 # _host_arch():
1829 # Return the host machine architecture from uname.
1830 sub _host_arch ()
1831 {
1832 require POSIX;
1833 my @uname = POSIX::uname();
1834 return $uname[4] // '';
1835 }
1836  
1837 # $self->_find_efi_firmware:
1838 # Return the firmware of the architecture as { code, vars }, or
1839 # undef. The vars entry is the variable-store template beside
1840 # the code file. It is undef when -bios boots the code file
1841 # alone. A code file without its template is not usable, so the
1842 # search walks on.
1843 sub _find_efi_firmware ($self)
1844 {
1845 my $arch = $self->_arch;
1846  
1847 my @candidates = $arch->firmware_paths;
1848 push @candidates, glob( $arch->firmware_glob );
1849  
1850 for my $code (@candidates) {
1851 next unless -f $code;
1852  
1853 my $vars = $arch->firmware_vars_path($code);
1854 next if defined $vars && !-f $vars;
1855  
1856 return { code => $code, vars => $vars };
1857 }
1858  
1859 return;
1860 }
1861  
1862 # $self->_firmware_args($firmware):
1863 # Return the QEMU arguments for the firmware, or an empty list
1864 # on failure. A code file without a variable store boots with
1865 # -bios. A code file with one boots through two pflash devices:
1866 # the code read-only, and a fresh copy of the variable-store
1867 # template. The copy is throwaway state, so every start makes it
1868 # again.
1869 sub _firmware_args ( $self, $firmware )
1870 {
1871 my $code = $firmware->{code};
1872 my $vars = $firmware->{vars};
1873  
1874 return ( '-bios', $code ) if !defined $vars;
1875  
1876 my $copy = $self->{state}->vm_state_dir . '/efivars.fd';
1877 require File::Copy;
1878 unless ( File::Copy::copy( $vars, $copy ) ) {
1879 $self->{log}->error("Cannot copy $vars to $copy: $!");
1880 return;
1881 }
1882  
1883 return (
1884 '-drive', "if=pflash,format=raw,readonly=on,file=$code",
1885 '-drive', "if=pflash,format=raw,file=$copy",
1886 );
1887 }
1888  
1889 # $self->_cache_dir:
1890 # Return the configured cache directory. App::FuguVM::Config::load_vm
1891 # injects it into the per-VM config. The fallback only serves VM
1892 # objects built without a configuration.
1893 sub _cache_dir ($self)
1894 {
1895 my $configured = $self->{config}{cache_dir};
1896 return $configured if defined $configured && $configured ne '';
1897  
1898 my $home = $ENV{HOME} // '/root';
1899 return "$home/.cache/fuguvm";
1900 }
1901  
1902 1;