archiveadm - Oracle Solaris archive utility
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>
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. See uar(7) for more information on Unified Archives in general.
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.
Only ZFS data is archived, and the data on other file system types such as tmpfs(4FS) and ufs(4FS) are not included. Archives of zones will not include any file systems mounted in the zone by way of an fs resource. Such data may be included in the global zone's archive, as long as it is on ZFS. In contrast, a ZFS filesystem delegated to the zone through a dataset resource or a zpool resource, is included in the zone's archive. For more information, see zones(7) and zonecfg(8).
When a clone archive is created of a global zone, the global zone archive will exclude storage delegated to any zone. That is, any ZFS filesystem mounted at any zone's zonepath, and its descendant datasets and all storage referenced by any zone's dataset or zpool resource is excluded from the global zone archive. The content of a global zone archive is not impacted by any zone's fs resources.
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.
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.
The following option is supported:
Output a help message indicating the usage of the utility.
The following subcommands are supported:
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.
If you run the archiveadm create command in a solaris branded zone, ensure that pcfs is included as part of the fs-allowed property value in the zone configuration.
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.
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.
This option is used to provide a zonename or list of zonenames to be archived, implicitly excluding all other systems from being archived.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
The 128-bit unique identifier for this Unified Archive.
The version of this Unified Archive.
The creation timestamp (UTC) of this Unified Archive.
The publishers (if any) of a dehydrated archive.
The version of Oracle Solaris installed on the host where the Unified Archive was created. For example, 11.4.
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.
'sparc' or 'i386'.
Solaris name. For example, 'Oracle Solaris 11.4 X86'.
'Yes' if the archive type is 'recovery'; otherwise 'No'.
The hostname of the origin archived system.
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:
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 name on deployment is formed from this name with the string -recovery appended to it.
On archive redeployment, the active BE is modified to match the target environment. In case of recovery archives, in order to preserve the original active BE for comparison and/or reference purposes the modifications are performed on the clone of that BE which is then activated.
The name of the AI media associated with this archived system.
The brand of the zone that is archived.
The name of this system.
The OS branch of osnet-incorporation. For example, '11.4.0.0.0.55.0'.
The version of Oracle Solaris installed on this system. For example, '11.4'.
'Yes' if this system contains only root data; Otherwise 'No'.
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.
The 128-bit unique identifier for this system.
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.
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.
The create-media command is used to create bootable media from a root-only 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 relative or absolute.
This subcommand must be used on a release of the Oracle Solaris operating system that matches the release included within the Unified Archive. If the archive has Oracle Solaris 11.4 in it, then the system this subcommand is executed on must also be Oracle Solaris 11.4.
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.
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 an absolute 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.
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.
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.
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.
The name of the resulting media image file. If not provided, a default name is used.
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.
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.uarExample 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.uarExample 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.uarExample 4 Creating an Archive With Excluded Zones
This example creates an archive excluding the 'zone3' and 'zone4' zones.
# archiveadm create -Z zone3,zone4 ./archive.uarExample 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.uarExample 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.uarExample 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.uarExample 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.uarExample 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.uarExample 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.uarExample 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.uarExample 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,sys4Example 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 solarisExample 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
See attributes(7) for descriptions of the following attributes:
|