xref: /titanic_41/usr/src/lib/libbrand/dtd/brand.dtd.1 (revision 63b4189d887d23563c10f979d5303b207c7c078e)

<?xml version='1.0' encoding='UTF-8' ?>

<!--
 CDDL HEADER START

 The contents of this file are subject to the terms of the
 Common Development and Distribution License (the "License").
 You may not use this file except in compliance with the License.

 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 or http://www.opensolaris.org/os/licensing.
 See the License for the specific language governing permissions
 and limitations under the License.

 When distributing Covered Code, include this CDDL HEADER in each
 file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 If applicable, add the following below this CDDL HEADER, with the
 fields enclosed by brackets "[]" replaced with your own identifying
 information: Portions Copyright [yyyy] [name of copyright owner]

 CDDL HEADER END

 Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.
 Copyright (c) 2011, Joyent, Inc. All rights reserved.

 DO NOT EDIT THIS FILE.

 Copyright 2014 Nexenta Systems, Inc. All rights reserved.
-->

<!--
  verify_cfg

    Identifies the program to be invoked by zonecfg to verify that the
    zone's configuration is legal, and that all the configured devices,
    attributes, etc. are legal for this brand.

    The program is called with a single argument: the path to a file
    containing a temporary config.xml file the zone.  It should return 0
    on success and non-0 on failure.  Any detailed error messages should be
    displayed to stderr.

    It has no attributes.

-->
<!ELEMENT verify_cfg	(#PCDATA) >
<!ATTLIST verify_cfg>
<!--
  verify_adm

    Identifies the program invoked by zoneadm to perform brand-specific
    checks as to the viability of a zone on this specific machine.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    The program should return 0 on success and non-0 on failure.  Any
    detailed error messages should be displayed to stderr.

    It has no attributes.

-->
<!ELEMENT verify_adm	(#PCDATA) >
<!ATTLIST verify_adm>

<!--
  install

    Identifies the program to invoke when installing a zone.  The following
    replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT install	(#PCDATA) >
<!ATTLIST install>

<!--
  installopts

    Identifies the command-line options supported by the brand's
    installation program, allowing zoneadm to parse the install line
    properly.

    It has no attributes.
-->
<!ELEMENT installopts	(#PCDATA) >
<!ATTLIST installopts>

<!--
  boot

    This is a program which gets run by zoneadmd when a zone is booted.
    The program will be invoked as the last step in the zone booting
    process before the the first process is spawned inside the zone.

    If this programs succeeds it should not generate any output.
    If this program returns an error, any output generated by the
    program will be sent to the zoneadmd message log.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT boot	(#PCDATA) >
<!ATTLIST boot>

<!--
  sysboot

    This is a program that will be run by zoneadm during system boot for an
    installed zone that won't automatically boot.

    If the program succeeds, then it should not generate output.
    If the program returns an error, then the output it generates will be
    sent to the zones SMF service's message log.

    The following replacements are performed:

      %z	Name of the target zone
      %R	Zonepath of the target zone
      Additional arguments, if any, are appended.

    This element has no attributes.
-->
<!ELEMENT sysboot	(#PCDATA) >
<!ATTLIST sysboot>

<!--
  halt

    This is a program which gets run by zoneadmd when a zone is being
    halted.  This callback is provided to allow a brand to cleanup any
    special configuration that was setup during boot.

    This program will also be invoked by zoneadmd if any part of the zone
    booting process fail, even if the booting process failed before the
    brand boot program was invoked.  It is also possible that if the zone
    fails to halt after invoking this program, future attempts to halt the
    zone will invoke this program again.  So this program should be
    designed to clean up any resources allocated to a zone but it should
    also be able to gracefully handle the case where resources that it
    expects to release are not actually allocated (or have been already
    released.)

    If this programs succeeds it should not generate any output.  If this
    program returns an error, any output generated by the program will be
    sent to the zoneadmd message log.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT halt	(#PCDATA) >
<!ATTLIST halt>

<!--
  shutdown

    This is a program which gets run by zoneadmd when a zone is being
    shutdown gracefully. Currently only asynchronous mode is supported.

    If this program succeeds it should not generate any output. If this
    program returns an error, any output generated by the program will be
    sent to the zoneadmd message log.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT shutdown	(#PCDATA) >
<!ATTLIST shutdown>

<!--
  modname

    Path to the kernel module that implements the kernel-level
    functionality of the brand.

    It has no attributes.
-->
<!ELEMENT modname	(#PCDATA) >
<!ATTLIST modname>

<!--
  initname

    Path to the initial executable that should be launched when booting a
    branded zone.

    It has no attributes.
-->
<!ELEMENT initname	(#PCDATA) >
<!ATTLIST initname>

<!--
  restartinit

    Boolean indicating that the program specified by the initname attr
    should be restarted, or not, if it exits.  By default, the init program
    will be restarted if this attribute is not provided.  Specifying false
    for this attr will prevent that.

    It has no attributes.
-->
<!ELEMENT restartinit	(#PCDATA) >
<!ATTLIST restartinit>

<!--
  login_cmd

    Path to the initial login binary that should be executed when
    attempting to zlogin into a branded zone.

    The following replacements are performed:

      %Z	Name of the current zone
      %u	User login name

    It has no attributes.
-->
<!ELEMENT login_cmd	(#PCDATA) >
<!ATTLIST login_cmd>

<!--
  forcedlogin_cmd

    Path to the initial login binary that should be executed when
    attempting to zlogin into a branded zone without authentication.

    The following replacements are performed:

      %Z	Name of the current zone
      %u	User login name

    It has no attributes.
-->
<!ELEMENT forcedlogin_cmd	(#PCDATA) >
<!ATTLIST forcedlogin_cmd>

<!--
  user_cmd

    Path to the binary that will translate a user name to a passwd(4) entry.

    The following replacements are performed:

      %u        User login name

    It has no attributes.  The passwd(4) entry is used to determine $LOGNAME,
    $HOME, and $SHELL for non-interactive "zlogin -l <user> <cmd>".
-->
<!ELEMENT user_cmd   (#PCDATA) >
<!ATTLIST user_cmd>

<!--
  attach

    Path to a hook that will perform any necessary processing on
    a zone to allow it to be attached.  The zone will be in the "configured"
    state when this hook is run.  This hook is never called when the zone
    is "force attached" (-F).

    If this hook exits with a non-zero exit status, the attach operation
    will fail.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    If no hook is provided, the internal zoneadm attach code will be used.

    It has no attributes.
-->
<!ELEMENT attach	(#PCDATA) >
<!ATTLIST attach>

<!--
  postattach

    Path to a hook that will perform any necessary post-processing on
    a zone after it has been attached.  The zone will be in the "installed"
    state when this hook is run.  This hook is never called when the zone
    is "force attached" (-F).

    If this hook exits with a non-zero exit status, the attach operation
    will fail and the zone state will be reset to "configured".

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT postattach	(#PCDATA) >
<!ATTLIST postattach>

<!--
  postclone

    Path to a hook that will perform any necessary post-processing on
    a zone after it has been cloned.  The zone will be in the "incomplete"
    state when this hook is run.

    If this hook exits with a non-zero exit status, the clone operation
    will fail and the zone will be left in the "incomplete" state,
    otherwise the state will be changed to the "installed" state.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT postclone	(#PCDATA) >
<!ATTLIST postclone>

<!--
  postinstall

    Path to a script that will perform any necessary post-processing on
    a zone after it has been freshly installed.  This hook will run after the
    install hook completes and the zone is in the installed state.  The
    additional arguments are the same as what is passed to the install hook.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT postinstall	(#PCDATA) >
<!ATTLIST postinstall>

<!--
  predetach

    Path to a hook that will perform any necessary pre-processing on
    a zone before it is detached.  The zone will be in the "installed"
    state when this hook is run.

    It is possible that if the zone fails to detach after invoking this
    hook, future attempts to detach the zone will invoke this hook again.
    So this hook should be designed to gracefully handle the case where
    it is run multiple times on the same zone.  If this hook exits with
    a non-zero exit status, the detach operation will fail.

    This hook is most commonly used when there is pre-processing for detaching
    a zone but the built-in detach support will be used for the actual
    detach.  Otherwise, if a detach hook is provided, then it can be used
    to do both preprocessing as well as the actual detach.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT predetach	(#PCDATA) >
<!ATTLIST predetach>

<!--
  detach

    Path to a hook that will perform any necessary processing on
    a zone to allow it to be detached.  The zone will be in the "installed"
    state when this hook is run.

    It is possible that if the zone fails to detach while running this
    hook, future attempts to detach the zone will invoke this hook again.
    So this hook should be designed to gracefully handle the case where
    it is run multiple times on the same zone.  If this hook exits with
    a non-zero exit status, the detach operation will fail and the zone will
    be left in the "installed" state, otherwise the state will be changed
    to "configured".

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    If no hook is provided, the internal zoneadm detach code will be used.

    It has no attributes.
-->
<!ELEMENT detach	(#PCDATA) >
<!ATTLIST detach>

<!--
  clone
    Path to a hook that will perform any necessary processing on a zone to
    allow it to be installed via cloning.  Cloning is an alternative to
    installing so this hook should result in the same effect for the zone.
    The zone will be in the "incomplete" state when this hook is run.

    If this hook exits with a non-zero exit status, the clone operation
    will fail and the zone will be left in the "incomplete" state, otherwise
    the state will be changed to "installed".

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      1st arg   name of source zone
      Additional arguments, if any, are appended.

    If no hook is provided, the internal zoneadm cloning code will be used.
-->
<!ELEMENT clone	(#PCDATA) >
<!ATTLIST clone>

<!--
  preuninstall

    Path to a script that will perform any necessary pre-processing on
    a zone before it is uninstalled.  The zone will be in the "installed"
    state when this hook is run.

    It is possible that if the zone fails to uninstall after invoking this
    hook, future attempts to uninstall the zone will invoke this hook
    again.  So this hook should be designed to gracefully handle the case
    where it is run multiple times on the same zone.  If this hook exits
    with a non-zero exit status, the uninstall operation will fail.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    It has no attributes.
-->
<!ELEMENT preuninstall	(#PCDATA) >
<!ATTLIST preuninstall>

<!--
  uninstall
    Identifies the hook to invoke when uninstalling a zone.  The zone will
    be in the "incomplete" state when this hook is run.

    If this hook exits with a non-zero exit status, the uninstall operation
    will fail and the zone will be left in the "incomplete" state, otherwise
    the state will be changed to "configured".

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      Additional arguments, if any, are appended.

    If no hook is provided, the internal zoneadm uninstall code will be used.
-->
<!ELEMENT uninstall	(#PCDATA) >
<!ATTLIST uninstall>

<!--
  presnap
    Identifies the hook to invoke before snapshotting a zone using the
    built-in ZFS clone support.

    If this hook exits with a non-zero exit status, the snapshot operation
    will fail and the zfs clone operation will fail.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
-->
<!ELEMENT presnap	(#PCDATA) >
<!ATTLIST presnap>

<!--
  postsnap
    Identifies the hook to invoke after snapshotting a zone using the
    built-in ZFS clone support.

    If this hook exits with a non-zero exit status, the zfs clone operation
    will fail.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
-->
<!ELEMENT postsnap	(#PCDATA) >
<!ATTLIST postsnap>

<!--
  validatesnap
    Identifies the hook to invoke to validate a snapshot of a zone using the
    built-in ZFS clone support.  This will validate a snapshot that was
    explicitly specified to the clone command when the user wants to
    re-use a snapshot from an earlier clone operation.

    If this hook exits with a non-zero exit status, the snapshot validation
    operation will fail, meaning the zfs snapshot cannot be used to install
    the zone.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      1st arg   snapshot name
      2nd arg   snapshot path
-->
<!ELEMENT validatesnap	(#PCDATA) >
<!ATTLIST validatesnap>

<!--
  prestatechange
    Identifies the hook to invoke before zoneadmd makes a state change.
    If this hook exits with a non-zero exit status, the action failed
    and no further state change activity will take place.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      1st arg   integer representing current state of zone
			2 - installed
			3 - ready
			4 - running
			5 - shutting down
			6 - down
			7 - mounted
      2nd arg   integer representing transition command
			0 - ready
			1 - boot
			4 - halt
      3rd arg   Alternate root (zonepath is mounted under this root)
			empty string if zone not mounted under alternate root
-->
<!ELEMENT prestatechange	(#PCDATA) >
<!ATTLIST prestatechange>

<!--
  poststatechange
    Identifies the hook to invoke after zoneadmd makes a successful state
    change.  If this hook exits with a non-zero exit status, the action failed
    and zoneadmd treats the overall state change as failed, although
    all of the actions up to running the hook will have taken place.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
    See prestatechange comment for 1st, 2nd and 3rd argument values.
-->
<!ELEMENT poststatechange	(#PCDATA) >
<!ATTLIST poststatechange>

<!--
  query
    Identifies a hook which can be called to get brand-specific information
    about the zone.  There is no specific place in zones where this is called,
    calls within the zone infrastructure can be added as needed.

    One example of the use of this hook is to query the implicit ZFS datasets
    supported by the brand.

    If this hook exits with a non-zero exit status, the query failed,
    although in general, this hook shouldn't return non-zero.

    The following replacements are performed:

      %z	Name of zone
      %R	Zonepath of zone
      1st arg   Arbitrary string which the hook can use to determine what
		data to return.  Brands implementing this hook should be
		tolerant of arguments they don't support and simply do
		nothing.
-->
<!ELEMENT query	(#PCDATA) >
<!ATTLIST query>

<!--
  privilege

    Add a privilege to the default, prohibited, or required set for all
    zones of this brand with ip-type matched.  If a privilege is added
    to the default set all zones of this brand with ip-type matched on
    the system will inherit this privilege unless the privilege is
    removed via limitpriv in zonecfg(1m).  If a privilege is added to
    the prohibited set it can not be added to any zones with ip-type
    matched via limitpriv in zonecfg(1m).  If a privilege is added to
    the required set then all zones of this brand with ip-type matched
    on the system will inherit this privilege and it can't be removed via
    limitpriv in zonecfg(1m).

    Its attributes are
      set	The name of the set the privilege should go into.
      name	The name of the privilege.
      ip-type	Optional, indicates that adding of the privilege to the
		set only applies to certain IP types. Can be "shared" or
		"exclusive". If it is not specified, the default value
		"all" will be used, which means it is applicable regardless
		the IP type.

-->
<!ELEMENT privilege	(#PCDATA) >
<!ATTLIST privilege	set	( default | prohibited | required ) #REQUIRED
			name	CDATA #REQUIRED
			ip-type ( shared | exclusive ) "all" >

<!--
  brand

    The toplevel container for a brand configuration.

    Its attributes are

      name	The name of the brand.  This must match the name of the
		directory in which the configuration file is stored.
-->

<!ELEMENT brand		(modname?, initname, restartinit?, login_cmd,
			forcedlogin_cmd, user_cmd, install,
			installopts?, boot?, sysboot?, halt?, shutdown?,
			verify_cfg?, verify_adm?, postattach?, postclone?,
			postinstall?, predetach?, attach?, detach?, clone?,
			presnap?, postsnap?, validatesnap?,
			preuninstall?, uninstall?,
			prestatechange?, poststatechange?, query?,
			privilege+)>

<!ATTLIST brand		name		CDATA #REQUIRED>