I've updated the document to incorporate the comments received
(thanks!), and the things I found in implementation.  In particular,
I'm now using "set -F mountpoint" rather than "-f" so that it's
consistent with the other commands.

And I added a fix to the parseable output format (a nit, I hope) to
the end of the list.

A variation of this document has been submitted for PSARC review.  In
it, I removed some of the references to the code itself, and added
stability levels.  Both variants are attached.

-- 
James Carlson, KISS Network                    <[EMAIL PROTECTED]>
Sun Microsystems / 1 Network Drive         71.232W   Vox +1 781 442 2084
MS UBUR02-212 / Burlington MA 01803-2757   42.496N   Fax +1 781 442 1677

Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.

# ident "@(#)new-on-features.txt        1.5     06/06/09 SMI"

Background
----------

  The changes described in lu-icf-design.txt and lumount-design.txt
  assume a certain amount of functionality from within the Operating
  System / Networking (ON) consolidation.  Currently, these features
  are not present in ON, and the Zulu project contains kludges to work
  around these feature gaps.  These kludges must be removed and
  replaced with supported ON features, or the Install gate (and Zulu)
  will be faced with complex dependencies on ON internal data
  structures and file formats.


Features In Zonecfg
-------------------

  -R <root>

    As with the other zones-related utilities, zonecfg needs a "-R"
    option to invoke zonecfg_set_root().  This is used in many of the
    functions below, and is a generic feature.  (It will likely also
    be used to deliver the ipge/e1000g transition, so it should be
    integrated separately from Zulu.)

    One of the risks with this feature is that the zones configuration
    files in the alternate root specified might not be the same
    (private) version as the running system.  The existing "-R"
    option on zoneadm also has this issue.  For this reason, the
    new option should remain (contracted) private at this point.

    In the future, though, administrative control over inactive boot
    environments seems like a highly desirable and useful feature.
    Having this feature (or something like it) become stable enough
    for general customer use should be a goal.

  set -F zonepath=<path>

    This new flag (-F) allows lucopy to change the path of a zone
    after performing the copy operation.  Unlike the regular "set
    zonepath" operation, it does not check the zone state; it "forces"
    the operation.  Unlike the existing "zoneadm move" command, the
    actual data are not moved or copied, just the path recorded in the
    database is changed.

    Note that the path given must be absolute; meaning that it must
    include the path to the alternate root itself.  The path printed
    by "zonecfg -R <root> -z <zone> info zonepath" will also be
    absolute and start with the alternate root.  For instance:

        # zonecfg -R /.alt.lu-test2 -z embed info zonepath
        zonepath: /.alt.lu-test2/export/home/embed-lu-test2
        # zonecfg -R /.alt.lu-test2 -z embed set -F \
            zonepath=/.alt.lu-test2/export/home/embed-lu-test2
        # 

    This is consistent with the existing zoneadm features that print
    zone roots in absolute terms.

    This should be a private feature as it relies on actions (copying
    zone data) that can't necessarily be supported in this manner.
    The documented way to change a zone path is via the "zoneadm move"
    option.

    This is used only in the case zones that exist on shared file
    systems.  Zones on unshared file systems do not change in path
    during LU operations.  Thus, it will be limited to just the "-R"
    case and won't allow the path on the running system to be altered.

    It is expected that when ZFS is integrated into Install, Zones
    using ZFS will have substantially different features (using
    snapshot/clone operations) and will thus be able to avoid path
    changes.


Features In Zoneadm
-------------------

  zoneadm [-R path] -z zone state incomplete

    This allows lucopy to mark damaged zones (those that cannot be
    replicated properly) as 'incomplete'.  It's probably a useful
    feature in general for administrative software that uses Zones
    under the covers, so making it public seems reasonable.

  zoneadm [-u uuid-match] list

    Two separate features are added to the "list" subfunction to
    enable matching based on UUID (universally unique identifiers).
    The zone UUID is used to ensure that the zone against which we're
    synchronizing is the same one that we previously copied.

    The separate identifier is needed because zones can be uninstalled
    and reinstalled under the same name (with different contents), and
    can be renamed (without changing contents).  The zone name is thus
    an unstable handle for the zone.

    Note that because S10 shipped without UUIDs on zones, and because
    of CR 6379341, inactive BEs may not necessarily have values to
    match.  Any running system with this new feature will
    (necessarily) have the fix for those problems, and thus have
    reliable UUIDs.

    -u uuid-match

      This feature enables matching based on the UUID.  If the UUID
      string to match is zero-length, then it is treated as though the
      option were not present.  (I.e., it has no effect.)

      If both -u and -z are present, then the match is done based on
      the UUID first.  If a zone with the specified UUID is found, it
      is used, and the -z parameter is ignored.  If no zone is found
      by UUID, then the system searches by zone name instead.

      This matching logic is identical to the existing "/b" mount
      logic in zoneadmd that provides access to the running zone from
      within a scratch zone.  It is possible for the user to go out of
      his way to fool this logic, but the result can only be a false
      match against an uninstalled zone (lacking a UUID), and no
      synchronization is ever done (or possible) with an uninstalled
      zone.

      Note that the option preceeds the subcommand because the "-z"
      option also preceeds the subcommand.  Standard style would place
      the option after the subcommand, but adding a new feature that's
      logically similar but differing in usage would be more
      confusing.

    list

      The UUID is added as the fifth field (after path) in the
      "zoneadm list -p" output.  It is not administratively
      significant, and thus is not listed with "zoneadm list -v."

      With one minor vplat simplification (creating a dummy
      /etc/zones/index entry inside the zone), this fixes CR 6365741
      as well, and thus should be publicly documented.  The
      implementation will do a zone_enter() and then open and write to
      that file.  No special handling (e.g., enforcing read-only via
      lofs) is expected to be needed.

      Creating this file will allow the non-global zone user to issue
      "zoneadm list -p" and discover his UUID.  As per CR 6365741, the
      user can then deal with the UUID however he pleases, provided
      that he understands its limitations.  (In particular,
      uninstalling a zone means that its UUID changes.  Renames and
      upgrades do not change the UUID.)

      Note that there's no security issue in allowing root within the
      zone to overwrite this file.  Such a user can already use
      LD_PRELOAD and other tricks to fake the contents of this file,
      so having that user overwrite the file directly introduces no
      new vulnerabilities.  The UUID is not (and cannot be made)
      "secure" within the zone, for the same reason that the hostid
      isn't "secure" anywhere.

  zoneadm list -p

    The output format for this feature is not always parseable, though
    it was documented that way.

    6431731 zoneadm list -p (parseable) output isn't

    Part of this project will be to make the output parseable so that
    the UUID can be extracted reliably, and document the escaping
    mechanism.  If the path name contains embedded colons, those will
    be escaped using "\:" in the output.  This allows the resulting
    string to be parsed properly using "IFS=: read" in the shell,
    which respects that form of escaping.

    Note that since the existing output format doesn't properly
    support its own field delimiters, it seems unlikely that any
    customer has come to depend on this problem.


Issues
------

  Should the list -p output default to omitting the UUID value, at
  least in a patch release due to CR 6431731?  If so, we'll need a
  way ("list -pu"?) to enable it there.
I'm sponsoring this fast-track request for myself.  The timer is set
to 06/16/2006.

The release binding asserted is "Patch/Micro."  The stability of the
interfaces varies (see below).  The final change documented (for
parseable output) is the only one that stretches the meaning of patch
binding; please pay particular attention to that.

The document described here is a derivative of a proposal that has
been circulated in the Zones and Zulu communities, and reflects input
from them.  It's not identical, as I've redrafted it for this
audience, so please do read closely if you saw the other version.


Background
----------

  The changes described in "Zones Upgrade Permanent Solution (Zulu)"
  (PSARC 2006/167) assume a certain amount of functionality from
  within the Operating System / Networking (ON) consolidation.
  Without these features, the Install gate (and Zulu) will be faced
  with complex dependencies on ON internal data structures and file
  formats.

  Currently, Install does have access to private ON interfaces, via
  contracts established in "Admin/Install Zones Support" (PSARC
  2003/460).  One of the goals of this project is to minimize any new
  library dependencies and, to the extent possible, pave the way for
  removing all of them in the future.


Features In Zonecfg
-------------------

  -R <root>

    Contracted Consolidation Private

    As with the other zones-related utilities, zonecfg needs a "-R"
    option to access alternate root environments.  For the time being,
    the access to this option will be kept under wraps.  An updated
    contract for this interface will be deposited with this case.

    One of the risks with this feature is that the zones configuration
    files in the alternate root specified might not be the same
    (private) version as the running system.  The existing "-R"
    option on zoneadm also has this issue, and the problem is at least
    centralized in libzonecfg.

    A future project may complete this functionality and promote it as
    a stable interface.

  set -F zonepath=<path>

    Contracted Project Private

    This new flag (-F) allows lucopy to change the path of a zone
    after performing the copy operation.  Unlike the regular "set
    zonepath" operation, it does not check the zone state; it "forces"
    the operation.  Unlike the existing "zoneadm move" command, the
    actual data are not moved or copied, just the path recorded in the
    database is changed.

    Note that the path given must be absolute; meaning that it must
    include the path to the alternate root itself.  The path printed
    by "zonecfg -R <root> -z <zone> info zonepath" will also be
    absolute and start with the alternate root.

    This should be a private feature as it relies on actions (copying
    zone data) that can't necessarily be supported in this manner.
    The documented way to change a zone path is via the "zoneadm move"
    option.

    This is used only in the case zones that exist on shared file
    systems.  Zones on unshared file systems do not change in path
    during LU operations.  Thus, it will be limited to just the "-R"
    case and won't allow the path on the running system to be altered.

    It is expected that when ZFS is integrated into Install, Zones
    using ZFS will have substantially different features (using
    snapshot/clone operations) and will thus be able to avoid path
    changes.


Features In Zoneadm
-------------------

  zoneadm [-R path] -z zone state incomplete

    Stable

    This allows lucopy to mark damaged zones (those that cannot be
    replicated properly) as 'incomplete'.  It's probably a useful
    feature in general for administrative software that uses Zones
    under the covers, so making it public seems reasonable.

    Note that only the "state" and "list" subcommands will be
    documented as supporting this "-R" option.  The mount/unmount
    subcommands introduced by Ashanti (PSARC 2005/474) are still not
    ready for wider use.

  zoneadm [-u uuid-match] list

    Stable

    Two separate features are added to the "list" subfunction to
    enable matching based on UUID (universally unique identifiers).
    The zone UUID is used to ensure that the zone against which we're
    synchronizing is the same one that we previously copied.

    Both features described here will work in the global zone and in
    non-global zones.  Naturally, the non-global zones will only be
    able to access information about themselves, and not about any
    other zone on the system.

    The separate identifier is needed because zones can be uninstalled
    and reinstalled under the same name (with different contents), and
    can be renamed (without changing contents).  The zone name is thus
    an unstable handle for the zone.

    Note that because S10 shipped without UUIDs on zones, and because
    of CR 6379341, inactive BEs may not necessarily have values to
    match.  Any running system with this new feature will
    (necessarily) have the fix for those problems, and thus have
    reliable UUIDs.

    -u uuid-match

      This feature enables matching based on the UUID.  If the UUID
      string to match is zero-length, then it is treated as though the
      option were not present.  (I.e., it has no effect.)

      If both -u and -z are present, then the match is done based on
      the UUID first.  If a zone with the specified UUID is found, it
      is used, and the -z parameter is ignored.  If no zone is found
      by UUID, then the system searches by zone name instead.

      This matching logic is identical to the existing "/b" mount
      logic in zoneadmd that provides access to the running zone from
      within a scratch zone.  It is possible for the user to go out of
      his way to fool this logic, but the result can only be a false
      match against an uninstalled zone (lacking a UUID), and no
      synchronization is ever done (or possible) with an uninstalled
      zone.

      Note that the option preceeds the subcommand because the "-z"
      option also preceeds the subcommand.  Standard style would place
      the option after the subcommand, but adding a new feature that's
      logically similar but differing in usage would be more
      confusing.

    list

      The UUID is added as the fifth field (after path) in the
      "zoneadm list -p" output.  It is not administratively
      significant, and thus is not listed with "zoneadm list -v."

      By allowing this to work in non-global zones, this feature also
      fixes:

        6365741 RFE: add unique identifier to facilitate asset
                tracking (similar to hostid)

  zoneadm list -p

    Stable

    The output format for this feature is not always parseable, though
    it was documented that way.

    6431731 zoneadm list -p (parseable) output isn't

    Part of this project will be to make the output parseable so that
    the UUID can be extracted reliably, and document the escaping
    mechanism.  If the path name contains embedded colons, those will
    be escaped using "\:" in the output.  This allows the resulting
    string to be parsed properly using "IFS=: read" in the shell,
    which respects that form of escaping.

    Note that since the existing output format doesn't properly
    support its own field delimiters, it seems unlikely that any
    customer has come to depend on this problem.
_______________________________________________
zones-discuss mailing list
zones-discuss@opensolaris.org

Reply via email to