Sun Management Center Change Manager 1.0.1 Reference Manual

## flash_archive(4CM)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO

#### 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 environment, plus other optional software. Such an archive is used for the rapid installation of the Solaris software 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.

An archive is used for initial installation or whenever a complete, fresh installation is required. An archive contains all of the files from a master and overwrites the installed software on a clone completely.

You create a flash archive with the flar(1MCM) command or the flarcreate(1MCM) command. You view information about a given flash archive with `flar`. The `flar` command also enables you to split or combine the sections of a flash archive.

Flash archives are monolithic files that contain the following:

- Archive identification information

- Files that have been copied from a master system and that will be extracted onto a clone system

The standard extension for a file that contains a flash archive is `.flar`.

The flash archive is laid out in the following sections:

- Archive cookie

- Archive identification

- Predeployment

- Postdeployment

- Reboot

- Summary

- User-defined (optional)

- Archive files

The only assumptions that an application processing the archive can make about section number and placement 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 Section

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 newline characters. It is composed of a series of keyword and 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-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, except for the section boundary keywords. 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 in the following table, 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 keywords 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 specification 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 keywords are reported to the user by means of a non-fatal warning message.

Following are the keywords defined for this version of the Flash archive specification.

Keyword | Type of 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 shown previously.

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

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 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 following table. 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(1MCM) 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 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 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 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 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 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 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 system size verification. The following verification methods are possible using this approach:

  No checking

    If the `files_unarchived_size` keyword is absent, no checking for space 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 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 flarcreate(1MCM). 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, the extraction process, or both. 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 packages.

  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 `\n`. 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 following keywords have default values that are 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 its source, you cannot override the value of a keyword that is filled in by `uname`.

`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`.

#### 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 section boundary.

#### ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | SUNWinst

#### SEE ALSO

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

SunOS 5.9 Last Revised 25 April 2003

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO

- © 2010, Oracle Corporation and/or its affiliates