Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

sysadm(8)

Name

sysadm - maintain host

Synopsis

sysadm maintain -s [ -m "message" ]

sysadm maintain -l [-p] [-o field1,...]

sysadm maintain -e

sysadm evacuate [-arnvqw]

sysadm evacuate -l [-p] [-o field1,...]

Description

The sysadm utility is used to control maintenance mode for a system and perform evacuation of zones hosted on the system.

Only users and roles that belong to the "Maintenance and Repair" RBAC profile can use the sysadm command.

Starting a maintenance mode will log an audit record and prevent the subsequent attach, boot, or incoming migration of any zones into the system. This can be used to perform administration on a zones host and remove it from service.

Maintenance state is held across host reboots and changes between different boot environments.

To bring zones back into service, maintenance must be ended with the –e option.

Optionally, the host may be evacuated by migrating all solaris-kz, solaris and solaris10 brand zones away from the system. A non-interactive RAD URI of the destination zones host must be given in the evacuation/target property of the zone instance. A default destination host may also be specified on the zone service svc:/system/zones/zone.

Sub Commands

The following subcommands are supported:

sysadm maintain –s [ –m "message" ]

Starts maintenance. An optional free-form message string may be given.

Starting maintenance clears any existing evacuation state.

sysadm maintain –l [–p] [–o field1,...]

Lists maintenance state if any.

–o field[,...], –-output=field[,...]

A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all to display all fields.

TYPE

The type of maintenance. Currently, always the value admin.

USER

The user who sets the maintenance mode.

DATE

The date when the maintenance mode is set.

MESSAGE

Any message associated with the maintenance mode.

–p

Displays using a stable machine-parseable format. The –o option is required with the –p option.

sysadm maintain –e

Ends maintenance mode.

sysadm evacuate –l [–p] [–o field1,...]

Lists any evacuation state. After a partial evacuation, this may show zones evacuated to destination systems, as well as zones that failed to evacuate, along with the reason for the failure.

–o field[,...], –-output=field[,...]

A case-insensitive, comma-separated list of output fields to display. The field name must be one of the fields listed below, or the special value all to display all fields.

ZONENAME

Name of the zone.

STATE

The state of evacuation for the zone. If EVACUATED, then the zone is evacuated to the location specified by the DEST value. If SKIPPED, then the evacuation is not attempted, and the zone may still be running. If FAILED, then the evacuation failed, and the ERROR field will give more information.

DEST

The destination RAD URI that the zone is evacuated to, or the last attempted destination if FAILED.

ERROR

If the state is either SKIPPED or FAILED, then this gives the relevant error status.

–p

Displays using a stable machine-parseable format. The –o option is required with the –p option.

sysadm evacuate [–arnvq]

Evacuates the host system. Or, with the –r option, returns zones to the host.

For each running zone, evacuation live migrates the zone to the destination configured in its SMF service instance.

If an individual zone is of a brand that does not support live migration, then evacuation is skipped and the state for that zone will be SKIPPED.

If the –a option is specified, then non-running zones are also evacuated by using cold migration.

If an individual zone fails to evacuate, then the state for that zone will be FAILED, and the ERROR value will be filled in with more information.

–a

Evacuates both non-running zones as well as running zones.

–v [–v]

Reports evacuation progress verbosely to the standard output. Each output line has a timestamp.

When the –v option is doubled, the detailed per zone migration progress is reported too.

–q

Only reports errors.

–n

Dry-run evacuation. Migration is planned, and a dry-run migration to the destination host is performed for each zone.

–r

Returns zones. Each evacuated zone is migrated from its destination, if it is still running there, back to the source host. If the –a option is specified, it is cold migrated back if not running.

–w

Overwrite zone configuration for each evacuated zone on the destination host with the respective configurations from the source host. This is mutually exclusive with the –n option.

Evacuation may be run several times, in case some zones fail to evacuate on the first run. The return status is successful only if the evacuation as a whole is complete. This means that there should be no zones running on the relevant hosts after executing the sysadm command.

Examples

Example 1 Starting Maintenance
# sysadm maintain -s -m "doing a pkg update"
# sysadm maintain -l
TYPE  USER       DATE             MESSAGE
admin root       2016-01-25 06:01 doing a pkg update
Example 2 Evacuating a System to a Single Default Destination
# svccfg -s svc:/system/zones/zone        
svc:/system/zones/zone> setprop evacuation/target = astring: "ssh://desthost/"
svc:/system/zones/zone> refresh
svc:/system/zones/zone> exit

# sysadm evacuate -nv
sysadm: preparing 2 zone(s) for evacuation ...
       sysadm: initializing migration of kzone1 to desthost ...
       sysadm: initializing migration of kzone2 to desthost ...
sysadm: kzone1: planned evacuation to ssh://desthost/
sysadm: kzone2: planned evacuation to ssh://desthost/
sysadm: dry-run succeeded

# sysadm evacuate    
sysadm: preparing zones for evacuation ... 2/2
sysadm: evacuating zones ... 2/2
sysadm: evacuation completed successfully.
		
# sysadm evacuate -l -o all
ZONENAME         STATE     DEST                                     ERROR
kzone1          EVACUATED ssh://desthost/                            -
kzone2          EVACUATED ssh://desthost/                            -
Example 3 Clearing Maintenance State and Returning an Evacuation
# sysadm maintain -e
# sysadm evacuate -r
sysadm: preparing zones for return ... 2/2
sysadm: returning zones ... 2/2
sysadm: return completed successfully.

# sysadm evacuate -l
sysadm: no active evacuation

# zoneadm list -civ
  ID NAME             STATUS      PATH                         BRAND      IP    
   0 global           running     /                            solaris    shared
   3 kzone2           running     -                            solaris-kz excl  
   4 kzone1           running     -                            solaris-kz excl  
Example 4 Getting the detailed evacuation progress messages.
# sysadm evacuate -vv
2021-09-09 10:38:26.844 sysadm: preparing 2 zone(s) for evacuation ...
2021-09-09 10:38:27.555 sysadm: initializing migration of kzone1 to desthost ...
2021-09-09 10:38:28.209 sysadm: initializing migration of kzone2 to desthost ...
2021-09-09 10:38:44.773 sysadm: evacuating 2 zone(s) ...
2021-09-09 10:38:44.773 sysadm: migrating kzone2 to desthost ...
2021-09-09 10:38:44.774 sysadm: migrating kzone1 to desthost ...
2021-09-09 10:38:44.792 sysadm: kzone2: Performing initial copy (total 4096MB).
2021-09-09 10:38:44.792 sysadm: kzone1: Performing initial copy (total 4096MB).
2021-09-09 10:38:44.847 sysadm: kzone2: 0.00% done: 0MB copied @ 0.0MB/s, skipped 0MB
2021-09-09 10:38:44.861 sysadm: kzone1: 0.00% done: 0MB copied @ 0.0MB/s, skipped 0MB
2021-09-09 10:38:49.848 sysadm: kzone2: 37.30% done: 768MB copied @ 153.6MB/s, skipped 759MB
2021-09-09 10:38:49.862 sysadm: kzone1: 49.11% done: 704MB copied @ 140.8MB/s, skipped 1307MB
2021-09-09 10:38:54.848 sysadm: kzone2: 63.48% done: 1600MB copied @ 166.4MB/s, skipped 1000MB
2021-09-09 10:38:54.863 sysadm: kzone1: 97.53% done: 1415MB copied @ 142.2MB/s, skipped 2578MB
2021-09-09 10:38:59.849 sysadm: kzone2: 96.73% done: 2342MB copied @ 148.4MB/s, skipped 1619MB
2021-09-09 10:38:59.864 sysadm: kzone1: 100.00% done: 1508MB copied @ 18.4MB/s, skipped 2587MB
2021-09-09 10:38:59.867 sysadm: kzone1: Performing copy of recently modified memory.
2021-09-09 10:38:59.883 sysadm: kzone1: Suspending zone on source host.
2021-09-09 10:39:00.509 sysadm: kzone1: Waiting for migration to complete.
2021-09-09 10:39:00.510 sysadm: kzone1: Halting and detaching zone on source host.
2021-09-09 10:39:00.512 sysadm: kzone1: Migration successful.
2021-09-09 10:39:04.850 sysadm: kzone2: 100.00% done: 2465MB copied @ 24.6MB/s, skipped 1630MB
2021-09-09 10:39:04.852 sysadm: kzone2: Performing copy of recently modified memory.
2021-09-09 10:39:04.862 sysadm: kzone2: Suspending zone on source host.
2021-09-09 10:39:05.284 sysadm: kzone2: Waiting for migration to complete.
2021-09-09 10:39:06.286 sysadm: kzone2: Migration successful.
2021-09-09 10:39:06.287 sysadm: kzone2: Halting and detaching zone on source host.
2021-09-09 10:39:07.124 sysadm: kzone1: evacuated to ssh://desthost/
2021-09-09 10:39:07.124 sysadm: kzone2: evacuated to ssh://desthost/
2021-09-09 10:39:07.124 sysadm: evacuation completed successfully.
      

Exit Status

The following exit values are returned:

0

Successful completion.

For evacuation, this exit value means that no zones are still running on the source system. For evacuation return, this exit value means that all zones have been migrated back to the source system.

1

An error occurred.

CAVEATS

When SSH transport is used, the sysadm utility requires the SSH keys to have empty passphrase to ensure non-interactive evacuation of the zones and their eventual returning. Unlike zoneadm(8), the sysadm utility ignores the SSH_AUTH_SOCK environment variable.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
See below.
- CLI options
Committed
- Parsable output of sysadm evacuate -l
Committed
- Human readable and verbose output
Not-an-Interface
Availability
system/zones

See Also

zones(7), solaris-kz(7), solaris(7), rad(8), beadm(8), svc.zones(8)