flarcreate man page on Solaris

flarcreate man page on Solaris

Man page or keyword search:
man Server 20652 pages
apropos Keyword Search (all sections)
Output format

flarcreate(1M) System Administration Commands flarcreate(1M)

NAME
flarcreate - create a flash archive from a master system

SYNOPSIS
flarcreate -n name [-R root] [-A system_image] [-H] [-I]
[-M] [-S] [-c] [-t [-p posn] [-b blocksize]]
[-i date] [-u section]... [-m master]
[-f [filelist | -] [-F]] [-a author]
[-e descr | -E descr_file] [-L archiver] [-D dataset]
[-T type] [-U key=value]... [-x exclude]...
[-y include]... [-z filelist]... [-X filelist]... archive

DESCRIPTION
The flarcreate command creates a flash archive from a master system. A
master system is one that contains a reference configuration, which is
a particular configuration of the Solaris operating environment, plus
optional other software. A flash archive is an easily transportable
version of the reference configuration.

In flash terminology, a system on which an archive is created is called
a master. The system image stored in the archive is deployed to systems
that are called clones.

A flash archive can be created on a system that is running a UFS root
file system or a ZFS root file system. A flash archive of a ZFS rooted
system contains the ZFS send stream of the entire dataset hierarchy
under root dataset and additional send streams for other datasets out‐
side rpool/ROOT except for the swap and dump volumes and any excluded
datasets.

ZFS send stream flash archive images cannot be used to install zones.
You must create a flash archive with an explicit cpio or pax archive
when the system has a ZFS root. To create the flash archive, use the -L
archiver option, described below, specifying cpio or pax as the method
to archive the files.

There are two types of flash archives: full and differential. A full
archive contains all the files that are in a system image. A differen‐
tial archive contains only differences between two system images.
Installation of a differential archive is faster and consumes fewer
resources than installation of a full archive.

In creating a differential archive, you compare two system images. A
system image can be any of:

o a Live Upgrade boot environment, mounted on some directory
using lumount(1M) (see live_upgrade(5))

o a clone system mounted over NFS with root permissions

o a full flash archive expanded into some local directory

To explain the creation of a differential flash archive, the following
terminology is used:

old

The image prior to upgrade or other modification. This is likely
the image as it was installed on clone systems.

new

The old image, plus possible additions or changes and minus possi‐
ble deletions. This is likely the image you want to duplicate on
clone systems.

The flarcreate command compares old and new, creating a differential
archive as follows:

o files on new that are not in old are added to the archive;

o files of the same name that are different between old and
new are taken from new and added to the archive;

o files that are in old and not in new are put in list of
files to be deleted when the differential archive is
installed on clone systems.

When creating a differential flash archive, the currently running image
is, by default, the new image and a second image, specified with the -A
option, is the old image. You can use the -R option to designate an
image other than the currently running system as the new image. These
options are described below.

Note that differential flash archives are not supported for a ZFS root
file system.

Following creation of a flash archive, you can use JumpStart to clone
the archive on multiple systems. Using JumpStart to install one or more
systems is the only installation method available for installing a
flash archive of a ZFS root pool.

You can run flarcreate in multi- or single-user mode. You can also use
the command when the master system is booted from the first Solaris
software CD or from a Solaris net image.

Archive creation should be performed when the master system is in as
stable a state as possible. Following archive creation, use the
flar(1M) command to administer a flash archive.

See flash_archive(4) for a description of the flash archive.

The flarcreate command requires root privileges.

OPTIONS
The flarcreate command has one required argument:

-n name

Specifies the name of the flash archive. name is supplied as the
value of the content_name keyword. See flash_archive(4).

The flarcreate command has the following general options:

-A system_image

Create a differential flash archive by comparing a new system image
(see DESCRIPTION) with the image specified by the system_image
argument. By default, the new system image is the currently running
system. You can change the default with the -R option, described
below. system_image is a directory containing an image. It can be
accessible through UFS, NFS, or lumount(1M).

The rules for inclusion and exclusion of files in a differential
archive are described in DESCRIPTION. You can modify the effect of
these rules with the use of the -x, -X, -y, and -z options,
described below.

This option is not supported when creating a flash archive of a ZFS
root pool.

-c

Compress the archive using compress(1)

-D dataset

Exclude specified datasets from the flash archive. This option can
be used multiple times to exclude multiple datasets.

-f filelist

Use the contents of filelist as a list of files to include in the
archive. The files are included in addition to the normal file
list, unless -F is specified (see below). If filelist is -, the
list is taken from standard input. filelist can include directo‐
ries. If a directory is listed, all files and subdirectories under
that directory are included.

This option is not supported when creating a flash archive of a ZFS
root pool.

-F

Include only files in the list specified by -f. This option makes
-f filelist an absolute list, rather than a list that is appended
to the normal file list.

This option is not supported when creating a flash archive of a ZFS
root pool.

-H

Do not generate hash identifier.

-I

Ignore integrity check. To prevent you from excluding important
system files from an archive, flarcreate runs an integrity check.
This check examines all files registered in a system package data‐
base and stops archive creation if any of them are excluded. Use
this option to override this integrity check.

This option is not supported when creating a flash archive of a ZFS
root pool.

-L archiver

By default, the value for the files_archived_method field in the
identification section is pax(1). If you specify -L, the archiver
(cpio(1) and pax) is used instead.

-M

Used only when you are creating a differential flash archive. When
creating a differential archive, flarcreate creates a long list of
the files in the system that remain the same, are changed, and are
to be deleted on clone systems. This list is stored in the manifest
section of the archive (see flash_archive(4)). When the differen‐
tial archive is deployed, the flash software uses this list to per‐
form a file-by-file check, ensuring the integrity of the clone sys‐
tem. Use of this option to avoids such a check and saves the space
used by the manifest section in a differential archive. However,
you must weigh the savings in time and disk space against the loss
of an integrity check upon deployment. Because of this loss, use of
this option is not recommended.

This option is not supported when creating a flash archive of a ZFS
root pool.

-R root

Create the archive from the file system tree rooted at root. If you
do not specify this option, flarcreate creates an archive from a
file system rooted at /.

Note -

The root file system of any non-global zones must not be refer‐
enced with the -R option. Doing so might damage the global zone's
file system, might compromise the security of the global zone,
and might damage the non-global zone's file system. See zones(5).

-S

Skip the disk space check and do not write archive size data to the
archive. Without -S, flarcreate builds a compressed archive in mem‐
ory before writing the archive to disk, to determine the size of
the archive. This size information is written to the header of the
archive in the files_archived_size field and is used during archive
deployment on the client to ensure enough disk space is available
on the client. Use -S to skip this step. The result of the use of
-S is a significant decrease in the time it takes to create an ar‐
chive.

-U key=value...

Include the user-defined keyword(s) and values in the archive iden‐
tification section.

-x exclude...

Exclude the file or directory exclude from the archive. Note that
the exclude file or directory is assumed to be relative to the
alternate root specified using -R. If the parent directory of the
file exclude is included with the -y option (see -y include), then
only the specific file or directory specified by exclude is
excluded. Conversely, if the parent directory of an included file
is specified for exclusion, then only the file include is included.
For example, if you specify:

-x /a -y /a/b

all of /a except for /a/b is excluded. If you specify:

-y /a -x /a/b

all of /a except for /a/b is included.

This option is not supported when creating a flash archive of a ZFS
root pool.

-X filelist...

Use the contents of filelist as a list of files to exclude from the
archive. If filelist is -, the list is taken from standard input.

This option is not supported when creating a flash archive of a ZFS
root pool.

-y include...

Include the file or directory include in the archive. Note that the
include file or directory is assumed to be relative to the alter‐
nate root specified using -R. See the description of the -x option,
above, for a description of the interaction of the -x and -y
options.

This option is not supported when creating a flash archive of a ZFS
root pool.

-z filelist...

filelist is a list of files prefixed with a plus (+) or minus (-).
A plus indicates that a file should be included in the archive; the
minus indicates exclusion. If filelist is -, the list is taken from
standard input.

This option is not supported when creating a flash archive of a ZFS
root pool.

Use the following option with user-defined sections.

-u section...

Include the user-defined section located in the file section in the
archive. section must be a blank-separated list of section names as
described in flash_archive(4).

Use the following options with tape archives.

-b blocksize

The block size to be used when creating the archive. If not speci‐
fied, a default block size of 64K is used.

-p posn

Used only with -t. Specifies the position on the tape device where
the archive should be created. If not specified, the current posi‐
tion of the tape device is used.

-t

Create an archive on a tape device. The archive operand (see OPER‐
ANDS) is assumed to be the name of the tape device.

The following options are used for archive identification.

-a author

author is used to provide an author name for the archive identifi‐
cation section. If you do not specify -a, no author name is
included in the identification section.

-e descr

The description to be included in the archive as the value of the
content_description archive identification key. This option is
incompatible with -E.

-E descr_file

The description to be used as the value of the archive identifica‐
tion content_description key is retrieved from the file descr_file.
This option is incompatible with -e.

-i date

By default, the value for the creation_date field in the identifi‐
cation section is generated automatically, based on the current
system time and date. If you specify the -i option, date is used
instead. date is in the format YYYYMMDDhhmmss, so that, for exam‐
ple:

20060905031000

...stands for 3:10 AM on September 5, 2006.

-m master

By default, the value for the creation_master field in the identi‐
fication section is the name of the system on which you run flar‐
create, as reported by uname -n. If you specify -m, master is used
instead.

-T type

Content type included in the archive as the value of the con‐
tent_type archive identification key. If you do not specify -T, the
content_type keyword is not included.

OPERANDS
The following operand is supported: