Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

flar


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 master]
          [-f [filelist | -] [-F]] [-a author]  [-D dataset]
          [-e descr | -E descr_file] [-L archiver] [-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


DESCRIPTION
     The flar command is used to  administer  flash  archives.  A
     flash archive is an easily transportable version of a refer-
     ence 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.


     A flash archive can be created on a system that is running a
     UFS  root  file  system  or  a ZFS root file system. A flash
     archive of a ZFS root pool contains the entire pool  hierar-
     chy  except  for  the swap and dump volumes and any excluded
     datasets. The swap and dump volumes  are  created  when  the
     flash archive is installed.


     There are two types of flash archives:  full  and  differen-
     tial.  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  differential  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  permis-
              sions

         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  differen-
     tial 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 systems.


     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.


     Note that differential flash archives are not supported  for
     a ZFS root file system.


     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. Using JumpStart to
     install one or more systems is the only installation  method
     available for installing a flash archive of a ZFS root pool.

SUBCOMMANDS
     The flar command includes subcommands for creating,  combin-
     ing,  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 run-
                ning 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 gath-
                ered  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 direc-
                tory,   its   contents   are    archived    using
                files_archived_method  (cpio  and  pax)  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  subcom-
                mand 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.

OPTIONS
     The options for the create subcommand  are  below.  Many  of
     these  options supply values for keywords in the identifica-
     tion 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
                        DESCRIPTION) with the image specified  by
                        the  system_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 con-
                        taining 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 DESCRIPTION. You can  modify
                        the effect of these rules with the use of
                        the -x, -X, -y, and -z options, described
                        below.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


     -c                 Compress the archive using compress(1)


     -D dataset         Exclude specified datasets from the flash
                        archive. This option can be used multiple
                        times to exclude multiple datasets.


     -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. filelist
                        can include directories. If  a  directory
                        is  listed,  all files and subdirectories
                        under that directory are included.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


     -e descr           The description to  be  included  in  the
                        archive    as    the    value    of   the
                        content_description  archive  identifica-
                        tion  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.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


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

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


     -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.    date   is   in   the   format
                        YYYYMMDDhhmmss, so that, for example:

                        20060905031000

                        ...stands for 3:10  AM  on  September  5,
                        2006.


     -L archiver        By   default,   the   value    for    the
                        files_archived_method  field in the iden-
                        tification  section  is  pax(1).  If  you
                        specify  -L,  the  archiver  (cpio(1) and
                        pax) is used instead.


     -m master          By   default,   the   value    for    the
                        creation_master  field in the identifica-
                        tion 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  dif-
                        ferential  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 sec-
                        tion in a differential 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.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


     -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
                        archive  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 DESCRIPTION.

                        Note -

                          The root file system of any  non-global
                          zones  must  not be referenced with the
                          -R option. Doing so  might  damage  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  suf-
                        ficient  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 sec-
                        tion. See flash_archive(4).


     -u section...      Include the user-defined section  located
                        in  the file section in the archive. sec-
                        tion 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  rela-
                        tive  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.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


     -y include ...     Include the file or directory include  in
                        the  archive.  Note that the exclude file
                        or directory is assumed to be relative 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.

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


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

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.


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

                        This option is not supported when  creat-
                        ing a flash archive of a ZFS root pool.



     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  pro-
                   cess  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 position 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 OPERANDS).



     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  sec-
                      tions. 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 posi-
                     tion of the tape device is used.


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



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


EXAMPLES
     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  descrip-
     tion of that option, above.


EXIT STATUS
     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  subcom-
     mand:

     0    Successful completion.


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


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWinst                    |
    |_____________________________|_____________________________|
    | Stability Level             | Evolving                    |
    |_____________________________|_____________________________|


SEE ALSO
     cpio(1), pax(1),  flarcreate(1M),  flash_archive(4),  attri-
     butes(5)










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments