flash_archive(4) File Formats flash_archive(4)NAMEflash_archive - format of flash archive
SYNOPSISflash_archiveDESCRIPTION
A flash archive is an easily transportable version of a reference con‐
figuration 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. The machine that contains a flash archive
is referred to as a master system. A machine that receives a copy of a
flash archive is called a clone system.
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 to flar(1M) or flarcreate(1M), specifying cpio or pax
as the method to archive the files.
There are two types of flash archives: full and differential. A full
archive is used for initial installation or whenever a complete, fresh
installation is called for. A differential archive is used to update an
installation. A full archive contains all of the files from a master
and overwrites the installed software on a clone completely. A differ‐
ential archive contains only the differences between the software on a
master and on a clone. These differences include new files, changed
files, and deleted files. (These will be deleted on clones, as well).
Installation of a differential archive is faster and consumes fewer
resources than installation of a full archive.
You create a flash archive, full or differential, with the flar(1M) or
flarcreate(1M) command. You view information about a given flash ar‐
chive with flar. flar also enables you to split or combine the sections
of a flash archive.
Flash archives are monolithic files containing both archive identifica‐
tion information and the actual files that have been copied from a mas‐
ter system and that will be extracted onto a clone system. The standard
extension for a flash archive is .flar.
The flash archive is laid out in the following sections:
o archive cookie
o archive identification
o manifest (for differential archives only)
o predeployment
o postdeployment
o reboot
o summary
o user-defined (optional)
o archive files
The only assumptions regarding section number and placement that an
application processing the archive can make is that there is an identi‐
fication section located immediately after the archive cookie and that
the last section in the archive is an archive files section.
These sections are described in the following subsections.
Archive Cookie
The very beginning of the archive contains a cookie, which serves to
identify the file as a flash archive. It is also used by the deployment
code for identification and validation purposes.
The case-sensitive, newline-terminated cookie that identifies version
1.n flash archives, is FlAsH-aRcHiVe-1.n, where n is an integer in the
range 0 through 9.
The archive version is designed to allow for the future evolution of
the flash archive specification while allowing applications that
process flash archives to determine whether specific archives are of a
format that can be handled correctly. The archive version is a number
of the form x.y, where x is the major version number, and y is the
minor version number.
When an application encounters a flash archive with an unknown major
version number, it should issue an error message and exit.
Archive Identification Section
The archive identification section is plain text, delimited with new‐
line characters. It is composed of a series of keyword/value pairs,
with one pair allowed per line. Keywords and values are separated by a
single equal sign. There are no limits to the length of individual
lines. Binary data to be included as the value to a keyword is base64
encoded. The keywords themselves are case-insensitive. The case-sensi‐
tivity of the values is determined by the definition of the keyword,
though most are case-insensitive.
The global order of the keywords within the identification section is
undefined, save for the section boundary keywords. The identification
section must begin with section_begin=ident and must end with sec‐
tion_end=ident.
In addition to the keywords defined for the flash archive and enumer‐
ated below, users can define their own. These user-defined keywords are
ignored by the flash mechanisms, but can be used by user-provided
scripts or programs that process the identification section. User-
defined keywords must begin with X, and contain characters other than
linefeeds, equal signs, and null characters. For example, X-department
is a valid user-defined keyword. department, which lacks the X- prefix,
is not. Suggested naming conventions for user-defined keyword include
the underscore-delimited descriptive method used for the pre-defined
keywords, or a federated convention similar to that used to name Java
packages.
Applications that process the identification section will process
unrecognized non-user-defined keywords differently, depending on
whether the archive version is known. If the application recognizes the
archive specification version, it will reject any unrecognized non-
user-defined keyword. If the application does not recognize the speci‐
fication version, that is, if the minor version number is higher than
the highest minor version it knows how to process, unrecognized non-
user-defined keywords will be ignored. These ignored keyword are
reported to the user by means of a non-fatal warning message.
The keywords defined for this version of the Flash archive specifica‐
tion are listed below.
Keyword Value Required
section_begin text yes
section_end text yes
archive_id text no
files_archived_method text no
files_compressed_method text no
files_archived_size numeric no
files_unarchived_size numeric no
creation_date text no
creation_master text no
content_name text yes
content_type text no
content_description text no
content_author text no
content_architectures text list no
creation_node text no
creation_hardware_class text no
creation_platform text no
creation_processor text no
creation_release text no
creation_os_name text no
creation_os_version text no
Future versions of the identification section might define additional
keywords. The only guarantee regarding the new keywords is that they
will not intrude upon the user-defined keyword namespace as given
above.
The following is an example identification section:
section_begin=identification
files_archived_method=cpio
files_compressed_method=compress
files_archived_size=259323342
files_unarchived_size=591238111
creation_date=20000131221409
creation_master=pumbaa
content_name=Finance Print Server
content_type=server
content_description=Solaris 8 Print Server
content_author=Mighty Matt
content_architectures=sun4u
creation_node=pumbaa
creation_hardware_class=sun4u
creation_platform=SUNW,Sun-Fire
creation_processor=sparc
creation_release=5.9
creation_os_name=SunOS
creation_os_version=s81_49
x-department=Internal Finance
section_end=identification
The following are descriptions of the identification section keywords:
o section_begin
o section_end
These keywords are used to delimit sections in the archive and are not
limited exclusively to the identification section. For example, the ar‐
chive files section includes a section_begin keyword, though with a
different value. User-defined archive sections will be delimited by
section_begin and section_end keywords, with values appropriate to each
section. The currently defined section names are given in the table
below. User-defined names should follow the same convention as user-
defined identification sections, with the additional restriction that
they not contain forward slashes ( / ).
Section Boundary
───────────────────────────────────────────────────────────
identification identification
archive files archive
archive cookie cookie
Note that while the archive cookie does not use section boundaries, and
thus has no need for a section name within the archive itself, the
flar(1M) command uses section names when splitting the archive, and
thus requires a section name for the archive cookie. The name cookie is
reserved for that purpose.
The following keywords, used in the archive identification section,
describe the contents of the archive files section.
archive_id This optional keyword uniquely describes the
contents of the archive. It is computed as a
unique hash value of the bytes representing
the archive. Currently this value is repre‐
sented as an ASCII hexadecimal 128-bit MD5
hash of the archive contents. This value is
used by the installation software only to
validate the contents of the archive during
archive installation.
If the keyword is present, the hash value is
recomputed during extraction based on the
contents of the archive being extracted. If
the recomputed value does not match the
stored value in the identification section,
the archive is deemed corrupt, and appropri‐
ate actions can be taken by the application.
If the keyword is not present, no integrity
check is performed.
files_archived_method This keyword describes the archive method
used in the files section. If this keyword
is not present, the files section is assumed
to be in cpio(1) format with ASCII headers
(the -c option to cpio). If the keyword is
present, it can have the following value:
pax The archive format in the files sec‐
tion is pax(1) with extended tar(1)
interchange format. Also allows ar‐
chiving and extracting files whose
size is greater than 4 GB.
cpio The archive format in the files sec‐
tion is cpio with ASCII headers.
The compression method indicated by the
files_compressed_method keyword (if present)
is applied to the archive file created by
the archive method.
The introduction of additional archive meth‐
ods will require a change in the major ar‐
chive specification version number, as
applications aware only of cpio/pax will be
unable to extract archives that use other
archive methods.
files_compressed_method This keyword describes the compression algo‐
rithm (if any) used on the files section. If
this keyword is not present, the files sec‐
tion is assumed to be uncompressed. If the
keyword is present, it can have one of the
following values:
none The files section is not com‐
pressed.
compress The files section is compressed
using compress(1).
The compression method indicated by this
keyword is applied to the archive file cre‐
ated by the archive method indicated by the
value of the files_archived_method keyword
(if any). gzip compression of the flash ar‐
chive is not currently supported, as the
gzip decompression program is not included
in the standard miniroot.
Introduction of an additional compression
algorithm would require a change in the
major archive specification version number,
as applications aware only of the above
methods will be unable to extract archives
that use other compression algorithms.
files_archived_size The value associated with this keyword is
the size of the archived files section, in
bytes. This value is used by the deployment
software only to give extraction progress
information to the user. While the deploy‐
ment software can easily determine the size
of the archived files section prior to
extraction, it cannot do so in the case of
archive retrieval via a stream. To determine
the compressed size when extracting from a
stream, the extraction software would have
to read the stream twice. This double read
would result in an unacceptable performance
penalty compared to the value of the infor‐
mation gathered.
If the keyword is present, the value is used
only for the provision of status informa‐
tion. Because this keyword is only advisory,
deployment software must be able to handle
extraction of archives for which the actual
file section size does not match the size
given in files_archive_size.
If files_archive_size is not present and the
archive is being read from a stream device
that does not allow the prior determination
of size information, such as a tape drive,
completion status information will not be
generated. If the keyword is not present and
the archive is being read from a random-
access device such as a mounted file system,
or from a stream that provides size informa‐
tion, the compressed size will be generated
dynamically and used for the provision of
status information.
files_unarchived_size This keyword defines the cumulative size in
bytes of the extracted archive. The value is
used for file system size verification. The
following verification methods are possible
using this approach:
No checking If the files_unar‐
chived_size keyword is
absent, no space
checking will be per‐
formed.
Aggregate checking If the files_unar‐
chived_size keyword is
present and the asso‐
ciated value is an
integer, the integer
will be compared
against the aggregate
free space created by
the requested file
system configuration.
The following keywords provide descriptive information about the ar‐
chive as a whole. They are generally used to assist the user in archive
selection and to aid in archive management. These keywords are all
optional and are used by the deployment programs only to assist the
user in distinguishing between individual archives.
creation_date The value of the creation_date keyword is a
textual timestamp representing the time of
creation for the archive. The value of this
keyword can be overridden at archive creation
time through the flarcreate(1M). The timestamp
must be in ISO-8601 complete basic calendar
format without the time designator (ISO-8601,
§5.4.1(a)) as follows:
CCYYMMDDhhmmss
For example:
20000131221409
(January 31st, 2000 10:14:09pm)
The date and time included in the value should
be in GMT.
creation_master The value of the creation_master keyword is
the name of the master machine used to create
the archive. The value can be overridden at
archive creation time.
content_name The value of the content_name keyword should
describe the archive's function and purpose.
It is similar to the NAME parameter found in
Solaris packages.
The value of the content_name keyword is used
by the deployment utilities to identify the
archive and can be presented to the user dur‐
ing the archive selection process and/or the
extraction process. The value must be no
longer than 256 characters.
content_type The value of this keyword specifies a category
for the archive. This category is defined by
the user and is used by deployment software
for display purposes. This keyword is the
flash analog of the Solaris packaging CATEGORY
keyword.
content_description The value of this keyword is used to provide
the user with a description of what the ar‐
chive contains and should build on the
description provided in content_name. In this
respect, content_description is analogous to
the DESC keyword used in Solaris packages.
There is no length limit to the value of con‐
tent_description. To facilitate display, the
value can contain escaped newline characters.
As in C, the escaped newline takes the form of
0fR. Due to the escaped newline, backlashes
must be included as \. The description is dis‐
played in a non-proportional font, with at
least 40 characters available per line. Lines
too long for display are wrapped.
content_author The value of this keyword is a user-defined
string identifying the creator of the archive.
Suggested values include the full name of the
creator, the creator's email address, or both.
content_architectures The value of this keyword is a comma-delimited
list of the kernel architectures supported by
the given archive. The value of this keyword
is generated at archive creation time, and can
be overridden by the user at that time. If
this keyword is present in the archive, the
extraction mechanism validates the kernel
architecture of the clone system with the list
of architectures supported by the archive. The
extraction fails if the kernel architecture of
the clone is not supported by the archive. If
the keyword is not present, no architecture
validation is performed.
The keywords listed belowhave values filled in by uname(2) at the time
the flash archive is created. If you create a flash archive in which
the root directory is not /, the flash archive software inserts the
string UNKNOWN for all of the creation_* keywords except creation_node,
creation_release, and creation_os_name. For creation_node, the flash
software uses the contents of the nodename(4) file. For cre‐
ation_release and creation_os_name, the flash software attempts to use
the contents of <root_directory>/var/sadm/system/admin/INST_RELEASE. If
it is unsuccessful in reading this file, it assigns the value UNKNOWN.
Regardless of their sources, you cannot override the values of the cre‐
ation_* keywords.
creation_node The return from uname -n.
creation_hardware_class The return from uname -m.
creation_platform The return from uname -i.
creation_processor The return from uname -p.
creation_release The return from uname -r.
creation_os_name The return from uname -s.
creation_os_version The return from uname -v.
Manifest Section
The manifest section is used only for differential flash archives. It
contains a filter that specifies selection of an operating environment
image and a list of the files to be retained in, added to, and deleted
from a clone system. The list contains permissions, modification times,
and other information on each file. The flash software uses this sec‐
tion to perform a consistency check prior to deployment of an archive
on a clone. If the user who created the differential archive used the
-M option to flar(1M) or flarcreate(1M), this section will not be
present.
The manifest section is for the exclusive use of the flash software.
The format of this section is internal to Sun and is subject to change.
Predeployment, Postdeployment, and Reboot Sections
Contain internal information that the flash software uses before and
after deploying an operating environment image. These sections are for
the exclusive use of the flash software.
Summary Section
Contains a summary of archive creation. This section records the activ‐
ities of predeployment and postdeployment scripts.
User-Defined Sections
Following the identification section can be zero or more user-defined
sections. These sections are not processed by the archive extraction
code and can be used for any purpose.
User-defined sections must be line-oriented, terminated with newline
(ASCII 0x0a) characters. There is no limit on the length of individual
lines. If binary data is to be included in a user-defined section, it
should be encoded using base64 or a similar algorithm.
Archive Files Section
The archive files section contains the files gathered from the master
system. While the length of this section should be the same as the
value of the files_archived_size keyword in the identification section,
you should not assume that these two values are equal. This section
begins with section_begin=archive, but it does not have an ending sec‐
tion boundary.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWinst │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOcompress(1), cpio(1), pax(1), tar(1), flar(1M), flarcreate(1M),
md5(3EXT), attributes(5)SunOS 5.10 11 Apr 2011 flash_archive(4)
