flar(1M) System Administration Commands flar(1M)NAMEflar - administer flash archives
SYNOPSISflar create -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] [-D dataset]
[-e descr | -E descr_file] [-L archiver] [-T type]
[-U key=value]... [-x exclude]... [-y include]...
[-z filelist]... [-X filelist]... archive
flar combine [-d dir] [-u section]...
[-t [-p posn] [-b blocksize]] archive
flar split [-d dir] [-u section]... [-f] [-S section]
[-t [-p posn] [-b blocksize]] archive
flar info [-l] [-k keyword] [-t [-p posn] [-b blocksize]] archive
DESCRIPTION
The flar command is used to administer flash archives. A flash archive
is an easily transportable version of a reference configuration of the
Solaris operating environment, plus optional other software. Such an
archive is used for the rapid installation of Solaris on large numbers
of machines. You can create a flash archive using either flar with the
create subcommand or the flarcreate(1M) command. See flash_archive(4).
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. Both are
created with the create subcommand. A full archive contains all the
files that are in a system image. A differential 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 pos‐
sible deletions. This is likely the image you want to duplicate
on clone systems.
The flar 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.
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 creation of a flash archive, you can use JumpStart to clone
the archive on multiple systems. You can install a flash archive of a
ZFS root pool by using Jumpstart, the luupgrade(1M) command, or by
selecting this option from the interactive text installation method.
SUBCOMMANDS
The flar command includes subcommands for creating, combining, split‐
ting, and providing information about archives. A subcommands is the
first argument in a flar command line. These subcommands are as fol‐
lows:
create Create a new flash archive, of a name you specify with the
-n argument, based on the currently running system. Use the
-A option (described below) to create a differential flash
archive.
combine Combine the individual sections that make up an archive into
the archive. If dir is specified (see -d option below), the
sections will be gathered from dir; otherwise, they will be
gathered from the current directory. Each section is assumed
to be in a separate file, the names of which are the section
names. At a minimum, the archive cookie (cookie), archive
identification (identification), and archive files (archive)
sections must be present. If archive is a directory, its
contents are archived using files_archived_method (cpio and
pax) prior to inclusion in the archive. If so specified in
the identification section, the contents are compressed.
Note that no validation is performed on any of the sections.
In particular, no fields in the identification section are
validated or updated. See flash_archive(4) for a description
of the archive sections.
info Extract information on an archive. This subcommand is analo‐
gous to pkginfo.
split Split an archive into one file for each section of the ar‐
chive. Each section is copied into a separate file in dir,
if dir is specified (see -d option below), or the current
directory if it is not. The files resulting from the split
are named after the sections. The archive cookie is stored
in a file named cookie. If section is specified (see -u
option below), only the named section is copied.
The create subcommand requires root privileges.
The options for each subcommand are described below.
OPTIONS
The options for the create subcommand are below. Many of these options
supply values for keywords in the identification section of a file con‐
taining a flash archive. See flash_archive(4) for a description of
these keywords.
-a author author is used to provide an author name for the ar‐
chive identification section of the new flash ar‐
chive. If you do not specify -a, no author name is
included in the identification section.
-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 sys‐
tem. You can change the default with the -R option,
described below. system_image is a directory con‐
taining 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 spec‐
ified (see below). If filelist is -, the list is
taken from standard input. filelist can include
directories. 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.
-e descr The description to be included in the archive as the
value of the content_description archive identifica‐
tion key. This option is incompatible with -E.
-E descr_file The description to be used as the value of the ar‐
chive identification content_description key is
retrieved from the file descr_file. This option is
incompatible with -e.
-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 exclud‐
ing important system files from an archive, flar
runs an integrity check. This check examines all
files registered in a system package database 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.
-i date By default, the value for the creation_date field in
the identification section is generated automati‐
cally, 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
example:
20060905031000
...stands for 3:10 AM on September 5, 2006.
-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 master By default, the value for the creation_master field
in the identification section is the name of the
system on which you run flarcreate, as reported by
uname -n. If you specify -m, master is used instead.
-M Used only when you are creating a differential flash
archive. When creating a differential archive, flar
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 mani‐
fest section of the archive (see flash_archive(4)).
When the differential archive is deployed, the flash
software uses this list to perform a file-by-file
check, ensuring the integrity of the clone system.
Use of this option to avoids such a check and saves
the space used by the manifest section in a differ‐
ential 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.
-n name name is supplied as the value of the content_name
keyword. See flash_archive(4).
The -n name option, with name argument, is required
for the create subcommand.
-R root Create the archive from the file system tree rooted
at root. If you do not specify this option, flar
creates an archive from a file system rooted at /.
When creating a differential flash archive, the sys‐
tem image specified by -R replaces the currently
running system as the new image. See DESCRIPTION.
Note -
The root file system of any non-global zones must
not be referenced 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, flar builds a
compressed archive in memory before writing the ar‐
chive to disk, to ensure you have sufficient disk
space. 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 archive.
-T type Content type included in the archive as the value of
the content_type archive identification key. If you
do not specify -T, the content_type keyword is not
included.
-U key=value... Include the user-defined keyword(s) and values in
the archive identification section. See flash_ar‐
chive(4).
-u section... Include the user-defined section located in the file
section in the archive. section must be a blank-sep‐
arated list of section names as described in
flash_archive(4).
-x exclude ... Exclude the file or directory exclude from the ar‐
chive. Note that the exclude file or directory is
assumed to be relative to the alternate root speci‐
fied 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 spec‐
ify:
-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.
-y include ... Include the file or directory include in the ar‐
chive. Note that the exclude file or directory is
assumed to be relative to the alternate root speci‐
fied 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.
-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.
-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 exclu‐
sion. If filelist is -, the list is taken from stan‐
dard input.
This option is not supported when creating a flash
archive of a ZFS root pool.
The options for flar info subcommand are as follows:
-k keyword Only the value of the keyword keyword is returned.
-l List all files in the archive. Does not process content
from any sections other than the archive section.
The following are flar info options used with tape archives:
-b blocksize The block size to be used when creating the archive. If
not specified, a default block size of 64K is used.
-p posn Specifies the position on the tape device where the ar‐
chive should be created. If not specified, the current
position of the tape device is examined.
-t The archive to be analyzed is located on a tape device.
The path to the device is specified by archive (see OP‐
ERANDS).
The options for flar split and combine (split and combine archives)
subcommands are as follows:
-d dir Retrieve sections from dir, rather than from the cur‐
rent directory.
-f (Used with split only.) Extract the archive section
into directory called archive, rather than placing it
in a file of the same name as the section.
-S section (Used with split only.) Extract only the section named
section from the archive.
-u section... Appends section to the list of sections to be
included. The default list includes the cookie, iden‐
tification, and archive sections. section can be a
single section name or a space-separated list of sec‐
tion names.
The following options are used with tape archives (with both split and
combine):
-b blocksize The block size to be used when creating the archive. If
not specified, 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 position of the tape device is
used.
-t Create an archive on or read an archive from a tape
device. The archive operand (see OPERANDS) is assumed
to be the name of the tape device.
OPERANDS
The following operand is supported:
archive Path to tape device if the -t option was used. Otherwise,
the complete path name of a flash archive. By convention, a
file containing a flash archive has a file extension of
.flar.
EXAMPLES
Example 1 Creating a Flash Archive
The command below creates a flash archive named pogoS9 and stores it in
/export/home/archives/s9fcs.flar. The currently running system is the
basis for the new archive.
# flar create -n pogoS9 /export/home/archives/s9fcs.flar
Example 2 Creating Differential Flash Archives
The command below creates a differential flash archive.
# flar create -n diff_pogoS9 -A /images \
/export/home/archives/diff_s9fcs.flar
In the following example the old system image is accessed through
lumount.
# lumount s9BE /test
# flar create -n diff_pogoS9 -A /test \
/export/home/archives/diff_s9fcs.flar
The following example shows the use of the -R option to specify a new
system image other than the currently running system.
# flar create -n diff_pogoS9 -R /test \
-A /images /export/home/archives/diff_s9fcs.flar
Note the caveat on the use of the -R option in the description of that
option, above.
EXIT STATUS
The following exit values are returned for the create, split, and com‐
bine subcommands:
0 Successful completion.
>0 An error occurred.
The following exit values are returned for the info subcommand:
0 Successful completion.
1 Command failed. If the -k option is used and the requested keyword
is not found, flar returns 2.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWinst │
├─────────────────────────────┼─────────────────────────────┤
│Stability Level │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcpio(1), pax(1), flarcreate(1M), luupgrade(1M), flash_archive(4),
attributes(5)SunOS 5.10 12 Apr 2011 flar(1M)
