Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Friday, February 2, 2018
 
 

archiveadm(8)

Name

archiveadm - Oracle Solaris archive utility

Synopsis

archiveadm <subcommand> [options] <arguments>
            create  <archive name>
                [-z|--zone <zone(s)>]
                [-D|--exclude-dataset <dataset(s)>]
                [-Z|--exclude-zone <zone(s)>]
                [-r|--recovery]
                [-e|--exclude-media]
                [-s|--skip-capacity-check]
                [--dehydrate[--publisher <publisher name(s)>]]

                [   --root-only] 
            info  <archive name>
                [-p|--parsable | -t|--targets [-s|--system <system name>]]
                [-k|--key]
                [-c|--cert]
                [-C|--ca-cert]
                [-v|--verbose]
            info  <archive name>
                -o|--output property[,...]
                [-p|--parsable]
                [-s|--system <system_name>]
                [-H|--exclude-headers]
            create-media    <archive name>
                [-g|--global-zone <global-zone>]
                [-s|--source <ISO image> | <repository URI>]
                [-k|--key <ssl_key]
                [-c|--cert <ssl_cert]
                [-d|--dataset <name>]
                [-f|--format <iso or usb>]
                [-o|--output <path for final image>]
            rehydrate  <dehydrated archive name> <archive name>

Description

The archiveadm utility provides users with functionality to create system archive images of a running Oracle Solaris system for the purposes of system cloning and recovery. The utility may also be used to retrieve information about archives, once created, and also to create bootable media from an archive.

The archive type which is created is an Oracle Solaris Unified Archive. An Oracle Solaris Unified Archive is a multi-system archive based upon Oracle Solaris Boot Environments and ZFS data streams. A Unified Archive contains one or more systems which are selected during archive creation. Each system may be encapsulated in its own archive within the overall Unified Archive, so that systems may later be selectively deployed. Alternatively, a single monolithic archive may be created which results in a singly-deployable archive with multiple embedded systems.

Unified Archives contain only ZFS datasets which include file systems, volumes, and snapshots. All other file systems and volume types are excluded from Unified Archives. Any file system resources in a zone are also excluded from the zone's archived data. However, if the type property in an fs resource has either the value lofs or the value zfs, the data referenced by the special property may be included in an archive of the global zone, if it refers to a ZFS file system.

Once created, the Oracle Solaris Unified Archives may be deployed by the Oracle Solaris Automated Installer or by the Oracle Solaris Zones software utilities.

During Oracle Solaris Automated Installer deployments, the archive file is set as an install service configuration parameter, similar to what is done with IPS publishers. When a client boots the service, the install software configures the system with the required ZFS pools, including any locally set ZFS pool properties from the origin system, and then the archived systems are received into the new pools.

During Oracle Solaris Zones deployments from a host system, the zonecfg(8) and zoneadm(8) utilities are used. New zones may be configured by using zonecfg(8) to extract configuration data from an Oracle Solaris Unified Archive. The zoneadm(8) utility may be used to install a zone directly from the archive. Zones may also be installed as part of a new Oracle Solaris Automated Installer deployment along with the global zone.

By default, Oracle Solaris Unified Archives are created in a lightweight form which is based upon the system's active boot environment and related datasets. Related datasets in the context of a zone system archive are the zone's delegated datasets. For an archive of a host global zone, the related datasets are any non-zoned datasets on the system. These archives are known as 'clone archives', as they are suitable for system cloning purposes. These archives are ideal for rapid deployment of the same customized image across a number of nodes.

Archives may be created which optionally contain all boot environments rather than just the active one. This type of archive is more suitable for system recovery purposes, and therefore are known as 'recovery archives'. This mode creates an archive as a single system which contains the selected zone. Any non-global zones within a selected global zone are embedded within the archive, and all boot environments from all systems are included.

During clone archive creation, specific systems may be explicitly included or excluded from the archive. Note that inclusion of a specific list of systems will implicitly exclude all other systems. Inversely, exclusion of a specific list of systems will implicitly include all other systems.

When creating a recovery archive, one specific system may be selected. If the system is a host with installed zones, those zones are embedded in the archive. If a recovery archive of a specific zone is desired, it may be selected. System exclusion is not permitted with recovery archives.

Specific datasets may also be excluded, which can further reduce the size of an archive. All swap and dump devices are excluded from all archives by default. Additionally, the VARSHARE dataset is excluded from clone archives; it is included in recovery archives.

The archiveadm utility supports the pkg(1) revert tag named system:clone which can be specified in a package's manifest for those files that need to be reverted during the archive cloning process. These files get reverted to their as-delivered state.

During archive creation, some content is reverted to its pristine state using pkg(1) revert tags. During recovery archive creation, the system:dev-init revert tag is used. During clone archive creation, the system:dev-init and system:clone revert tags are used. The effect is that both recovery and clone archives have device configuration cleared. Only clone archives have instance-specific information like log file content and some configuration files reverted to their initial state. For more information, see the Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4.

An archive may be optionally created which contains data only from the root pool. When the –-root-only option is used with the create subcommand, all non-root pools are excluded from the archive.

During deployment, archived systems may be selectively deployed from a clone Unified Archive. Systems may also be deployed as zones, which provides for a Global-to-Non-global (G2N) transform functionality. Note that single-system recovery archives are not selectable; an entire recovery archive is deployed as a single deployment.

In order to archive zones on shared storage resources, these zones must be archived as individual systems. This is true for both clone and recovery archives. Additionally, the only zones that can be excluded from a recovery archive are zones on shared storage. It will fail for any other exclusion.

Bootable installation media may be created from an Oracle Solaris Unified Archive. Users may provide options which define the build area and the content of the installation media. The resulting media image may then be used to create recovery media or otherwise custom installation media.

Each of the utility's three main functions are described below in the SUB-COMMANDS section.

Options

The following option is supported:

–h,–-help

Output a help message indicating the usage of the utility.

Sub Commands

The following subcommands are supported:

archiveadm create <archive name>
[–r|–-recovery]
[–z|–-zone <zone(s)>]
[–Z|–-exclude-zone < zone(s)>]
[–D|–-exclude-dataset < dataset(s)>]
[–e|–-exclude-media ]
[–s|–-skip-capacity-check]
[–-dehydrate[–-publisher <publisher name(s)>]]
[–-root-only]

The create command will drive the creation of a new Oracle Solaris Unified Archive. The command requires the location and name of the new archive. This is passed as a path to a new archive file name in a writable directory. The create command requires the user to have solaris.user.manage authorization.

Without options, create will build an archive of the system where the command is invoked. If the system is a global zone, all virtual systems on the host are included. The archive consists of the active boot environment of each system and all related datasets. For a zone, the list of related datasets is equal to the list of delegated datasets. In the global zone, all datasets not affiliated with zones are archived.

All swap and dump devices are excluded from all archives. The VARSHARE dataset is excluded by default from all clone archives.

–r|–-recovery

This option creates an archive suitable for system recovery. This archive type is comprised of a single deployable system containing the selected zone. If the zone is a global zone, the archive contains it and all non-global zones that it hosts. All boot environments (included inactive boot environments) from all systems are included in the archive.

[–z|–-zone <zone(s) >]

This option is used to provide a zonename or list of zonenames to be archived, implicitly excluding all other systems from being archived.

[–Z|–-exclude-zone < zone(s)>]

This option is used to provide a zonename or list of zonenames to be excluded from the archive, implicitly including all other systems. –-zone and –-exclude-zone are mutually exclusive. This option is not valid when –-recovery is used.

[–D|–-exclude-dataset < dataset(s)>]

This option is used to exclude one or more datasets from the archive. The dataset names passed are recursively excluded from the archive, meaning any datasets which are hierarchically 'children' of an excluded dataset are also excluded.


Note -  This option is used to exclude one or more datasets while creating an archive of a global zone or a non-global zone, but not a kernel zone.
[–-root-only]

This option is used to exclude all non‐root pool data. Each non‐root pool is excluded recursively from the resulting archive image. This is useful when a root‐only archive is desired and the list of non‐root pools is not known.

[–e|–-exclude-media]

This option may be used to skip the generation of bootable media for each deployable system in the Unified Archive. This media is created per deployable system automatically in order to enhance archive portability. If this is not desired, this option may be used.

[–s|–-skip-capacity-check]

A capacity check is performed in the staging directory prior to archive stream creation. This option may be used when the user wishes to skip this capacity check.

[–-dehydrate[–-publisher <publisher name(s)>]]

This option is used to dehydrate the archive image during archive creation. Only clone archives will support dehydration.

Additionally a –-publisher option may be provided to specify specific publishers to be dehydrated, which may leave the archive partially dehydrated. If there are multiple publishers, the output will be delimited by a comma separated list of publishers.

The dehydration implementation takes its behavior from the pkg dehydrate command. For more information on what exactly is being removed within a dehydration, consult those references in the pkg(1) man page.

archiveadm info <archive name>
[–v|–-verbose]
[–k|–-key]
[–c|–-cert]
[–C|–-ca-cert]
[–p|–-parsable]
[–t|–-targets]
[–o|–-output property[,...]]
[–s|–-system <system_name>]
[–H|–-exclude-headers]

The info command will provide information about the content of an Oracle Solaris archive file, passed as a URI. If the path is a relative or absolute path to a file system-accessible file, the 'file' URI type is optional. HTTP and HTTPS are other supported URI types.

The output of this command provides archive-related data, such as archive creation time and information regarding the original systems such as hostname, architecture and Oracle Solaris version. It also provides a list of deployable system archives, by system name.

[–v|–-verbose]

This option provides more detail regarding the deployable system archives, including the name of the active boot environment, the version of Oracle Solaris installed, and the size needed to deploy each system archive. Also shown in the verbose mode is the version of the Oracle Solaris OS installed on the host when the archive was created, unique ID (UUID) of the Unified Archive file, and UUID of each system archive.

[–k|–-key]
[–c|–-cert]
[–C|–-ca-cert]

These options are used to pass HTTPS credentials when the path provided is an HTTPS URI. Client certificate, CA certificate and key are set with these options.

[–p|–-parsable]

This option provides a parsable colon-delimited set of values which correlate to the archive information as opposed to the formatted output. This can be useful for scripting or data entry applications. Both verbose and non-verbose parsable outputs include headers which label the outputs.

When the –p option is used in conjunction with the –o option, the output includes only those properties specified with the –o option, in the order requested.

[–t|–-targets]

This option lists information specifically related to the storage configuration on the origin system. Configuration metadata is archived along with the data which is used during deployment to give the Automated Installer a guideline for how to configure the client system. This option gives users a way to examine what AI will attempt to create upon deployment.

This option can be used to retrieve the origin system's target configuration, which may be used in recreating the storage configuration for an AI manifest. The manifest content is shown in XML so that it may be used with a little modification.

For an archive with multiple deployable systems, the –s option can be used in conjunction with the –t option to designate the system for which target configuration data is desired.

[–o|–-output property[,...]]

This option displays the information of the user specified properties in a tabular format. It accepts a case-insensitive, comma separated list of properties. The property must be one of the Native Properties described below.

The properties specified with the –o option must be in the same property category: all Native Archive Properties or all Native System Properties.

The following Native Archive Properties are supported:

ARCHIVE_UUID

The 128-bit unique identifier for this Unified Archive.

ARCHIVE_VERSION

The version of this Unified Archive.

CREATION_TIME

The creation timestamp (UTC) of this Unified Archive.

DEHYDRATED_PUBLISHERS

The publishers (if any) of a dehydrated archive.

HOST_OS_VERSION

The version of Oracle Solaris installed on the host where the Unified Archive was created. For example, 11.4.

HOST_OS_BRANCH

The IPS branch of the osnet-incorporation package installed on the host where the Unified Archive was created. For example, 11.4.0.0.0.123.0.

ISA

'sparc' or 'i386'.

OS_NAME

Solaris name. For example, 'Oracle Solaris 11.4 X86'.

RECOVERY

'Yes' if the archive type is 'recovery'; otherwise 'No'.

SOURCE_HOST

The hostname of the origin archived system.

SYSTEMS

The deployable systems contained in this unified archive. The output is a list of system names separated with comma.

The following Native System Properties are supported:

ACTIVE_BE

The name of the active boot environment on the original system when the archive was created. When a clone archive is redeployed, the active BE agrees with this name. When a recovery archive is redeployed, the active BE on deployment is a copy of this BE with the name "-recovery" appended to it.

AI_MEDIA

The name of the AI media associated with this archived system.

BRAND

The brand of the zone that is archived.

NAME

The name of this system.

OS_BRANCH

The OS branch of osnet-incorporation. For example, '11.4.0.0.0.55.0'.

OS_VERSION

The version of Oracle Solaris installed on this system. For example, '11.4'.

ROOT_ONLY

'Yes' if this system contains only root data; Otherwise 'No'.

SIZE

The estimated minimum size needed to deploy the system. Additional space will need to be added to account for swap and/or dump, and other system configuration actions that are not accounted for in the archive.

SYSTEM_UUID

The 128-bit unique identifier for this system.

[–s|–-system <system_name>]

This option specifies the name(s) of the deployable system archives. Either the –o option or –t option is required with the –s option.

When the –o option is used to display the Native System Properties, the systems must be specified explicitly with the –s option. In this usage, the –s option accepts a comma-separated list of system names. The <system_name> can be one of the values listed in the output of Native Archive Property 'systems', or the special value all to display all the archived systems.

When the –s option is used with the –t option, <system_name> should designate the deployable system for which target configuration data is desired.

[–H|–-exclude-headers]

This option is used to print the output without headers in both parsable and non-parsable mode.

The –o option is required with the –H option.

archiveadm create-media <archive name>
[–g|–-global-zone <global-zone>]
[–s|–-source < ISO image> | <repository URI>]
[–k|–-key <ssl_key>]
[–c|–-cert <ssl_cert >]
[–d|–-dataset < name>]
[–f|–-format < iso or usb>]
[–o|–-output < path for final image>]

The create-media command is used to create bootable media from a Unified Archive. The resulting media image may then be used to boot and install a system from the archive content. The archive file is passed as a path. The path may be a relative or absolute path.

[–g|–-global-zone]

Media is created from an archived global zone. This switch allows users to select the global zone media is created from. The resulting media will deploy an archive of the specified global zone, with any embedded zones.

[–s|–-source]

Bootable media is based upon a Solaris AI image. This switch allows users to provide a source for the AI image. Valid sources are either a path to a compatible Solaris Automated Install ISO image file or the URI of a Solaris IPS repository which contains a compatible pkg://solaris/install-image/solaris-auto-install package. Compatibility is based upon the version of Solaris.

If source is not passed, all IPS publishers which are set on the system executing create-media will be searched for a compatible version of the solaris-auto-install package.

[–k|–-key]
[–c|–-cert]

These options are used to pass HTTPS credentials when the source provided is an HTTPS URI. Client certificate and key are set with these options.

[–d|–-dataset]

This switch allows the user to provide a ZFS dataset to be used as a staging area for media creation. If this is not passed a default staging area on rpool is used.

[–f|–-format]

Selects the format of the resulting bootable media, either ISO or USB image file. If the resulting media image will be larger than 4GB, only the USB format is supported.

[–o|–-output]

The name of the resulting media image file. If not provided, a default name is used.

rehydrate <dehydrated archive name> <archive name>

The rehydrate command is used to create a rehydrated Unified Archive from a dehydrated Unified Archive. The resulting archive will be a fully rehydrated archive. Rehydration re-installs all the files and hardlinks removed by dehydration to restore the archive image to its original state. The rehydration implementation takes its behavior from the pkg rehydrate command. For more information on what exactly rehydration restores to a dehydrated archive consult those references in the pkg(1) man page.

Both the dehydrated archive and rehydrated archive are passed in as paths. The paths may be relative or absolute.

Examples

Example 1 Creating a Default Archive

This example creates an archive with no options, which results in the creation of a Unified Archive containing all systems on the host.

# archiveadm create ./archive.uar
Example 2 Creating an Archive With Excluded Datasets

This example creates an archive excluding the data/scratch and tank/tmp datasets.

# archiveadm create -D data/scratch,tank/tmp ./archive.uar
Example 3 Archiving a Single Zone

This example creates a single-system archive comprised of a zone's active boot environment and related rpool dataset and all delegated datasets.

# archiveadm create -z zone1 ./archive.uar
Example 4 Creating an Archive With Excluded Zones

This example creates an archive excluding the 'zone3' and 'zone4' zones.

# archiveadm create -Z zone3,zone4 ./archive.uar
Example 5 Archiving a solaris-kz Zone

This example creates a single-system archive comprised of a solaris-kz brand zone. Any zones which are deployed within the kernel zone are archived within the single-system archive.

# archiveadm create -z kz1 ./archive.uar
Example 6 Creating a Dehydrated Archive With Specified Publishers

This example creates a dehydrated Archive dehydrating the solaris and nightly publishers.

# archiveadm create --dehydrate --publisher solaris,nightly ./archive.uar
Example 7 Retrieving Basic Archive Information

This example retrieves basic information related to the archive.


# archiveadm info ./archive.uar
        Archive Information
                          Creation Time:  2017-03-29T01:29:29Z
                            Source Host:  myhost
                           Architecture:  i386
                       Operating System:  Oracle Solaris 11.4 X86
                  Dehydrated Publishers:  nightly, solaris
                     Deployable Systems:  global,zone1
Example 8 Retrieving Verbose Archive Information

This example retrieves verbose information related to the archive and its deployable system archives.


# archiveadm info --verbose archive.uar
        Archive Information
                         Creation Time:  2017-03-29T01:29:29Z
                           Source Host:  myhost
                          Architecture:  i386
                      Operating System:  Oracle Solaris 11.4 X86
                 Dehydrated Publishers:  nightly, solaris
                      Recovery Archive:  No
                             Unique ID:  d1689f79-0bca-6cea-e06c-f335e98006f0
                       Host OS Version:  11.4
                        Host OS Branch:  11.4.0.0.0.121.1
                       Archive Version:  1.0
  
                   Deployable Systems
                     'global'
                       OS Version:  11.4
                        OS Branch:  11.4.0.0.0.121.1
                        Active BE:  mybe1
                            Brand:  solaris
                   Installed Size:  21.44GB
                        Unique ID:  73ec33b8-55c2-6291-cabd-943f3b1c359e
                     'zone1'
                       OS Version:  11.4.0.0.0.105.2
                        Active BE:  solaris-6
                            Brand:  solaris
                      Size Needed:  345.90MB
Example 9 Retrieving Storage Configuration Information

This example retrieves information from the archive related to what targets resources will be necessary if an archive were to be deployed through Solaris Automated Installer.


# archiveadm info --targets archive.uar
<target name="origin">
      <disk in_zpool="rpool" in_vdev="rpool-none" whole_disk="true">
        <disk_name name="SYS/HDD0" name_type="receptacle"/>
        <disk_prop dev_type="scsi" dev_vendor="HITACHI" dev_chassis="SYS"
dev_size="585937500secs"/>
        <gpt_partition name="0" action="create" force="false" part_type="bbp">
          <size val="524288secs" start_sector="256"/>
        </gpt_partition>
        <gpt_partition name="1" action="create" force="false" part_type="solaris">
          <size val="585396539secs" start_sector="524544"/>
        </gpt_partition>
        <gpt_partition name="8" action="create" force="false" part_type="reserved">
          <size val="16384secs" start_sector="585921083"/>
        </gpt_partition>
      </disk>
      <disk in_zpool="data" in_vdev="data-none" whole_disk="true">
        <disk_name name="SYS/HDD1" name_type="receptacle"/>
        <disk_prop dev_type="scsi" dev_vendor="HITACHI" dev_chassis="SYS"
dev_size="585937500secs"/>
        <gpt_partition name="0" action="create" force="false" part_type="solaris">
          <size val="585920827secs" start_sector="256"/>
        </gpt_partition>
        <gpt_partition name="8" action="create" force="false" part_type="reserved">
          <size val="16384secs" start_sector="585921083"/>
        </gpt_partition>
      </disk>
      <logical noswap="false" nodump="false">
        <zpool name="data" action="create" is_root="false" mountpoint="/data">
          <vdev name="data-none" redundancy="none"/>
        </zpool>
        <zpool name="rpool" action="create" is_root="true" mountpoint="/rpool">
          <vdev name="rpool-none" redundancy="none"/>
        </zpool>
      </logical>
    </target>
Example 10 Creating Media

This example creates a bootable USB image which will deploy the global zone from 'archive.uar' when booted. It can be copied to a USB device by using the usbcopy(8) command. The AI image components will be sourced from the current list of IPS publishers.

# archiveadm create-media ./archive.uar
Example 11 Creating Media From an IPS Publisher

This example creates bootable media, sourcing the AI image components from a specific IPS publisher.

# archiveadm create-media -s http://server.domain:port
                ./archive.uar
Example 12 Creating Media in a User-selected Build Area

This example shows how to create a media by using an AI ISO image as the source for the boot archive.

# archiveadm create-media -d data/build
                -s S11-2-x86-AI.iso ./archive.uar
Example 13 Creating a Rehydrated Archive From a Dehydrated Archive

This example shows how to create a rehydrated archive from a dehydrated archive.

# archiveadm rehydrate ./dehydrated_archive.uar ./rehydrated_archive.uar
Example 14 Creating Media from a Selected Global Zone

This example shows how to create media from a specific archived global zone.

# archiveadm create-media -g kz-global ./archive.uar
Example 15 Retrieving Native Archive Properties

This example shows how to retrieve native archive properties.

# archiveadm info -o SOURCE_HOST,ISA,RECOVERY,SYSTEMS
                ./archive.uar
SOURCE_HOST   ISA  RECOVERY SYSTEMS
-----------   ---  -------- -------
ss12-aiserver i386 No       sys1,sys2,sys3,sys4
Example 16 Retrieving Native System Properties

This example shows how to retrieve native system properties.

# archiveadm info -o NAME,ACTIVE_BE,BRAND
                -s sys1,sys2,sys3 ./archive.uar
Name Active_BE Brand
---- --------- -----
sys1 solaris-1 solaris
sys2 solaris-2 solaris
Example 17 Retrieving Parsable Native System Properties Without Headers

This example shows how to retrieve parsable native system properties without headers.

# archiveadm info -o NAME,ACTIVE_BE,BRAND
                -s all -p -H ./archive.uar
sys1|solaris-1|solaris
sys2|solaris-2|solaris
sys3|solaris-3|solaris
sys4|solaris-4|solaris

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
install/archive|
Interface Stability
Uncommitted

See Also

ai_manifest(5), zoneadm(8), zonecfg(8)