flash_archive(4)




NAME

     flash_archive - format of flash archive


SYNOPSIS

     flash_archive


DESCRIPTION

     A flash archive is an  easily  transportable  version  of  a
     reference  configuration  of  the Solaris operating environ-
     ment, 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.

     There are two types of flash archives:  full  and  differen-
     tial.  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
     differential 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 dif-
     ferential 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 archive with flar. flar also enables you
     to split or combine the sections of a flash archive.

     Flash archives are monolithic files containing both  archive
     identification  information  and  the actual files that have
     been copied from a master 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 identification 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  valida-
     tion purposes.

     The case-sensitive, newline-terminated cookie  that  identi-
     fies 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 evo-
     lution  of  the  flash  archive specification while allowing
     applications  that  process  flash  archives  to   determine
     whether  specific  archives are of a format that can be han-
     dled 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 mes-
     sage and exit.

  Archive Identification Section
     The archive identification section is plain text,  delimited
     with  newline  characters.  It  is  composed  of a series of
     keyword/value pairs, with one pair allowed  per  line.  Key-
     words 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-
     sensitivity 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 key-
     words.  The   identification   section   must   begin   with
     section_begin=ident and must end with section_end=ident.

     In addition to the keywords defined for  the  flash  archive
     and  enumerated  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  conven-
     tions  for  user-defined  keyword  include  the  underscore-
     delimited descriptive method used for the  pre-defined  key-
     words,  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 specification ver-
     sion, that is, if the minor version number  is  higher  than
     the  highest minor version it knows how to process, unrecog-
     nized  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
     specification 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 sec-
     tion. For example, the  archive  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  represented as an ASCII hexadecimal 128-bit
           MD5 hash of the archive contents. This value  is  used
           by the installation software only to validate the con-
           tents of the archive during archive installation.

           If the keyword is present, the hash  value  is  recom-
           puted  during  extraction based on the contents of the
           archive being extracted. If the recomputed value  does
           not  match the stored value in the identification sec-
           tion, the archive is deemed corrupt,  and  appropriate
           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  format  with
           ASCII headers (the -c option to cpio).  If the keyword
           is present, it can have the following value:

           cpio  The archive format in the files section 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  methods  will
           require  a  change  in the major archive specification
           version number, as applications  aware  only  of  cpio
           will  be  unable  to  extract  archives that use other
           archive methods.

     files_compressed_method
           This keyword describes the compression  algorithm  (if
           any) used on the files section. If this keyword is not
           present,  the  files  section   is   assumed   to   be
           uncompressed.  If  the keyword is present, it can have
           one of the following values:

           none  The files section is not compressed.

           compress
                 The   files   section   is   compressed    using
                 compress(1).

     The compression method indicated by this keyword is  applied
     to  the archive file created by the archive method indicated
     by the value of the files_archived_method keyword (if  any).
     gzip  compression of the flash archive is not currently sup-
     ported, 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 specifica-
           tion 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  extrac-
           tion  progress  information  to  the  user.  While the
           deployment 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 extract-
           ing 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 information gathered.

           If the keyword is present, the value is used only  for
           the provision of status information. Because this key-
           word 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  pro-
           vides  size  information,  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 sys-
           tem  size  verification.  The  following  verification
           methods are possible using this approach:

           No checking
                 If the files_unarchived_size keyword is  absent,
                 no space checking will be performed.

           Aggregate checking
                 If the files_unarchived_size keyword is  present
                 and  the  associated  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  archive  as  a whole. They are generally used to assist
     the user in archive selection and to aid in archive  manage-
     ment.  These  keywords  are all optional and are used by the
     deployment programs only to assist the user in  distinguish-
     ing 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,
           f5.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 during 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 archive 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  pack-
           ages.

           There  is  no   length   limit   to   the   value   of
           content_description.  To facilitate display, the value
           can contain escaped newline characters. As in  C,  the
           escaped  newline  takes  the  form  of  0.  Due to the
           escaped newline, backlashes must  be  included  as  \.
           The  description  is  displayed  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  creation_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 creation_* 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 activities 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  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWinst                    |
    |_____________________________|_____________________________|


SEE ALSO

     compress(1), cpio(1), flar(1M),  flarcreate(1M),  md5(3EXT),
     attributes(5)


Man(1) output converted with man2html