Solaris 10 10/09 Installation Guide: Solaris Flash Archives (Creation and Installation)

Chapter 5 Solaris Flash (Reference)

This chapter provides a description of Solaris Flash sections, keywords, and keyword values. Also, the chapter describes the flar command options.

For limitations when creating or installing a Solaris Flash archive, see Table 2–1.

Solaris Flash Archive Section Descriptions

Each Solaris Flash archive is grouped into sections. Some sections are generated by the Solaris Flash software and need no input from you. Some sections require input or optionally allow you to add information. The following table describes each section.

Table 5–1 Flash Archive Sections


Section Name	Description	Required by Archive?	Requires Input From User?
Archive cookie	The first section contains a cookie that identifies the file as a Solaris Flash archive. The deployment code uses the cookie for identification and validation purposes. The cookie must be present for an archive to be valid.	Yes	No
Archive identification	The second section contains keywords with values that provide identification information about the archive. The software generates some information such as the following: The archive ID number The method of archival such as `cpio` The creation date by default You are required to specify a name for the Solaris Flash archive. Other information that you can specify about the archive includes the following: The author of the archive The date that the archive was created The name of the master system that you used to create the archive For a list of keywords that describe the archive, see Keywords for the Archive Identification Section.	Yes	Content is generated by both user and the software
Manifest	A section of a Solaris Flash archive that is used to validate a clone system. The manifest section lists the files on a system to be retained, added to, or deleted from the clone system. The installation fails if the files do not match the expected file set. This section is informational only. The section lists the files in an internal format and cannot be used for scripting. You can exclude this section by creating the differential archive with the `flarcreate` `-M` option. Because no validation of the archive occurs, excluding this section is not recommended.	No	No
Predeployment, Postdeployment, Reboot	This section contains internal information that the flash software uses before and after installing an OS image. Any customization scripts that you have provided are stored in this section.	Yes	No
Summary	This section contains messages about the archive creation and records the activities of predeployment scripts.	Yes	Content is generated by both user and the software
User-defined	This section follows the archive-identification section. The archive can contain zero or more user-defined sections. These sections are not processed by the archive extraction code. These sections are retrieved separately and can be used for content descriptions.	No	Yes
Archive files	The archive files section contains the files that have been gathered from the master system in binary data. This section begins with `section_begin=archive`, but it does not have an ending section boundary.	Yes	No

Solaris Flash Keywords

Solaris Flash keywords are like custom JumpStart keywords. They define elements of the installation. Each keyword is a command that controls one aspect of how the Solaris Flash software installs the software on a clone system.

Use the following guidelines to format keywords and values:

Keywords and values are separated by a single equal sign with only one pair per line
Keywords are case insensitive
Individual lines can be any length

General Keywords

Each Solaris Flash archive section is defined by the section_begin and section_end keywords. For example, the archive files section includes a section_begin keyword, though with a different value. User-defined archive sections are delimited by section_begin and section_end keywords, with values appropriate to each section. The values for the section_begin and section_end keywords are described in the following table.

Table 5–2 Values for section_begin and section_end Keywords


Archive Section	Value for `section_begin` and `section_end` keywords
Archive cookie	`cookie` – This section is not delimited by the `section_begin` and `section_end` keywords.
Archive identification	`identification`
User-defined sections	`section_name` – An example of a `section_name` keyword is X-user_section_1.
Archive files	`archive`

Keywords for the Archive Identification Section

The following tables describe the keywords for use in the archive identification section and the values you can define for them.

Every section uses the keywords in Table 5–3 to delimit each section.

Table 5–3 Archive Identification Section Keywords: General Keywords


Keywords	Value Definitions	Value	Required
`section_begin` `section_end`	These keywords are used to delimit sections in the archive and are not limited exclusively to the archive identification section. For a description of these keywords, see General Keywords.	Text	Yes

The following keywords, used in the archive-identification section, describe the contents of the archive files section.

Table 5–4 Archive Identification Section Keywords: Contents of Archive Files Section


Keywords	Value Definitions	Value	Required
`archive_id` (optional)	This keyword uniquely describes the contents of the archive. This value is used by the installation software only to validate the contents of the archive during archive installation. If the keyword is not present, no integrity check is performed. For example, the `archive_id` keyword might be `FlAsH-ARcHive-2.0`.	Text	No
`files_archived_method`	This keyword describes the archive method that is used in the files section. If this keyword is not present, the files section is assumed to be in `cpio` format with ASCII headers. This format is the `cpio` `-c` option. If this keyword is present, it has one of the following values: `cpio` – The archive format in the files section is `cpio` with ASCII headers. `pax` – The archive format in the files section is `pax` with extended `tar` interchange format. The `pax` utility enables archiving and extracting files that are greater than 4 GB. If the `files_compressed_method` is present, the compression method is applied to the archive file that is created by the archive method.	Text	No
`files_archived_size`	This keyword value is the size of the archived files section in bytes.	Numeric	No
`files_compress_method`	This keyword describes the compression algorithm that is used on the files section. If the keyword is present, it can have one of the following values. `none` – The archive file section is not compressed. `compress` – The file section is compressed by using the `compress` command. If this keyword is not present, the archive files section is assumed to be uncompressed. The compression method that is indicated by this keyword is applied to the archive file created by the archive method indicated by the `files_archived_method` keyword.	Text	No
`files_unarchived_size`	This keyword defines the cumulative size in bytes of the extracted archive. The value is used for file-system size verification.	Numeric	No

The following keywords provide descriptive information about the entire archive. These keywords are generally used to assist you in archive selection and to aid in archive management. These keywords are all optional and are used to help you to distinguish between individual archives. You use options for the flarcreate command to include these keywords. For details, see Example 3–9.

Table 5–5 Archive Identification Section Keywords: User Describes the Archive


Keywords	Value Definitions	Value	Required
`creation_date`	This keyword value is a textual timestamp that represents the time that you created the archive. You can use the `flarcreate` command with the `-i` option to create the date. If you do not specify a creation date with the `flarcreate` command, the default date is set in Greenwich mean time (GMT). The value must be in ISO-8601 complete basic calendar format without the time designator (ISO-8601,§5.4.1(a)). The format is `CCYYMMDDhhmmss`. For example, 20000131221409 represents January 31, 2000, 10:14:09 p.m.	Text	No
`creation_master`	This keyword value is the name of the master system you used to create the archive. You can use the `flarcreate` `-m` option to create this value. If you do not specify a value, the value is taken from the `uname -n` command.	Text	No
`content_name`	This keyword identifies the archive. The value is generated from the `flarcreate` `-n` option. Follow these guidelines when you create this value: The descriptive name can be no longer than 256 characters. The description should contain the function and purpose of the archive.	Text	Yes
`content_type`	This keyword value specifies a category for the archive. You use the `flarcreate` `-T` option to generate the value.	Text	No
`content_description`	The keyword value describes the contents of the archive. The value of this keyword has no length limit. You use the `flarcreate` `-E` option to create this value.	Text	No
`content_author`	This keyword value identifies the creator of the archive. You use the `flarcreate-a` option to create this value. Suggested values include the full name of the creator and the creator's email address.	Text	No
`content_architectures`	This keyword value is a comma-separated list of the kernel architectures that the archive supports. If the keyword is present, the installation software validates the kernel architecture of the clone system against the list of architectures that the archive supports. The installation fails if the archive does not support the kernel architecture of the clone system. If the keyword is not present, the installation software does not validate the architecture of the clone system.	Text list	No

The following keywords also describe the entire archive. By default, the values are filled in by uname when the flash archive is created. If you create a flash archive in which the root directory is not /, the archive software inserts the string UNKNOWN for the keywords. The exceptions are the creation_node, creation_release, and creation_os_name keywords.

For creation_node, the software uses the contents of the nodename file.
For creation_release and creation_os_name, the software attempts to use the contents of root directory /var/sadm/system/admin/INST_RELEASE. If the software is unsuccessful in reading this file, it assigns the value UNKNOWN.

Regardless of their sources, you cannot override the values of these keywords.

Table 5–6 Archive Identification Section Keywords: Software Describes the Archive


Keyword	Value
`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`

User-Defined Section Keywords

In addition to the keywords that are defined by the Solaris Flash archive, you can define other keywords. The Solaris Flash archive ignores user-defined keywords, but you can provide scripts or programs that process the archive identification section and use user-defined keywords. Use the following format when creating user-defined keywords:

Begin the keyword name with an X.
Create the keyword with any characters other than linefeeds, equal signs, and null characters.
Suggested naming conventions for user-defined keywords include the underscore-delimited descriptive method used for the predefined keywords. Another convention is a federated convention similar to the naming of Java packages.

For example, X-department is a valid name for a user-defined keyword.

For an example of using options to include user-defined keywords in the archive identification section, see Example 3–9.

Solaris Flash `flar` Command

Use the Solaris Flash flar command to create a Solaris Flash archive and administer the archive.

`flar` Command

You can use the flar command with the following options:

flarcreate creates an archive
flar combine merges two archives
flar split breaks an archive into sections
flar info checks the structure of an archive

Use the flarcreate command to create a Solaris Flash archive from a master system. You can use this command when the master system is running in multiuser mode or single-user mode. You can also use flarcreate when the master system is booted from the following media.

Solaris Operating System DVD
Solaris Software - 1 CD
A Solaris network installation image of the DVD or CDs.

The master system should be in as stable a state as possible when you create a Solaris Flash archive.

Note –

You can create a Solaris Flash archive by using either of these command options:

As two words: flar with the create subcommand
As one word: flarcreate

The syntax of the command is as follows:

flarcreate -n archive_name [-R root] [-A unchanged_master_image_dir] [-H][-I][-M][[-S]-c][-t [-p posn] [-b blocksize]][-i date][-u section ...][-m master][-f [list_filename| -] [-F][-a author][-e descr|-E descr_file][-L pax] [-T type][-U key=val ...][-x exclude_dir/filename] [-y include_dir/filename] [-z list_filename] [-X list_filename]path/filename

flar combine [-d dir] [-u section...] [-t [-p posn] path/filename

flar split [-d dir] [-u section...] [-f] [-S section] [-t [-p posn] path/filename

flar info [-l] [-k keyword] [-t [-p posn] path/filename

In the previous command lines, path is the directory in which you want the archive file to be saved. filename is the name of the archive file. If you do not specify a path, flarcreate saves the archive file in the current directory.

Table 5–7 Command-Line Options for the flar Command


Option	Description
Required Options
`-n` `archive_name`	The value of this flag is the name of the archive. The `archive_name` you specify is the value of the `content_name` keyword.
Option for Compression
`-c`	Compresses the archive by using `compress(1)`.
Options for Directories and Sizes
`-R` `root`	Creates the archive from the file system tree that begins at the file system specified by `root`. If you do not specify this option, `flarcreate` creates an archive from a file system that begins at the root `(/)` file system.
`-S`	Omits sizing information in the archive.
`-H`	Does not generate the hash identifier.
Options for Creating a Differential Archive
`-A` `unchanged_master_image_dir`	Creates a differential archive by comparing a new system image with the image that is specified by the `unchanged_master_image_dir` argument. By default, the new system image is root (`/`). You can change the default with the `-R` option. `unchanged_master_image_dir` is a directory where the unchanged master system image is stored or mounted through UFS, NFS, or `lumount`. You can modify the effects of file selection for a differential archive by using the options for contents selection described in the next section of the table.
`-M`	Excludes the manifest file. When you use this option, no validation occurs on the differential archive. When creating a differential archive, `flarcreate` creates a long list of the files in the system that are unchanged, are changed, and are to be deleted from the archive. This list is stored in the manifest section of the archive. When the differential archive is deployed, the software uses this list to perform a file-by-file check, ensuring the integrity of the clone system. Use of this option avoids such a check and saves the space that is used by the manifest section in a differential archive. However, you must consider the savings in time and disk space against the loss of an integrity check upon installation. Because no validation occurs, avoid using this option.
Options for Contents Selection
Caution – Use the `flarcreate` file-exclusion options with caution. If you exclude some directories, others that you were unaware of might be left in the archive, such as system configuration files. The system would then be inconsistent and the installation would not work. Excluding directories and files is best used with data that can easily be removed without disrupting the system, such as large data files.
`-y` `include_dir/filename`	Adds to the archive those files and directories that are specified on the command line. This option is used when you have excluded a directory, but want to restore individual subdirectories or files. `include_dir/filename` is the name of the subdirectory or file to be included.
`-f` `list_filename`	Adds files and directories from a list to the archive. `list_filename` is the full path to a file that contains a list. The contents of the file are added to the file list unless `-F` is specified. The `list_filename` file must contain one file per line. If you specify a file system with `-R` `root`, the path to each file must be relative to the alternate `root` directory or an absolute path. If `filename` is “-”, `flarcreate` reads standard input as the list of files. When you use the value “-”, the archive size is not calculated.
`-F`	Uses only the files in `-f` `list_filename` to create the archive. This option makes the `-f` `list_filename` the absolute list, rather than a list that is appended to the normal file list.
`-x` `exclude_dir/filename`	Excludes files and directories from the archive. These files and directories are specified at the command line. You can use multiple instances of this option to exclude more than one file or directory. `exclude_dir/filename` is the name of the directory or file to be excluded.
`-X` `list_filename`	Excludes a list of files or directories from the archive. `list_filename` is the full path to a file that contains the list. The `list_filename` file must contain one file per line. If you specify a file system with `-R` `root`, the path to each file must be relative to the alternate `root` directory or an absolute path. If `list_filename` is “-”, `flarcreate` reads standard input as the list of files. When you use the value “-”, the archive size is not calculated.
`-z` `list_filename`	Excludes or includes a list of files or directories from the archive. Each file or directory in the list is noted with a plus “+” or minus “-”. A plus indicates an included file or directory and the minus indicates an excluded file or directory. `list_filename` is the full path to a file that contains the list. The `list_filename` file must contain one file per line. If you specify a file system with `-R` `root`, the path to each file must be relative to the alternate `root` directory or an absolute path.
`-I`	Override the integrity check. To prevent you from excluding important system files from an archive, `flarcreate` runs an integrity check. This check examines all files that are registered in a system package database and stops archive creation if any of them are excluded. Use of this option overrides this integrity check. Therefore, avoid the use of the `-I` option.
Options for Splitting and Merging Archives
`-d` `dir`	Retrieves the sections to copy from `dir`, rather than from the current directory.
`-u` `section`	If you use this option, `flar` copies the cookie, identification, archive, and `section` sections. You can specify a single section name or a space-separated list of section names. If you do not use this option, `flar` copies the cookie, ldentification, and archive sections only.
`-f` archive	Extracts the archive section into a directory that is named `archive`, rather than placing it in a file with the name `archive`. Used for splitting an archive.
`-S` `section`	Only copies the section that is named `section` from the archive. This section is user defined. Used for splitting an archive.
Option Used To Copy Files (Archive)
`-L pax`	The `cpio` utility is the default copy method. If you have large individual files, the `-L pax` option uses the `pax` utility to create an archive without limitations on individual file sizes. Individual file sizes can be greater than 4 GB.
Options Used With User-Defined Sections
`-u` `section`	Includes `section` as a user-defined section. To include more than one user-defined section, `section` must be a space-separated list of section names.
`-d` `dir`	Retrieves the section file that is specified with `-u` from `dir`.
Options Used With Tape Archives
`-t`	Creates an archive on a tape device. The `filename` argument is the name of the tape device.
`-p` `posn`	Use only with the `-t` option. Specifies the position on the tape device for `flarcreate` to store the archive. If you do not use this option, `flarcreate` places the archive at the current position of the tape.
`-b` `blocksize`	Specifies the block size `flarcreate` uses when creating the archive. If you do not specify a block size, `flarcreate` uses the default block size of 64 KB.
Options for Archive Identification These keywords and values appear in the archive identification section of the archive.
`-U` `key=val`	Includes user-defined keywords and values in the archive identification section.
`-i` `date`	Uses `date` as the value for the `creation_date` keyword. If you do not specify a date, `flarcreate` uses the current system time and date.
`-m` `master`	Uses `master` as the name of the master system on which you created the archive. `master` is the value for the `creation_master` keyword. If you do not specify `master`, `flarcreate` uses the system name that is reported by `uname -n`.
`-e` `descr`	Uses `descr` for the value of the `content_description` keyword. You cannot use this option when you use the `-E` option.
`-E` `descr_file`	Retrieves the value for the `content_description` keyword from the `descr_file` file. You cannot use this option when you use the `-e` option.
`-a` `author`	Uses `author` as the author name in the archive identification section. `author` is the value for the `content_author` keyword. If you do not specify an author, `flarcreate` does not include the `content_author` keyword in the archive identification section.
`-T` `type`	Uses `type` as the value for the `content_type` keyword. `type` is user defined. If you do not specify a type, `flarcreate` does not include the `content_type` keyword.