unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

flash_archive(4)                 File Formats                 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 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.

       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.


       tab(); lw(1.933333i) lw(1.783333i) lw(1.783333i).  KeywordValueRequired
       section_begintextyes        section_endtextyes         archive_idtextno
       files_archived_methodtextno               files_compressed_methodtextno
       files_archived_sizenumericno    files_unarchived_sizenumericno     cre-
       ation_datetextno    creation_mastertextno    content_nametextyes   con-
       tent_typetextno  content_descriptiontextno  content_authortextno   con-
       tent_architecturestext    listno   creation_nodetextno   creation_hard-
       ware_classtextno creation_platformtextno creation_processortextno  cre-
       ation_releasetextno creation_os_nametextno creation_os_versiontextno


       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:

            section_begin

            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 ( / ).


       tab(); lw(2.750000i)  lw(2.750000i).   SectionBoundary  identification-
       identification archive filesarchive archive cookiecookie


       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  ar-
           chive.  It  is  computed as a unique hash value of the bytes repre-
           senting 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
           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 identi-
           fication section, 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 sec-
           tion. 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 appli-
           cations  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 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 compressed.




           compress                The  files section is compressed using com-
                                   press(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 supported, as the gzip decom-
           pression 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 appli-
           cations 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 soft-
           ware  only  to  give  extraction  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  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
           information gathered.

           If the keyword is present, the value is used only for the provision
           of  status  information.  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  informa-
           tion  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 information, the
           compressed size will be generated dynamically and used for the pro-
           vision 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_unarchived_size  keyword  is
                                   absent, no  space  checking  will  be  per-
                                   formed.




           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 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 rep-
           resenting 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
           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,   con-
           tent_description  is  analogous to the DESC keyword used in Solaris
           packages.

           There is no length limit to the value  of  content_description.  To
           facilitate  display,  the value can contain escaped newline charac-
           ters. As in C, the escaped newline takes the form of  0fR.  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  overrid-
           den by the user at that time. If this keyword is present in the ar-
           chive, 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:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWinst


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



SunOS 5.10                        29 Apr 2003                 flash_archive(4)