archiveadm - 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] [ --root-only] info <archive name> [-p|--parseable] [-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>]
The archiveadm utility provides users with functionality to create system archive images of a running 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 a Solaris Unified Archive. A Solaris Unified Archive is a multi-system archive based upon 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.
Once created, Solaris Unified Archives may be deployed by the Solaris Automated Installer or by the Solaris Zones software utilities.
During 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 Solaris Zones deployments from a host system, the zonecfg(1M) and zoneadm(1M) utilities are used. New zones may be configured by using zonecfg(1M) to extract configuration data from a Solaris Unified Archive. The zoneadm(1M) utility may be used to install a zone directly from the archive. Zones may also be installed as part of a new Solaris Automated Installer deployment along with the global zone.
By default, 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 archive creation, specific systems may be explicitly included in an archive which is being created, which implicitly excludes all others. Inversely systems may be excluded, implicitly including all others.
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, any system not explicitly excluded is included.
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.3.
The dev-init tag introduced in Oracle Solaris 11.2 is being transitioned to system:dev-init. A future release of Oracle Solaris may remove the dev-init revert tag. Software that needs to use the functionality provided by either of these tags and needs to be portable across Oracle Solaris 11 and later releases should use both the dev-init and system:dev-init revert tags.
Only ZFS data is archived, and the data on other file system types such as tmpfs(7FS) and ufs(7FS) 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(5) and zonecfg(1M).
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.
An archive may be optionally created which contains only data 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.
Bootable installation media may be created from a 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 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.
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 global zone in the Unified Archive. This media is created per global zone 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.
The info command will provide information about the content of a 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 origin systems such as hostname, architecture and 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 Solaris installed, and the size needed to deploy each system archive. Also shown in verbose mode is the unique ID (UUID) of the Unified Archive file, and 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 parseable 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 parseable outputs include headers which label the outputs.
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 in recreating the storage configuration for an AI manifest. The manifest content is shown in XML so that it may be used with little modification.
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 hostname of the origin archived system.
The creation timestamp (UTC) of this unified archive.
'sparc' or 'i386'.
Solaris name. For example, 'Oracle Solaris 11.0 X86'.
'Yes' if the archive type is 'recovery'; otherwise 'No'.
The 128-bit unique identifier for this unified archive.
The version of this unified archive.
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 this system.
The version of Oracle Solaris installed on this system. For example, '5.11'.
The os branch of osnet-incorporation. For example, '18.104.22.168.0.1.0'.
The name of the active boot environments on this system.
The brand of the zone that is archived.
The size needed to deploy this system.
The 128-bit unique identifier for this system.
The name of the AI media associ- ated with this asrchived system.
'Yes' if this system contains only root data; Otherwise 'No'.
This option specifies the names of the deployable system archives. When the –o option is used to display the Native System Properties, the systems must be specified explicitly with the –s option.
This 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.
The –o option is required with the –s option.
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 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.
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 the 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.
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 Retrieving Basic Archive Information
This example retrieves basic information related to the archive.
# archiveadm info ./archive.uar Archive Information Creation Time: 2012-09-29T01:29:29Z Source Host: osai-brm-x-5 Architecture: i386 Operating System: Oracle Solaris 12.0 X86 Deployable Systems: global,zone1Example 7 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: 2012-09-29T01:29:29Z Source Host: osai-brm-x-5 Architecture: i386 Operating System: Oracle Solaris 12.0 X86 Unique ID: d1689f79-0bca-6cea-e06c-f335e98006f0 Archive Version: 1 Deployable Systems 'global' OS Version: 5.12 OS Branch: 22.214.171.124.0.5.2 Active BE: on12_05-ref Brand: solaris Size Needed: 21.44GB Unique ID: 73ec33b8-55c2-6291-cabd-943f3b1c359e 'zone1' OS Version: 126.96.36.199.0.5.2 Active BE: solaris-6 Brand: solaris Size Needed: 345.90MB Unique ID: 2ef3e063-764b-c756-b58d-a778dd18a00cExample 8 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 9 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(1M) command. The AI image components will be sourced from the current list of IPS publishers.
# archiveadm create-media ./archive.uarExample 10 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 11 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 12 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 13 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 14 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 sys3 solaris-3 solarisExample 15 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(5) for descriptions of the following attributes: