.\" -*- 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 "virt-make-fs 1"
.TH virt-make-fs 1 2024-01-09 guestfs-tools-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
virt\-make\-fs \- Make a filesystem from a tar archive or files
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& virt\-make\-fs [\-\-options] input.tar output.img
\&
\& virt\-make\-fs [\-\-options] input.tar.gz output.img
\&
\& virt\-make\-fs [\-\-options] directory output.img
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Virt-make-fs is a command line tool for creating a filesystem from a
tar archive or some files in a directory.  It is similar to tools like
\&\fBmkisofs\fR\|(1), \fBgenisoimage\fR\|(1) and \fBmksquashfs\fR\|(1).  Unlike those
tools, it can create common filesystem types like ext2/3 or NTFS,
which can be useful if you want to attach these filesystems to
existing virtual machines (eg. to import large amounts of read-only
data to a VM).
.PP
To create blank disks, use \fBvirt\-format\fR\|(1).  To create complex
layouts, use \fBguestfish\fR\|(1).
.PP
Basic usage is:
.PP
.Vb 1
\& virt\-make\-fs input output.img
.Ve
.PP
where \f(CW\*(C`input\*(C'\fR is either a directory containing files that you want to
add, or a tar archive (either uncompressed tar or gzip-compressed
tar); and \fIoutput.img\fR is a disk image.  The input type is detected
automatically.  The output disk image defaults to a raw ext2 sparse
image unless you specify extra flags (see "OPTIONS" below).
.SS "FILESYSTEM TYPE"
.IX Subsection "FILESYSTEM TYPE"
The default filesystem type is \f(CW\*(C`ext2\*(C'\fR.  Just about any filesystem
type that libguestfs supports can be used (but \fInot\fR read-only
formats like ISO9660).  Here are some of the more common choices:
.IP \fIext3\fR 4
.IX Item "ext3"
Note that ext3 filesystems contain a journal, typically 1\-32 MB in size.
If you are not going to use the filesystem in a way that requires the
journal, then this is just wasted overhead.
.IP "\fIntfs\fR or \fIvfat\fR" 4
.IX Item "ntfs or vfat"
Useful if exporting data to a Windows guest.
.IP \fIminix\fR 4
.IX Item "minix"
Lower overhead than \f(CW\*(C`ext2\*(C'\fR, but certain limitations on filename
length and total filesystem size.
.PP
\fIEXAMPLE\fR
.IX Subsection "EXAMPLE"
.PP
.Vb 1
\& virt\-make\-fs \-\-type=minix input minixfs.img
.Ve
.SS "TO PARTITION OR NOT TO PARTITION"
.IX Subsection "TO PARTITION OR NOT TO PARTITION"
Optionally virt-make-fs can add a partition table to the output disk.
.PP
Adding a partition can make the disk image more compatible with
certain virtualized operating systems which don't expect to see a
filesystem directly located on a block device (Linux doesn't care and
will happily handle both types).
.PP
On the other hand, if you have a partition table then the output image
is no longer a straight filesystem.  For example you cannot run
\&\fBfsck\fR\|(8) directly on a partitioned disk image.  (However libguestfs
tools such as \fBguestfish\fR\|(1) and \fBvirt\-resize\fR\|(1) can still be
used).
.PP
\fIEXAMPLE\fR
.IX Subsection "EXAMPLE"
.PP
Add an MBR partition:
.PP
.Vb 1
\& virt\-make\-fs \-\-partition \-\- input disk.img
.Ve
.PP
If the output disk image could be terabyte-sized or larger, it's
better to use an EFI/GPT\-compatible partition table:
.PP
.Vb 1
\& virt\-make\-fs \-\-partition=gpt \-\-size=+4T \-\-format=qcow2 input disk.img
.Ve
.SS "EXTRA SPACE"
.IX Subsection "EXTRA SPACE"
Unlike formats such as tar and squashfs, a filesystem does not "just
fit" the files that it contains, but might have extra space.
Depending on how you are going to use the output, you might think this
extra space is wasted and want to minimize it, or you might want to
leave space so that more files can be added later.  Virt-make-fs
defaults to minimizing the extra space, but you can use the \fI\-\-size\fR
flag to leave space in the filesystem if you want it.
.PP
An alternative way to leave extra space but not make the output image
any bigger is to use an alternative disk image format (instead of the
default "raw" format).  Using \fI\-\-format=qcow2\fR will use the native
qemu/KVM qcow2 image format (check your hypervisor supports this
before using it).  This allows you to choose a large \fI\-\-size\fR but the
extra space won't actually be allocated in the image until you try to
store something in it.
.PP
Don’t forget that you can also use local commands including
\&\fBresize2fs\fR\|(8) and \fBvirt\-resize\fR\|(1) to resize existing filesystems,
or rerun virt-make-fs to build another image from scratch.
.PP
\fIEXAMPLE\fR
.IX Subsection "EXAMPLE"
.PP
.Vb 1
\& virt\-make\-fs \-\-format=qcow2 \-\-size=+200M input output.img
.Ve
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-help\fR 4
.IX Item "--help"
Display brief help.
.IP \fB\-\-blocksize=512\fR 4
.IX Item "--blocksize=512"
.PD 0
.IP \fB\-\-blocksize=4096\fR 4
.IX Item "--blocksize=4096"
.PD
This parameter sets the sector size of the output disk image.
.Sp
The default is \f(CW512\fR bytes.
.Sp
See also "guestfs_add_drive_opts" in \fBguestfs\fR\|(3).
.IP \fB\-\-floppy\fR 4
.IX Item "--floppy"
Create a virtual floppy disk.
.Sp
Currently this preselects the size (1440K), partition type (MBR) and
filesystem type (VFAT).  In future it may also choose the geometry.
.IP \fB\-\-size=\fRN 4
.IX Item "--size=N"
.PD 0
.IP \fB\-\-size=+\fRN 4
.IX Item "--size=+N"
.IP "\fB\-s\fR N" 4
.IX Item "-s N"
.IP "\fB\-s\fR \fB+\fRN" 4
.IX Item "-s +N"
.PD
Use the \fI\-\-size\fR (or \fI\-s\fR) option to choose the size of the output
image.
.Sp
If this option is \fInot\fR given, then the output image will be just
large enough to contain all the files, with not much wasted space.
.Sp
To choose a fixed size output disk, specify an absolute number
followed by b/K/M/G/T/P/E to mean bytes, Kilobytes, Megabytes,
Gigabytes, Terabytes, Petabytes or Exabytes.  This must be large
enough to contain all the input files, else you will get an error.
.Sp
To leave extra space, specify \f(CW\*(C`+\*(C'\fR (plus sign) and a number followed
by b/K/M/G/T/P/E to mean bytes, Kilobytes, Megabytes, Gigabytes,
Terabytes, Petabytes or Exabytes.  For example: \fI\-\-size=+200M\fR means
enough space for the input files, and (approximately) an extra 200 MB
free space.
.Sp
Note that virt-make-fs estimates free space, and therefore will not
produce filesystems containing precisely the free space requested.
(It is much more expensive and time-consuming to produce a filesystem
which has precisely the desired free space).
.IP \fB\-\-format=\fRFMT 4
.IX Item "--format=FMT"
.PD 0
.IP "\fB\-F\fR FMT" 4
.IX Item "-F FMT"
.PD
Choose the output disk image format.
.Sp
The default is \f(CW\*(C`raw\*(C'\fR (raw sparse disk image).
.IP \fB\-\-type=\fRFS 4
.IX Item "--type=FS"
.PD 0
.IP "\fB\-t\fR FS" 4
.IX Item "-t FS"
.PD
Choose the output filesystem type.
.Sp
The default is \f(CW\*(C`ext2\*(C'\fR.
.Sp
Any filesystem which is supported read-write by libguestfs can be used
here.
.IP \fB\-\-label=\fRLABEL 4
.IX Item "--label=LABEL"
Set the filesystem label.
.IP \fB\-\-partition\fR 4
.IX Item "--partition"
.PD 0
.IP \fB\-\-partition=\fRPARTTYPE 4
.IX Item "--partition=PARTTYPE"
.PD
If specified, this flag adds an MBR partition table to the output disk
image.
.Sp
You can change the partition table type, eg. \fI\-\-partition=gpt\fR for
large disks.
.Sp
For MBR, virt-make-fs sets the partition type byte automatically.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
Enable debugging information.
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
Display version number and exit.
.IP \fB\-x\fR 4
.IX Item "-x"
Enable libguestfs trace.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBguestfish\fR\|(1),
\&\fBvirt\-format\fR\|(1),
\&\fBvirt\-resize\fR\|(1),
\&\fBvirt\-tar\-in\fR\|(1),
\&\fBmkisofs\fR\|(1),
\&\fBgenisoimage\fR\|(1),
\&\fBmksquashfs\fR\|(1),
\&\fBmke2fs\fR\|(8),
\&\fBresize2fs\fR\|(8),
\&\fBguestfs\fR\|(3),
http://libguestfs.org/.
.SH AUTHOR
.IX Header "AUTHOR"
Richard W.M. Jones http://people.redhat.com/~rjones/
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2010\-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.