mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-22 07:03:38 +00:00
3b8322e18c
I noticed that the --attach option was not covered in the synopsis. This commit documents all of the missing command line parameters in the synopsis.
283 lines
6.6 KiB
Plaintext
283 lines
6.6 KiB
Plaintext
=head1 NAME
|
|
|
|
virt-customize - Customize a virtual machine
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
virt-customize
|
|
[ -a disk.img [ -a disk.img ... ] | -d domname ]
|
|
[--attach ISOFILE] [--attach-format FORMAT]
|
|
[ -c URI | --connect URI ] [ -n | --dry-run ]
|
|
[ --format FORMAT] [ -m MB | --memsize MB ]
|
|
[ --network | --no-network ]
|
|
[ -q | --quiet ] [--smp N] [ -v | --verbose ] [-x]
|
|
__CUSTOMIZE_SYNOPSIS__
|
|
|
|
virt-customize [ -V | --version ]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Virt-customize can customize a virtual machine (disk image) by
|
|
installing packages, editing configuration files, and so on.
|
|
|
|
Virt-customize modifies the guest or disk image I<in place>. The
|
|
guest must be shut down. If you want to preserve the existing
|
|
contents of the guest, I<you must snapshot, copy or clone the disk first>.
|
|
|
|
You do I<not> need to run virt-customize as root. In fact we'd
|
|
generally recommend that you don't.
|
|
|
|
Related tools include: L<virt-sysprep(1)> and L<virt-builder(1)>.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over 4
|
|
|
|
=item B<--help>
|
|
|
|
Display brief help.
|
|
|
|
=item B<-a> file
|
|
|
|
=item B<--add> file
|
|
|
|
Add I<file> which should be a disk image from a virtual machine.
|
|
|
|
The format of the disk image is auto-detected. To override this and
|
|
force a particular format use the I<--format> option.
|
|
|
|
=item B<-a> URI
|
|
|
|
=item B<--add> URI
|
|
|
|
Add a remote disk. The URI format is compatible with guestfish.
|
|
See L<guestfish(1)/ADDING REMOTE STORAGE>.
|
|
|
|
=item B<--attach> ISOFILE
|
|
|
|
The given disk is attached to the libguestfs appliance. This is used
|
|
to provide extra software repositories or other data for
|
|
customization.
|
|
|
|
You probably want to ensure the volume(s) or filesystems in the
|
|
attached disks are labelled (or use an ISO volume name) so that you
|
|
can mount them by label in your run-scripts:
|
|
|
|
mkdir /tmp/mount
|
|
mount LABEL=EXTRA /tmp/mount
|
|
|
|
You can have multiple I<--attach> options, and the format can be any
|
|
disk format (not just an ISO).
|
|
|
|
=item B<--attach-format> FORMAT
|
|
|
|
Specify the disk format for the next I<--attach> option. The
|
|
C<FORMAT> is usually C<raw> or C<qcow2>. Use C<raw> for ISOs.
|
|
|
|
=item B<-c> URI
|
|
|
|
=item B<--connect> URI
|
|
|
|
If using libvirt, connect to the given I<URI>. If omitted, then we
|
|
connect to the default libvirt hypervisor.
|
|
|
|
If you specify guest block devices directly (I<-a>), then libvirt is
|
|
not used at all.
|
|
|
|
=item B<-d> guest
|
|
|
|
=item B<--domain> guest
|
|
|
|
Add all the disks from the named libvirt guest. Domain UUIDs can be
|
|
used instead of names.
|
|
|
|
=item B<-n>
|
|
|
|
=item B<--dry-run>
|
|
|
|
Perform a read-only "dry run" on the guest. This runs the sysprep
|
|
operation, but throws away any changes to the disk at the end.
|
|
|
|
=item B<--format> raw|qcow2|..
|
|
|
|
=item B<--format> auto
|
|
|
|
The default for the I<-a> option is to auto-detect the format of the
|
|
disk image. Using this forces the disk format for I<-a> options which
|
|
follow on the command line. Using I<--format auto> switches back to
|
|
auto-detection for subsequent I<-a> options.
|
|
|
|
For example:
|
|
|
|
virt-customize --format raw -a disk.img
|
|
|
|
forces raw format (no auto-detection) for F<disk.img>.
|
|
|
|
virt-customize --format raw -a disk.img --format auto -a another.img
|
|
|
|
forces raw format (no auto-detection) for F<disk.img> and reverts to
|
|
auto-detection for F<another.img>.
|
|
|
|
If you have untrusted raw-format guest disk images, you should use
|
|
this option to specify the disk format. This avoids a possible
|
|
security problem with malicious guests (CVE-2010-3851).
|
|
|
|
=item B<-m> MB
|
|
|
|
=item B<--memsize> MB
|
|
|
|
Change the amount of memory allocated to I<--run> scripts. Increase
|
|
this if you find that I<--run> scripts or the I<--install> option are
|
|
running out of memory.
|
|
|
|
The default can be found with this command:
|
|
|
|
guestfish get-memsize
|
|
|
|
=item B<--network>
|
|
|
|
=item B<--no-network>
|
|
|
|
Enable or disable network access from the guest during the installation.
|
|
|
|
Enabled is the default. Use I<--no-network> to disable access.
|
|
|
|
The network only allows outgoing connections and has other minor
|
|
limitations. See L<virt-rescue(1)/NETWORK>.
|
|
|
|
If you use I<--no-network> then certain other options such as
|
|
I<--install> will not work.
|
|
|
|
This does not affect whether the guest can access the network once it
|
|
has been booted, because that is controlled by your hypervisor or
|
|
cloud environment and has nothing to do with virt-customize.
|
|
|
|
Generally speaking you should I<not> use I<--no-network>. But here
|
|
are some reasons why you might want to:
|
|
|
|
=over 4
|
|
|
|
=item 1.
|
|
|
|
Because the libguestfs backend that you are using doesn't support the
|
|
network. (See: L<guestfs(3)/BACKEND>).
|
|
|
|
=item 2.
|
|
|
|
Any software you need to install comes from an attached ISO, so you
|
|
don't need the network.
|
|
|
|
=item 3.
|
|
|
|
You don't want untrusted guest code trying to access your host network
|
|
when running virt-customize. This is particularly an issue when you
|
|
don't trust the source of the operating system templates. (See
|
|
L</SECURITY> below).
|
|
|
|
=item 4.
|
|
|
|
You don't have a host network (eg. in secure/restricted environments).
|
|
|
|
=back
|
|
|
|
=item B<-q>
|
|
|
|
=item B<--quiet>
|
|
|
|
Don't print log messages.
|
|
|
|
To enable detailed logging of individual file operations, use I<-x>.
|
|
|
|
=item B<--smp> N
|
|
|
|
Enable N E<ge> 2 virtual CPUs for I<--run> scripts to use.
|
|
|
|
=item B<-v>
|
|
|
|
=item B<--verbose>
|
|
|
|
Enable verbose messages for debugging.
|
|
|
|
=item B<-V>
|
|
|
|
=item B<--version>
|
|
|
|
Display version number and exit.
|
|
|
|
=item B<-x>
|
|
|
|
Enable tracing of libguestfs API calls.
|
|
|
|
=back
|
|
|
|
=head2 Customization options
|
|
|
|
__CUSTOMIZE_OPTIONS__
|
|
|
|
=head1 SELINUX
|
|
|
|
For guests which make use of SELinux, special handling for them might
|
|
be needed when using operations which create new files or alter
|
|
existing ones.
|
|
|
|
For further details, see L<virt-builder(1)/SELINUX>.
|
|
|
|
=head1 EXIT STATUS
|
|
|
|
This program returns 0 on success, or 1 if there was an error.
|
|
|
|
=head1 ENVIRONMENT VARIABLES
|
|
|
|
=over 4
|
|
|
|
=item C<VIRT_TOOLS_DATA_DIR>
|
|
|
|
This can point to the directory containing data files used for Windows
|
|
firstboot installation.
|
|
|
|
Normally you do not need to set this. If not set, a compiled-in
|
|
default will be used (something like F</usr/share/virt-tools>).
|
|
|
|
This directory may contain the following files:
|
|
|
|
=over 4
|
|
|
|
=item F<rhsrvany.exe>
|
|
|
|
This is the RHSrvAny Windows binary, used to install a "firstboot"
|
|
script in Windows guests. It is required if you intend to use the
|
|
I<--firstboot> or I<--firstboot-command> options with Windows guests.
|
|
|
|
See also: C<https://github.com/rwmjones/rhsrvany>
|
|
|
|
=back
|
|
|
|
=back
|
|
|
|
For other environment variables, see L<guestfs(3)/ENVIRONMENT VARIABLES>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<guestfs(3)>,
|
|
L<guestfish(1)>,
|
|
L<virt-builder(1)>,
|
|
L<virt-clone(1)>,
|
|
L<virt-rescue(1)>,
|
|
L<virt-resize(1)>,
|
|
L<virt-sparsify(1)>,
|
|
L<virt-sysprep(1)>,
|
|
L<virsh(1)>,
|
|
L<lvcreate(8)>,
|
|
L<qemu-img(1)>,
|
|
L<scrub(1)>,
|
|
L<http://libguestfs.org/>,
|
|
L<http://libvirt.org/>.
|
|
|
|
=head1 AUTHORS
|
|
|
|
Richard W.M. Jones L<http://people.redhat.com/~rjones/>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (C) 2011-2016 Red Hat Inc.
|