flar(1M)
NAME
flar - administer flash archives
SYNOPSIS
flar 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] [-e descr | -E descr_file] [-T type] [-U
key=value...] [-x exclude...] [-y include...] [-z filel-
ist...] [-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 refer-
ence 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.
There are two types of flash archives: full and differen-
tial. 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 direc-
tory
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 sys-
tems.
new The old image, plus possible additions or changes and
minus possible deletions. This is likely the image you
want to duplicate on clone systems.
The flar command compares old and new, creating a differen-
tial 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.
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.
The flar command includes subcommands for creating, combin-
ing, splitting, and providing information about archives. A
subcommands is the first argument in a flar command line.
These subcommands are as follows:
create
Create a new flash archive, of a name you specify
with the -n argument, based on the currently run-
ning 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 gath-
ered 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 direc-
tory, its contents are archived using cpio 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 subcom-
mand is analogous to pkginfo.
split Split an archive into one file for each section
of the archive. 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 create subcommand has one required argument:
-n name
name is supplied as the value of the content_name key-
word. See flash_archive(4).
The options for the create subcommand below. Many of these
options supply values for keywords in the identification
section of a file containing 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
archive identification section of the new flash
archive. 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 speci-
fied 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.
-c Compress the archive using compress(1)
-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 speci-
fied (see below). If filelist is -, the list is taken
from standard input.
-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 archive
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.
-H Do not generate hash identifier.
-I Ignore integrity check. To prevent you from excluding
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.
-i date
By default, the value for the creation_date field in
the identification section is generated automatically,
based on the current system time and date. If you
specify the -i option, date 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 manifest
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 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.
-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 system
image specified by -R replaces the currently running
system as the new image. See DESCRIPTION.
-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
archive 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_archive(4).
-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).
-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 direc-
tory 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.
-y include ...
Include the file or directory include in the archive.
Note that the exclude file or directory is assumed to
be relative to the alternate root specified using -R.
See the description of the -x option, above, for a
description of the interaction of the -x and -y
options.
-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.
-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.
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 con-
tent 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
archive 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 dev-
ice. The path to the device is specified by archive
(see OPERANDS).
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
current 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.
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
OPERANDS
The following operand is supported:
archive
Path to tape device if the -t option was used. Other-
wise, the complete path name of a flash archive. By
convention, a file containing a flash archive has a
file extension of .flar.
EXIT STATUS
The following exit values are returned for the create,
split, and combine subcommands:
0 Successful completion.
>0 An error occurred.
The following exit values are returned for the info subcom-
mand:
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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWinst |
|_____________________________|_____________________________|
SEE ALSO
flarcreate(1M), flash_archive(4), attributes(5)
Man(1) output converted with
man2html