flar(1M)																  flar(1M)

NAME

       flar - administer flash archives

SYNOPSIS

       flar  create  -n name [-R root] [-A system_image] [-H] [-I] [-M] [-S] [-c] [-t [-p posn] [-b blocksize]] [-i date] [-u section...] [-m mas-
       ter] [-f  [filelist | -] [-F]] [-a author] [-e descr | -E descr_file] [-T type] [-U  key=value...]  [-x	exclude...]  [-y  include...]  [-z
       filelist...] [-X filelist...] archive

       flar combine [-d dir] [-u section...] [-t [-p posn] [-b blocksize]] archive

       flar split [-d dir] [-u section...] [-f] [-S section] [-t [-p posn] [-b blocksize]] archive

       flar info [-l] [-k keyword] [-t [-p posn] [-b blocksize]] archive

       The  flar  command is used to administer flash archives. A flash archive is an easily transportable version of a reference configuration 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.  You  can  create  a  flash  archive using either flar with the create subcommand or the flarcreate(1M) command. See
       flash_archive(4).

       In flash terminology, a system on which an archive is created is called a master. The system image stored in the  archive  is  deployed	to
       systems that are called clones.

       There  are two types of flash archives: full and differential. Both are created with the create subcommand. A full archive contains all the
       files that are in a system image. A differential archive contains only differences between two system images. Installation of  a  differen-
       tial archive is faster and consumes fewer resources than installation of a full archive.

       In creating a differential archive, you compare two system images. A system image can be any of:

	 o  a Live Upgrade boot environment, mounted on some directory using lumount(1M) (see live_upgrade(5))

	 o  a clone system mounted over NFS with root permissions

	 o  a full flash archive expanded into some local directory

       To explain the creation of a differential flash archive, the following terminology is used:

       old		       The image prior to upgrade or other modification. This is likely the image as it was installed on clone systems.

       new		       The  old  image, plus possible additions or changes and minus possible deletions. This is likely the image you want
			       to duplicate on clone systems.

       The flar command compares old and new, creating a differential archive as follows:

	 o  files on new that are not in old are added to the archive;

	 o  files of the same name that are different between old and new are taken from new and added to the archive;

	 o  files that are in old and not in new are put in list of files to be deleted when the differential archive is installed on  clone  sys-
	    tems.

       When  creating  a  differential flash archive, the currently running image is, by default, the new image and a second image, specified with
       the -A option, is the old image. You can use the -R option to designate an image other than the currently running system as the new  image.
       These options are described below.

       You  can run flarcreate in multi- or single-user mode. You can also use the command when the master system is booted from the first Solaris
       software CD or from a Solaris net image. Archive creation should be performed when the master system is in as stable a state as possible.

       Following creation of a flash archive, you can use JumpStart to clone the archive on multiple systems.

SUBCOMMANDS

       The flar command includes subcommands for creating, combining, splitting, and providing information about archives. A  subcommands  is  the
       first argument in a flar command line. These subcommands are as follows:

       create		       Create  a new flash archive, of a name you specify with the -n argument, based on the currently running system. Use
			       the -A option (described below) to create a differential flash archive.

       combine		       Combine the individual sections that make up an archive into the archive.  If  dir  is  specified  (see	-d  option
			       below),	the  sections will be gathered from dir; otherwise, they will be gathered from the current directory. Each
			       section is assumed to be in a separate file, the names of which are the section names. At a  minimum,  the  archive
			       cookie  (cookie), archive identification (identification), and archive files (archive) sections must be present. If
			       archive is a directory, its contents are archived using cpio prior to inclusion in the archive. If so specified	in
			       the identification section, the contents are compressed.

			       Note that no validation is performed on any of the sections. In particular, no fields in the identification section
			       are validated or updated. See flash_archive(4) for a description of the archive sections.

       info		       Extract information on an archive. This subcommand is analogous to pkginfo.

       split		       Split an archive into one file for each section of the archive. Each section is copied into a separate file in dir,
			       if  dir	is  specified  (see  -d option below), or the current directory if it is not. The files resulting from the
			       split are named after the sections. The archive cookie is stored in a file named cookie. If  section  is  specified
			       (see -u option below), only the named section is copied.

       The create subcommand requires root privileges.

       The options for each subcommand are described below.

       The  options  for the create subcommand are below. Many of these options supply values for keywords in the identification section of a file
       containing a flash archive. See flash_archive(4) for a description of these keywords.

       -a author	       author is used to provide an author name for the archive identification section of the new flash archive. If you do
			       not specify -a, no author name is included in the identification section.

       -A system_image	       Create  a  differential	flash  archive by comparing a new system image (see ) with the image specified by the sys-
			       tem_image argument. By default, the new system image is the currently running system. You can  change  the  default
			       with  the -R option, described below. system_image is a directory containing an image. It can be accessible through
			       UFS, NFS, or lumount(1M).

			       The rules for inclusion and exclusion of files in a differential archive are described in  .  You  can  modify  the
			       effect of these rules with the use of the -x, -X, -y, and -z options, described below.

       -c		       Compress the archive using compress(1)

       -f filelist	       Use  the  contents  of filelist as a list of files to include in the archive. The files are included in addition to
			       the normal file list, unless -F is specified (see below). If filelist is -, the list is taken from standard input.

       -e descr 	       The description to be included in the archive as the value of the content_description archive  identification  key.
			       This option is incompatible with -E.

       -E descr_file	       The description to be used as the value of the archive identification content_description key is retrieved from the
			       file descr_file. This option is incompatible with -e.

       -F		       Include only files in the list specified by -f. This option makes -f filelist an absolute list, rather than a  list
			       that is appended to the normal file list.

       -H		       Do not generate hash identifier.

       -I		       Ignore  integrity  check.  To  prevent  you  from  excluding  important	system files from an archive, flar runs an
			       integrity check. This check examines all files registered in a system package database and stops  archive  creation
			       if any of them are excluded. Use this option to override this integrity check.

       -i date		       By  default,  the value for the creation_date field in the identification section is generated automatically, based
			       on the current system time and date. If you specify the -i option, date is used instead.

       -m master	       By default, the value for the creation_master field in the identification section is the  name  of  the	system	on
			       which you run flarcreate, as reported by uname -n. If you specify -m, master is used instead.

       -M		       Used  only when you are creating a differential flash archive. When creating a differential archive, flar creates a
			       long list of the files in the system that remain the same, are changed, and are to be  deleted  on  clone  systems.
			       This list is stored in the manifest section of the archive (see flash_archive(4)). When the differential archive is
			       deployed, the flash software uses this list to perform a file-by-file check, ensuring the integrity  of	the  clone
			       system.	Use  of this option to avoids such a check and saves the space used by the manifest section in a differen-
			       tial archive. However, you must weigh the savings in time and disk space against the loss  of  an  integrity  check
			       upon deployment. Because of this loss, use of this option is not recommended.

       -n name		       name is supplied as the value of the content_name keyword. See flash_archive(4).

			       The -n name option, with name argument, is required for the create subcommand.

       -R root		       Create the archive from the file system tree rooted at root. If you do not specify this option, flar creates an ar-
			       chive from a file system rooted at /.  When creating a differential flash archive, the system image specified by -R
			       replaces the currently running system as the new image. See .

			       Note -  The root file system of any non-global zones must not be referenced with the -R option. Doing so might dam-
				       age the global zone's file system, might compromise the security of the global zone, and might  damage  the
				       non-global zone's file system. See zones(5).

       -S		       Skip  the  disk space check and do not write archive size data to the archive. Without -S, flar builds a compressed
			       archive in memory before writing the archive to disk, to ensure you have sufficient disk space.	 Use  -S  to  skip
			       this step. The result of the use of -S is a significant decrease in the time it takes to create an archive.

       -T type		       Content	type  included	in  the archive as the value of the content_type archive identification key. If you do not
			       specify -T, the content_type keyword is not included.

       -U key=value...	       Include the user-defined keyword(s) and values in the archive identification section. See flash_archive(4).

       -u section...	       Include the user-defined section located in the file section in the archive. section must be a blank-separated list
			       of section names as described in flash_archive(4).

       -x exclude ...	       Exclude	the  file  or directory exclude from the archive. Note that the exclude file or directory is assumed to be
			       relative to the alternate root specified using -R. If the parent directory of the file exclude is included with the
			       -y option (see -y include), then only the specific file or directory specified by exclude is excluded.  Conversely,
			       if the parent directory of an included file is specified for exclusion, then only the file include is included. For
			       example, if you specify:

			       -x /a -y /a/b

			       all of /a except for /a/b is excluded. If you specify:

			       -y /a -x /a/b

			       all of /a except for /a/b is included.

       -y include ...	       Include the file or directory include in the archive. Note that the exclude file or directory is assumed to be rel-
			       ative to the alternate root specified using -R. See the description of the -x option, above, for a  description	of
			       the interaction of the -x and -y options.

       -X filelist ...	       Use  the  contents  of filelist as a list of files to exclude from the archive. If filelist is -, the list is taken
			       from standard input.

       -z filelist ...	       filelist is a list of files prefixed with a plus (+) or minus (-). A plus indicates that a file should be  included
			       in the archive; the minus indicates exclusion. If filelist is -, the list is taken from standard input.

       The options for flar info subcommand are as follows:

       -k keyword	       Only the value of the keyword keyword is returned.

       -l		       List all files in the archive. Does not process content from any sections other than the archive section.

       The following are flar info options used with tape archives:

       -b blocksize	       The block size to be used when creating the archive. If not specified, a default block size of 64K is used.

       -p posn		       Specifies  the position on the tape device where the archive should be created. If not specified, the current posi-
			       tion of the tape device is examined.

       -t		       The archive to be analyzed is located on a tape device. The path to the device is specified by archive (see ).

       The options for flar split and combine (split and combine archives) subcommands are as follows:

       -d dir		       Retrieve sections from dir, rather than from the current directory.

       -f		       (Used with split only.) Extract the archive section into directory called archive, rather than placing it in a file
			       of the same name as the section.

       -S section	       (Used with split only.) Extract only the section named section from the archive.

       -u section...	       Appends	section  to the list of sections to be included. The default list includes the cookie, identification, and
			       archive sections. section can be a single section name or a space-separated list of section names.

       The following options are used with tape archives (with both split and combine):

       -b blocksize	       The block size to be used when creating the archive. If not specified, a default block size of 64K is used.

       -p posn		       Used only with -t. Specifies the position on the tape device where the archive should be created. If not specified,
			       the current position of the tape device is used.

       -t		       Create an archive on or read an archive from a tape device. The archive operand (see ) is assumed to be the name of
			       the tape device.

       The following operand is supported:

       archive

	   Path to tape device if the -t option was used. Otherwise, the complete path name of a flash archive. By convention, a file containing a
	   flash archive has a file extension of .flar.

       Example 1: Creating a Flash Archive

       The  command  below creates a flash archive named pogoS9 and stores it in /export/home/archives/s9fcs.flar. The currently running system is
       the basis for the new archive.

       # flar create -n pogoS9 /export/home/archives/s9fcs.flar

       Example 2: Creating Differential Flash Archives

       The command below creates a differential flash archive.

       # flar create -n diff_pogoS9 -A /images 
       /export/home/archives/diff_s9fcs.flar

       In the following example the old system image is accessed through lumount.

       # lumount s9BE /test
       # flar create -n diff_pogoS9 -A /test /export/home/archives/diff_s9fcs.flar

       The following example shows the use of the -R option to specify a new system image other than the currently running system.

       # flar create -n diff_pogoS9 -R /test 
       -A /images /export/home/archives/diff_s9fcs.flar

       Note the caveat on the use of the -R option in the description of that option, above.

       The following exit values are returned for the create, split, and combine subcommands:

       0	Successful completion.

       >0	An error occurred.

       The following exit values are returned for the info subcommand:

       0	Successful completion.

       1	Command failed. If the -k option is used and the requested keyword is not found, flar returns 2.

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

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

       flarcreate(1M), flash_archive(4), attributes(5)

								    6 Apr 2005								  flar(1M)