Skip to content

GitLab

Commit 0469f905 authored by Mike Hibler's avatar Mike Hibler
Browse files
Options

Preliminary man pages for imagezip tools.

parent 424d948e
Hide whitespace changes
Inline Side-by-side
Showing with 544 additions and 0 deletions
os/imagezip/imagedump.8 0 → 100644
View file @ 0469f905
.\"
.\" EMULAB-COPYRIGHT
.\" Copyright (c) 2000-2003 University of Utah and the Flux Group.
.\" All rights reserved.
.\"
.Dd January 9, 2003
.Dt IMAGEDUMP 8
.Os
.Sh NAME
.Nm imagedump
.Nd dump information about an imagezip compressed image file
.Sh SYNOPSIS
.Nm
.Op Fl dv
.Ar imagefile ...
.Sh DESCRIPTION
The
.Nm
utility can be used to view information about
.Xr imagezip
created image files.
With no options,
.Nm
prints a summary for each image file specified. This summary includes:
the size of the image file, the size of the resulting uncompressed data,
the compression factor achieved on allocated data (due to
.Xr zlib Ns
),
the overall compression factor (due to smart filesystem aware compression and
.Xr zlib Ns
),
and the amount of overhead and wasted space in the image file
(due to the way in which compressed data is chunked in the image file).
.Pp
One or more
.Fl d
options can be specified to dump various levels of structure within the
image file.
.Pp
The
.Fl v
option prints version information about
.Nm
itself.
.Sh DIAGNOSTICS
The
.Nm
utility will exit with a status of zero if it successfully parses and
dumps all the listed image files.
It will exit non-zero if there is any error.
.Sh SEE ALSO
.Xr imagezip 8 ,
.Xr imageunzip 8 ,
.Xr zlib 3
.Sh HISTORY
The
.Nm
utility is part of the Netbed software (www.netbed.org).
.Sh BUGS
The
.Xr imagedump
image format needs to be documented.
os/imagezip/imageunzip.8 0 → 100644
View file @ 0469f905
.\"
.\" EMULAB-COPYRIGHT
.\" Copyright (c) 2000-2003 University of Utah and the Flux Group.
.\" All rights reserved.
.\"
.Dd January 9, 2003
.Dt IMAGEUNZIP 8
.Os
.Sh NAME
.Nm imageunzip
.Nd restore a compressed image created by imagezip
.Sh SYNOPSIS
.Nm
.Op Fl dnovz
.Op Fl D Ar DOS-ptype
.Op Fl p Ar pattern
.Op Fl s Ar slice
.Ar image
.Op outfile
.Sh DESCRIPTION
The
.Nm
utility is used to restore a compressed image of a complete disk or
single DOS partition that was created by
.Xr imagezip .
Unlike
.Xr imagezip ,
.Nm
has no special knowledge of filesystem types.
It merely reads compressed data from the image, decompresses it,
and writes it to the appropriate location in
.Ar outfile .
.Pp
Since
.Xr imagezip
created image files may contain just the location of free blocks and
not their data,
.Nm
must recreate those blocks' data in some way.
The conservative strategy, specified by using the
.Fl z
option, is to write zeros (or a pattern indicated by the
.Fl p
option) to the appropriate location in the output file.
A more efficient strategy is to do nothing for new free blocks,
leaving whatever was at the target location in the output file.
This allows
.Nm
to simply skip over long ranges of free blocks, speeding the restoration
process enormously.
This is the default strategy unless the output file is not seekable.
A potentially security concern with the skip strategy is that data can
.Dq leak
through from the previous use of the
.Ar outfile
to the new use. If this is an issue, use
.Fl z
to ensure that all blocks in
.Ar outfile
are overwritten.
.Pp
See the
.Xr imagezip
man page for more details on disk images and their creation.
.Pp
To further optimize the image restoration process,
writing of the image to the output file is done is a separate thread
from reading and uncompressing. This allows overlap of uncompression and IO.
The
.Fl n
option can be used to disable this feature.
.Pp
Command line arguments are:
.Bl -tag -width "outfile"
.It image
The
.Xr imagezip
created image file. If
.Ar image
is '-', the image is read from
.Va stdin .
.It outfile
The output file for the expanded image. If not specified,
.Va stdout
is used.
.El
.Pp
Recognized options are:
.Bl -tag -width indent
.It Fl D Ar DOS-ptype
In slice mode, after successful restoration of the image,
change the DOS partition type of the slice indicated by the
.Fl s
option to the numeric value
.Ar DOS-ptype .
This can be used to ensure that the MBR information matches what is in
the slice. Without this option, the MBR is not touched when restoring
an image to a slice.
.It Fl d
Turn on debugging output. Can be specified multiple times to increase
the level of debugging output.
.It Fl n
Run uncompression and disk writing in a single thread.
This option can be used for benchmarking or if a race condition is suspected.
You will probably never need this option.
.It Fl o
Indicate the progress of image restore by printing a dot ('.') to
.Dv stderr
after every 1MB of compressed data that is uncompressed and written to
the output file.
At the end of each line of dots, elapsed time in seconds and
the amount of expanded data written is also printed.
.It Fl p Ar pattern
Specify a 32-bit
.Dq zero pattern
that is to be written to free blocks when using the
.Fl z
option. The default value is zero.
.It Fl s Ar slice
Restore
.Ar image
to the indicated slice.
The slice number should be the DOS partition number which ranges from 1 to 4.
The specified
.Ar outfile
must be seekable and have a DOS MBR with a partition table in its first sector.
.It Fl v
Print the version number of
.Nm
and exit.
.It Fl z
Tells
.Nm
to write the
.Dq zero pattern
to free blocks in the image rather than seeking over them.
.El
.Sh DIAGNOSTICS
The
.Nm
utility will exit with a status of zero if it successfully uncompresses the
entire image and writes it to the output. It will exit non-zero if it
runs out of memory or gets an error while reading or uncompressing the
image or writing the output file.
.Sh IMPLEMENTATION NOTES
Because
.Xr imagezip
does not include the content of free blocks in the image and
because
.Nm
may not initialize these free blocks with any value, you cannot
perform a simple compare of the source and destination of an image.
.Pp
If
.Ar outfile
is a device special file, it should always be the special file for
an entire disk even when restoring slice images.
.Pp
Since slice images do not contain the DOS MBR, you cannot load a slice image
on a naked disk and expect it to boot.
If you need such a bootable slice image, you can use the
.Fl I
option to ignore all but the slice you care about, thus
creating a full disk image containing only that single slice.
.Pp
If the output file is a disk or slice,
it should not overlap with the filesystem you are running off of
or disaster will ensue!
.Sh EXAMPLES
.Dl imageunzip /nfs/backup/images/myimage.ndz /dev/ad0
.Pp
Restore a full disk image across NFS to the master IDE disk.
This would have to be done while running in a memory system booted
from a CDROM or the network.
.Pp
.Dl ssh backup cat /images/myimage.ndz | imageunzip - /dev/ad0
.Pp
As above but uses ssh to transfer the image from the remote machine.
.Pp
.Dl ssh backup imagezip -s 1 /dev/ad0 | imageunzip -z -D 165 -s 1 - /dev/ad0
.Pp
Image slice 1 on the remote machine and restore it to the same slice
on the local disk, zeroing all free blocks and marking the slice as
FreeBSD (165) in the DOS partition table.
.Pp
.Dl imageunzip -z image.ndz | wc
.Pp
A slow way to find out how big an image would be when uncompressed
(use
.Xr imagedump
instead).
.Sh SEE ALSO
.Xr imageunzip 8 ,
.Xr imagedump 8 ,
.Xr fdisk 8 ,
.Xr disklabel 8 ,
.Xr zlib 3
.Sh HISTORY
The
.Nm
utility is part of the Netbed software (www.netbed.org).
os/imagezip/imagezip.8 0 → 100644
View file @ 0469f905
.\"
.\" EMULAB-COPYRIGHT
.\" Copyright (c) 2000-2003 University of Utah and the Flux Group.
.\" All rights reserved.
.\"
.Dd January 9, 2003
.Dt IMAGEZIP 8
.Os
.Sh NAME
.Nm imagezip
.Nd create a compressed image of a complete disk or DOS partition
.Sh SYNOPSIS
.Nm
.Op Fl bdhilorv
.Op Fl c Ar count
.Op Fl I Ar slice
.Op Fl s Ar slice
.Op Fl z Ar level
.Ar device
.Op outfile
.Sh DESCRIPTION
The
.Nm
utility is used to create a compressed image of the complete disk or
single DOS partition identified by
.Ar device .
The result is written to
.Ar outfile
or
.Dv stdout .
This image can later be uncompressed and installed using the companion
.Xr imageunzip 8
utility.
.Nm
understands the format of several of the more popular filesystem types
(BSD FFS, Linux EXT2FS, NTFS) and uses that knowledge to
.Dq smartly compress
the data, ensuring that only allocated blocks in a filesystem are
compressed and saved in the image. Free blocks within a filesystem are
recorded but otherwise skipped.
Conventional
.Xr zlib 3
compression is applied to the allocated data during smart compression
and is also used on filesystem types which are not understood.
.Pp
When used to create a full disk image (the default), the
.Ar device
argument should refer to a
.Dq raw
disk device such as
.Pa /dev/ad1 .
In this mode,
.Nm
expects the first sector of the disk to contain a DOS Master Boot Record (MBR)
including a DOS partition table.
The information in the DOS partition table is used to locate all the
slices on the disk and determine what they contain.
(Note:
.Em slice
is BSD-speak for a DOS-style partition. A
.Em partition
in BSD is a subset of a slice, typically used to hold a filesystem.)
Each slice is then processed in turn as described in the next paragraph.
If a disk does not have a DOS partition table, the
.Fl r
option can be used to force
.Nm
to treat the disk as though it were a big bag of bits which it will
then compress using conventional compression.
.Pp
To create a single slice image, the
.Fl s
option is used.
.Nm
will use the DOS partition table to look up the specified
slice number and determine its location and type.
The slice type determines the action of
.Nm
as follows:
.Bl -hang
.It Sy Unused
(0).
The slice is skipped.
.It Sy FreeBSD/NetBSD/386BSD
(165).
.Nm
will attempt to locate a BSD partition table and process each BSD
partition in turn. If no partition table is found,
.Nm
fails. Within a BSD slice, filesystem partitions are smartly compressed,
unused and swap partitions are skipped, and all others are
compressed conventionally.
.It Sy Linux filesystem
(131).
If the slice contains a Linux EXT2FS, it is smartly compressed.
Otherwise
.Nm
fails.
.It Sy Linux swap
(130).
The first 8KB (the bitmap) is compressed conventionally, the remainder
of the slice is skipped.
.El
.Pp
All unrecognized slice types are compressed conventionally.
.Pp
Command line arguments are:
.Bl -tag -width "outfile"
.It device
The device to be imaged. This is typically a disk special file.
.It outfile
The output file for the resulting image. If not specified,
.Va stdout
is used.
.El
.Pp
Recognized options are:
.Bl -tag -width indent
.It Fl b
Tells
.Nm
that
.Ar device
is a BSD slice. Should be used only when the device does not contain
a DOS partition table and really does contains a BSD filesystem.
Incompatible with
.Fl l .
You will probably never need this option.
.It Fl c Ar count
Explicitly tell
.Nm
how many sectors to compress in full disk mode. Can be used to compress
a subset of a disk.
Incompatible with
.Fl s .
You will probably never need this option.
.It Fl d
Turn on debugging output. Can be specified multiple times to increase
the level of debugging output.
.It Fl h
Print a usage message.
.It Fl I Ar slice
In full disk mode, tells
.Nm
to skip a specific slice. This option can be given multiple times to
skip multiple slices.
The slice number should be the DOS partition number which ranges from 1 to 4.
Incompatible with
.Fl s .
.It Fl i
Prints a variety of diagnostic information about what
.Nm
would do, but doesn't create an image file.
.It Fl l
Tells
.Nm
that
.Ar device
is a Linux filesystem slice. Should be used only when the device does
not contain a DOS partition table and really does contains a Linux filesystem.
Incompatible with
.Fl b .
You will probably never need this option.
.It Fl o
Indicate the progress of image creation by printing a dot ('.') to
.Dv stderr
after every 1MB of compressed data is written to the output file.
At the end of each line of dots, the input offset and elapsed time in
seconds is also printed.
.It Fl r
Generate a
.Dq raw
image using conventional compression. No smart compression is attempted
and thus the disk need not contain a DOS MBR, disklabels,
or any filesystem structure.
.It Fl s Ar slice
Create a slice image containing only the indicated slice.
The slice number should be the DOS partition number which ranges from 1 to 4.
.It Fl v
Print the version number of
.Nm
and exit.
.It Fl z Ar level
Set the compression level (0-9) used by the
.Xr zlib
compression library. Higher levels mean better compression but will cause
.Nm
to run longer. Level 0 means no compression. The default value is 4.
.El
.Sh DIAGNOSTICS
The
.Nm
utility will exit with a status of zero if it successfully processes the
entire disk or slice and creates the image. It will exit non-zero if it
runs out of memory, cannot parse the MBR or a filesystem, or gets an error
reading or writing.
.Sh IMPLEMENTATION NOTES
If
.Ar device
is a device special file, it should always be the special file for
an entire disk even when creating slice images. The only exception is
when using the
.Fl b
and
.Fl l
options.
If
.Ar device
is not a regular file, it must be a seekable file type.
Thus, pipes are not allowed and no provision is made for redirecting input
to
.Nm .
.Pp
Creating a partition image for each DOS partition on a disk and then
concatenating them together is
.Em not
the same as creating a full disk image of a disk, as the latter
contains the initial (typically 63) sectors which are outside of any
DOS partition. Most importantly, this area is where the DOS MBR is stored.
.Pp
Since slice images do not contain the DOS MBR, you cannot load a slice image
on a naked disk and expect it to boot.
If you need such a bootable slice image, you can use the
.Fl I
option to ignore all but the slice you care about, thus
creating a full disk image containing only that single slice.
.Pp
The output image,
.Ar outfile ,
created by imagezip should not be on the same disk
that you are imaging since you would be changing the disk as it is saving.
In general, it is a bad idea to create an image of an active disk.
.Pp
FreeBSD partition tables contain absolute, not slice relative, block
numbers.
.Nm
contains code to recognize this and generates "relocation entries"
for imageunzip to use. But this is only one problem you will encounter
if attempting to move a FreeBSD slice to a different location.
.Pp
Likewise, Linux boot boot blocks generated by LILO appear to contain
absolute block numbers. In theory, the
.Nm
relocation mechanism could handle this, but no one I know groks LILO.
.Pp
NTFS (Windows NT/2000/XP filesystem) can be handled but isn't in this
release.
.Sh EXAMPLES
.Dl imagezip /dev/ad0 /nfs/backup/images/myimage.ndz
.Pp
Create a full disk image of the master IDE disk saving it across
NFS to a remote machine. This could be done with the machine in single
user mode and the root filesystem mounted read-only, or it could be
done from a CDROM or network booted system.
.Pp
.Dl imagezip /dev/ad0 | ssh backup 'cat > /backup/images/myimage.ndz'
.Pp
As above but uses ssh to transfer the image to the remote machine.
.Pp
.Dl imagezip -o -s 1 /dev/ad0 myimage.ndz
.Pp
Create a slice image of DOS partition 1 on the primary disk, amusing
yourself by watching the dots go by.
.Pp
.Dl imagezip -r -z 9 /dev/ad0 | imageunzip - /dev/ad1
.Pp
A really slow way to copy one disk to another.
.Sh SEE ALSO
.Xr imageunzip 8 ,
.Xr imagedump 8 ,
.Xr fdisk 8 ,
.Xr disklabel 8 ,
.Xr zlib 3
.Sh HISTORY
The
.Nm
utility is part of the Netbed software (www.netbed.org).
.Sh BUGS
Full disk smart compression in
.Nm
is pretty x86 specific due to its reliance on the DOS MBR.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment