.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.52.0 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "guestfs-release-notes-1.26 1"
.TH guestfs-release-notes-1.26 1 2024-01-05 libguestfs-1.52.0 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
guestfs\-release\-notes \- libguestfs Release Notes
.SH "RELEASE NOTES FOR LIBGUESTFS 1.26"
.IX Header "RELEASE NOTES FOR LIBGUESTFS 1.26"
These release notes only cover the differences from the previous
stable/dev branch split (1.24.0).  For detailed changelogs, please see
the git repository, or the ChangeLog file distributed in the tarball.
.SS "New features"
.IX Subsection "New features"
\fITools\fR
.IX Subsection "Tools"
.PP
\&\fBvirt\-customize\fR\|(1) is a new tool for customizing virtual machine
disk images.  It lets you install packages, edit configuration files,
run scripts, set passwords and so on.  \fBvirt\-builder\fR\|(1) and
\&\fBvirt\-sysprep\fR\|(1) use virt-customize, and command line options across
all these tools are now identical.
.PP
\&\fBvirt\-diff\fR\|(1) is a new tool for showing the differences between the
filesystems of two virtual machines.  It is mainly useful when showing
what files have been changed between snapshots.
.PP
\&\fBvirt\-builder\fR\|(1) has been greatly enhanced.  There are many more
ways to customize the virtual machine.  It can pull templates from
multiple repositories.  A parallelized internal xzcat implementation
speeds up template decompression.  Virt-builder uses an optimizing
planner to choose the fastest way to build the VM.  It is now easier
to use virt-builder from other programs.  Internationalization support
has been added to metadata.  More efficient SELinux relabelling of
files.  Can build guests for multiple architectures.  Error messages
have been improved.
(Pino Toscano)
.PP
\&\fBvirt\-sparsify\fR\|(1) has a new \fI\-\-in\-place\fR option.  This sparsifies
an image in place (without copying it) and is also much faster.
(Lots of help provided by Paolo Bonzini)
.PP
\&\fBvirt\-sysprep\fR\|(1) can delete and scrub files under user control.  You
can lock user accounts or set random passwords on accounts.  Can
remove more log files.  Can unsubscribe a guest from Red Hat
Subscription Manager.  New flexible way to enable and disable
operations.
(Wanlong Gao, Pino Toscano)
.PP
\&\fBvirt\-win\-reg\fR\|(1) allows you to use URIs to specify remote disk
images.
.PP
\&\fBvirt\-format\fR\|(1) can now pass the extra space that it recovers back
to the host.
.PP
\&\fBguestfish\fR\|(1) has additional environment variables to give fine
control over the \f(CW\*(C`><fs>\*(C'\fR prompt.  Guestfish reads its
(rarely used) configuration file in a different order now so that
local settings override global settings.
(Pino Toscano)
.PP
\&\fBvirt\-make\-fs\fR\|(1) was rewritten in C, but is unchanged in terms of
functionality and command line usage.
.PP
\fILanguage bindings\fR
.IX Subsection "Language bindings"
.PP
The OCaml bindings have a new \f(CW\*(C`Guestfs.Errno\*(C'\fR module, used to check
the error number returned by \f(CW\*(C`Guestfs.last_errno\*(C'\fR.
.PP
PHP tests now work.
(Pino Toscano)
.PP
\fIInspection\fR
.IX Subsection "Inspection"
.PP
Inspection can recognize Debian live images.
.PP
\fIArchitectures\fR
.IX Subsection "Architectures"
.PP
ARMv7 (32 bit) now supports KVM acceleration.
.PP
Aarch64 (ARM 64 bit) is supported, but the appliance part does not
work yet.
.PP
PPC64 support has been fixed and enhanced.
.SS Security
.IX Subsection "Security"
.IP "Denial of service when inspecting disk images with corrupt btrfs volumes" 4
.IX Item "Denial of service when inspecting disk images with corrupt btrfs volumes"
It was possible to crash libguestfs (and programs that use libguestfs
as a library) by presenting a disk image containing a corrupt btrfs
volume.
.Sp
This was caused by a NULL pointer dereference causing a denial of
service, and is not thought to be exploitable any further.
.Sp
See commit d70ceb4cbea165c960710576efac5a5716055486 for the fix.  This
fix is included in libguestfs stable branches ≥\ 1.26.0, ≥\ 1.24.6 and ≥\ 1.22.8, and also in RHEL ≥\ 7.0.
Earlier versions of libguestfs are not vulnerable.
.IP "Better generation of random root passwords and random seeds" 4
.IX Item "Better generation of random root passwords and random seeds"
When generating random root passwords and random seeds, two bugs were
fixed which are possibly security related.  Firstly we no longer read
excessive bytes from \fI/dev/urandom\fR (most of which were just thrown
away).  Secondly we changed the code to avoid modulo bias.  These
issues were not thought to be exploitable.
(Both changes suggested by Edwin Török)
.SS API
.IX Subsection "API"
GUID parameters are now validated when they are passed to API calls,
whereas previously you could have passed any string.
(Pino Toscano)
.PP
\fINew APIs\fR
.IX Subsection "New APIs"
.ie n .IP """guestfs_add_drive_opts"": new ""discard"" parameter" 4
.el .IP "\f(CWguestfs_add_drive_opts\fR: new \f(CWdiscard\fR parameter" 4
.IX Item "guestfs_add_drive_opts: new discard parameter"
The new \f(CW\*(C`discard\*(C'\fR parameter allows fine-grained control over
discard/trim support for a particular disk.  This allows the host file
to become more sparse (or thin-provisioned) when you delete files or
issue the \f(CW\*(C`guestfs_fstrim\*(C'\fR API call.
.ie n .IP """guestfs_add_domain"": new parameters: ""cachemode"", ""discard""" 4
.el .IP "\f(CWguestfs_add_domain\fR: new parameters: \f(CWcachemode\fR, \f(CWdiscard\fR" 4
.IX Item "guestfs_add_domain: new parameters: cachemode, discard"
These parameters are passed through when adding the domain's disks.
.ie n .IP """guestfs_blkdiscard""" 4
.el .IP \f(CWguestfs_blkdiscard\fR 4
.IX Item "guestfs_blkdiscard"
Discard all blocks on a guestfs device.  Combined with the \f(CW\*(C`discard\*(C'\fR
parameter above, this makes the host file sparse.
.ie n .IP """guestfs_blkdiscardzeroes""" 4
.el .IP \f(CWguestfs_blkdiscardzeroes\fR 4
.IX Item "guestfs_blkdiscardzeroes"
Test if discarded blocks read back as zeroes.
.ie n .IP """guestfs_compare_*""" 4
.el .IP \f(CWguestfs_compare_*\fR 4
.IX Item "guestfs_compare_*"
.PD 0
.ie n .IP """guestfs_copy_*""" 4
.el .IP \f(CWguestfs_copy_*\fR 4
.IX Item "guestfs_copy_*"
.PD
For each struct returned through the API, libguestfs now generates
\&\f(CW\*(C`guestfs_compare_*\*(C'\fR and \f(CW\*(C`guestfs_copy_*\*(C'\fR functions to allow you to
compare and copy structs.
.ie n .IP """guestfs_copy_attributes""" 4
.el .IP \f(CWguestfs_copy_attributes\fR 4
.IX Item "guestfs_copy_attributes"
Copy attributes (like permissions, xattrs, ownership) from one
file to another.
(Pino Toscano)
.ie n .IP """guestfs_disk_create""" 4
.el .IP \f(CWguestfs_disk_create\fR 4
.IX Item "guestfs_disk_create"
A flexible API for creating empty disk images from scratch.  This
avoids the need to call out to external programs like \fBqemu\-img\fR\|(1).
.ie n .IP """guestfs_get_backend_settings""" 4
.el .IP \f(CWguestfs_get_backend_settings\fR 4
.IX Item "guestfs_get_backend_settings"
.PD 0
.ie n .IP """guestfs_set_backend_settings""" 4
.el .IP \f(CWguestfs_set_backend_settings\fR 4
.IX Item "guestfs_set_backend_settings"
.PD
Per-backend settings (can also be set via the environment variable
\&\f(CW\*(C`LIBGUESTFS_BACKEND_SETTINGS\*(C'\fR).  The main use for this is forcing TCG
mode in the qemu-based backends, for example:
.Sp
.Vb 2
\& export LIBGUESTFS_BACKEND=direct
\& export LIBGUESTFS_BACKEND_SETTINGS=force_tcg
.Ve
.ie n .IP """guestfs_part_get_name""" 4
.el .IP \f(CWguestfs_part_get_name\fR 4
.IX Item "guestfs_part_get_name"
Get the label or name of a partition (for GPT disk images).
.SS "Build changes"
.IX Subsection "Build changes"
The following extra packages are required to build libguestfs 1.26:
.IP "supermin ≥ 5" 4
.IX Item "supermin ≥ 5"
Supermin version 5 is required to build this version of libguestfs.
.IP "flex, bison" 4
.IX Item "flex, bison"
Virt-builder now uses a real parser to parse its metadata file, so
these tools are required.
.IP xz 4
.IX Item "xz"
This is now a required build dependency, where previously it was
(in theory) optional.
.SS Internals
.IX Subsection "Internals"
PO message extraction rewritten to be more robust.
(Pino Toscano)
.PP
\&\f(CW\*(C`podwrapper\*(C'\fR gives an error if the \fI\-\-insert\fR or \fI\-\-verbatim\fR
argument pattern is not found.
.PP
Libguestfs now passes the qemu \fI\-enable\-fips\fR option to enable FIPS,
if qemu supports it.
.PP
\&\f(CW\*(C`./configure \-\-without\-qemu\*(C'\fR can be used if you don't want to specify
a default hypervisor.
.PP
Copy-on-write [COW] overlays, used for example for read-only drives,
are now created through an internal backend API (\f(CW\*(C`.create_cow_overlay\*(C'\fR).
.PP
Libvirt backend uses some funky C macros to generate XML.  These are
simpler and safer.
.PP
The ChangeLog file format has changed.  It is now just the same as
\&\f(CW\*(C`git log\*(C'\fR, instead of using a custom format.
.PP
Appliance start-up has changed:
.IP \(bu 4
The libguestfs appliance now initializes LVM the same way as it is
done on physical machines.
.IP \(bu 4
The libguestfs appliance does not write an empty string to
\&\fI/proc/sys/kernel/hotplug\fR when starting up.
.Sp
Note that you \fBmust\fR configure your kernel to have
\&\f(CW\*(C`CONFIG_UEVENT_HELPER_PATH=""\*(C'\fR otherwise you will get strange LVM
errors (this applies as much to any Linux machine, not just
libguestfs).
(Peter Rajnoha)
.PP
Libguestfs can now be built on arches that have \fBocamlc\fR\|(1) but not
\&\fBocamlopt\fR\|(1).
(Hilko Bengen, Olaf Hering)
.PP
You cannot use \f(CW\*(C`./configure \-\-disable\-daemon \-\-enable\-appliance\*(C'\fR.  It
made no sense anyway.  Now it is expressly forbidden by the configure
script.
.PP
The packagelist file uses \f(CW\*(C`m4\*(C'\fR for macro expansion instead of \f(CW\*(C`cpp\*(C'\fR.
.SS "Bugs fixed"
.IX Subsection "Bugs fixed"
.IP https://bugzilla.redhat.com/1073906 4
.IX Item "https://bugzilla.redhat.com/1073906"
java bindings inspect_list_applications2 throws java.lang.ArrayIndexOutOfBoundsException:
.IP https://bugzilla.redhat.com/1063374 4
.IX Item "https://bugzilla.redhat.com/1063374"
[RFE] enable subscription manager clean or unregister operation to sysprep
.IP https://bugzilla.redhat.com/1060404 4
.IX Item "https://bugzilla.redhat.com/1060404"
virt-resize does not preserve GPT partition names
.IP https://bugzilla.redhat.com/1057504 4
.IX Item "https://bugzilla.redhat.com/1057504"
mount-local should give a clearer error if root is not mounted
.IP https://bugzilla.redhat.com/1056290 4
.IX Item "https://bugzilla.redhat.com/1056290"
virt-sparsify overwrites block devices if used as output files
.IP https://bugzilla.redhat.com/1055452 4
.IX Item "https://bugzilla.redhat.com/1055452"
libguestfs: error: invalid backend: appliance
.IP https://bugzilla.redhat.com/1054761 4
.IX Item "https://bugzilla.redhat.com/1054761"
guestfs_pvs prints "unknown device" if a physical volume is missing
.IP https://bugzilla.redhat.com/1053847 4
.IX Item "https://bugzilla.redhat.com/1053847"
Recommended default clock/timer settings
.IP https://bugzilla.redhat.com/1046509 4
.IX Item "https://bugzilla.redhat.com/1046509"
ruby-libguestfs throws "expecting 0 or 1 arguments" on Guestfs::Guestfs.new
.IP https://bugzilla.redhat.com/1045450 4
.IX Item "https://bugzilla.redhat.com/1045450"
Cannot inspect cirros 0.3.1 disk image fully
.IP https://bugzilla.redhat.com/1045033 4
.IX Item "https://bugzilla.redhat.com/1045033"
LIBVIRT_DEFAULT_URI=qemu:///system breaks libguestfs
.IP https://bugzilla.redhat.com/1044585 4
.IX Item "https://bugzilla.redhat.com/1044585"
virt-builder network (eg. \-\-install) doesn't work if resolv.conf sets nameserver 127.0.0.1
.IP https://bugzilla.redhat.com/1044014 4
.IX Item "https://bugzilla.redhat.com/1044014"
When SSSD is installed, libvirt configuration requires authentication, but not clear to user
.IP https://bugzilla.redhat.com/1039995 4
.IX Item "https://bugzilla.redhat.com/1039995"
virt-make-fs fails making fat/vfat whole disk: Device partition expected, not making filesystem on entire device '/dev/sda' (use \-I to override)
.IP https://bugzilla.redhat.com/1039540 4
.IX Item "https://bugzilla.redhat.com/1039540"
virt-sysprep to delete more logfiles
.IP https://bugzilla.redhat.com/1033207 4
.IX Item "https://bugzilla.redhat.com/1033207"
RFE: libguestfs inspection does not recognize Free4NAS live CD
.IP https://bugzilla.redhat.com/1028660 4
.IX Item "https://bugzilla.redhat.com/1028660"
RFE: virt\-sysprep/virt\-builder should have an option to lock a user account
.IP https://bugzilla.redhat.com/1026688 4
.IX Item "https://bugzilla.redhat.com/1026688"
libguestfs fails examining libvirt guest with ceph drives: rbd: image name must begin with a '/'
.IP https://bugzilla.redhat.com/1022431 4
.IX Item "https://bugzilla.redhat.com/1022431"
virt-builder fails if \f(CW$HOME\fR/.cache doesn't exist
.IP https://bugzilla.redhat.com/1022184 4
.IX Item "https://bugzilla.redhat.com/1022184"
libguestfs: do not use versioned jar file
.IP https://bugzilla.redhat.com/1020806 4
.IX Item "https://bugzilla.redhat.com/1020806"
All libguestfs LVM operations fail on Debian/Ubuntu
.IP https://bugzilla.redhat.com/1008417 4
.IX Item "https://bugzilla.redhat.com/1008417"
Need update helpout of part-set-gpt-type
.IP https://bugzilla.redhat.com/953907 4
.IX Item "https://bugzilla.redhat.com/953907"
virt-sysprep does not correctly set the hostname on Debian/Ubuntu
.IP https://bugzilla.redhat.com/923355 4
.IX Item "https://bugzilla.redhat.com/923355"
guestfish prints literal "\en" in error messages
.IP https://bugzilla.redhat.com/660687 4
.IX Item "https://bugzilla.redhat.com/660687"
guestmount: "touch" command fails: touch: setting times of `timestamp': Invalid argument
.IP https://bugzilla.redhat.com/593511 4
.IX Item "https://bugzilla.redhat.com/593511"
[RFE] function to get partition name
.IP https://bugzilla.redhat.com/563450 4
.IX Item "https://bugzilla.redhat.com/563450"
list-devices returns devices of different types out of order
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBguestfs\-examples\fR\|(1),
\&\fBguestfs\-faq\fR\|(1),
\&\fBguestfs\-performance\fR\|(1),
\&\fBguestfs\-recipes\fR\|(1),
\&\fBguestfs\-testing\fR\|(1),
\&\fBguestfs\fR\|(3),
\&\fBguestfish\fR\|(1),
http://libguestfs.org/
.SH AUTHOR
.IX Header "AUTHOR"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2023 Red Hat Inc.
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA.
.SH BUGS
.IX Header "BUGS"
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP \(bu 4
The version of libguestfs.
.IP \(bu 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP \(bu 4
Describe the bug accurately and give a way to reproduce it.
.IP \(bu 4
Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.