clustertoc(4)                                                                                                                        clustertoc(4)

NAME

       clustertoc - cluster table of contents description file

       The  cluster  table of contents file, .clustertoc, is an ASCII file that describes a hierarchical view of a software product. A .clustertoc
       file is required for the base OS product. The file resides in the top-level directory containing the product.

       The hierarchy described by .clustertoc can be of arbitrary depth, although the initial system installation  programs  assume  that  it  has
       three  levels.  The hierarchy is described bottom-up, with the packages described in .packagetoc at the lowest layer. The next layer is the
       cluster layer which collects packages into functional units. The highest layer is the meta-cluster layer which collects packages and  clus-
       ters together into typical configurations.

       The  hierarchy exists to facilitate the selection or deselection of software for installation at varying levels of granularity. Interacting
       at the package level gives the finest level of control over what software is to be installed.

       Each entry in the .clustertoc file is a line that establishes the value of a parameter in the following form:

       PARAM=value

       A line starting with a pound-sign, ``#'', is considered a comment and is ignored.

       Parameters are grouped by cluster or meta-cluster. The start of a cluster description is defined by a line of the form:

       CLUSTER=value

       The start of a meta-cluster description is defined by a line of the form:

       METACLUSTER=value

       There is no order implied or assumed for specifying the parameters for a (meta-)cluster with the exception of the  CLUSTER  or  METACLUSTER
       parameter, which must appear first and the END parameter which must appear last.

       The following parameters are mandatory:

       CLUSTER

           The  cluster  identifier  (for  example,  SUNWCacc).  The identifier specified must be unique within the package and cluster identifier
           namespace defined by a product's .packagetoc and .clustertoc files. The identifiers used are subject to the same constraints  as  those
           for package identifiers. These constraints are (from pkginfo(4)):

           All  characters  in  the  abbreviation  must be alphanumeric and the first may not be numeric. The abbreviation is limited to a maximum
           length of nine characters. install, new, and all are reserved abbreviations.

           A cluster must be described before another cluster or meta-cluster may refer to it.

       DESC

           An informative textual description of the (meta-)cluster's contents. The length of the description supplied may not exceed 256  charac-
           ters. The text should contain no newlines.

       METACLUSTER

           The  metacluster identifier (for example, SUNWCprog). The identifier specified must be unique within the package and cluster identifier
           namespace defined by a product's .packagetoc and .clustertoc files. The identifiers used are subject to the same constraints  as  those
           for package identifiers. These constraints are (from pkginfo(4)):

           All  characters  in  the  abbreviation  must be alphanumeric and the first may not be numeric. The abbreviation is limited to a maximum
           length of nine characters. install, new, and all are reserved abbreviations.

           Meta-clusters can not contain references to other meta-clusters.

       NAME

           The full name of the (meta-)cluster. The length of the name string supplied may not exceed 256 characters.

       SUNW_CSRMEMBER

           Indicates that the package or cluster is a part of the (meta-) cluster currently being described. The value specified is the identifier
           of the package or cluster. There may be an arbitrary number of SUNW_CSRMEMBER parameters per (meta-)cluster.

       VENDOR

           The name of the (meta-)cluster's vendor. The length of the vendor string supplied may not exceed 256 characters.

       VERSION

           The version of the (meta-)cluster. The length of the version string supplied may not exceed 256 characters.

       The following parameters are optional:

       DEFAULT

           Specifies  which  metacluster  within  a  .clustertoc  file should be selected or installed by default. Only one metacluster can be the
           default.

       HIDDEN

           Specifies whether a metacluster should be hidden by applications. A hidden metacluster cannot be DEFAULT.

       REQUIRED

           Specifies which metacluster is required. A required metacluster implies that all of  its  cluster  and  package  members  are  not  de-
           selectable (must be installed).

       SUNW_CSRMBRIFF

           Indicates  that  the package is to be included dynamically in the (meta-)cluster currently being described. The value of this parameter
           must follow the following format:

           SUNW_CSRMBRIFF=(test test_arc)package

           This line is converted into a SUNW_CSRMEMBER entry at media installation time if the test provided matches the platform  on  which  the
           media is being installed. There may be zero or more SUNW_CSRMBRIFF parameters per (meta-)cluster.

       SUNW_CSRMBRIFF=(test value)package

           where  the test is either the builtin test of "platform" or a shell script which returns shell true(0) or shell false(1) depending on
           the tests being performed in the script. value is passed to the test as the first argument and can be used  to  create  a  script  that
           tests for multiple hardware objects. Finally package is the package that is included in the final .clustertoc file as a SUNW_CSRMEMBER.
           See parse_dynamic_clustertoc(1M) for more information about the scripts.

       Example 1: A Cluster Description

       The following is an example of a cluster description in a .clustertoc file.

       CLUSTER=SUNWCacc
       NAME=System Accounting
       DESC=System accounting utilities
       VENDOR=Sun Microsystems, Inc.
       VERSION=7.2
       SUNW_CSRMEMBER=SUNWaccr
       SUNW_CSRMEMBER=SUNWaccu
       END

       Example 2: A Meta-cluster Description

       The following is an example of a meta-cluster description in a .clustertoc file.

       METACLUSTER=SUNWCreq
       NAME=Core System Support
       DESC=A pre-defined software configuration consisting of the minimum
       required software for a standalone, non-networked workstation.
       VENDOR=Sun Microsystems, Inc.
       VERSION=2.x
       SUNW_CSRMEMBER=SUNWadmr
       SUNW_CSRMEMBER=SUNWcar
       SUNW_CSRMEMBER=SUNWCcs
       SUNW_CSRMEMBER=SUNWCcg6
       SUNW_CSRMEMBER=SUNWCdfb
       SUNW_CSRMEMBER=SUNWkvm
       SUNW_CSRMEMBER=SUNWCnis
       SUNW_CSRMEMBER=SUNWowdv
       SUNW_CSRMEMBER=SUNWter
       END

       Example 3: A Meta-cluster Description With a Dynamic Cluster Entry

       The following is an example of a meta-cluster description with a dynamic cluster entry as indicated by the use of the SUNW_CSRMBRIFF param-
       eter entries.

       METACLUSTER=SUNWCprog
       NAME=Developer System Support
       DESC=A pre-defined software configuration consisting of the
       typical software used by software developers.
       VENDOR=Sun Microsystems, Inc.
       VERSION=2.5
       SUNW_CSRMEMBER=SUNWCadm
       SUNW_CSRMBRIFF=(smcc.dctoc tcx)SUNWCtcx
       SUNW_CSRMBRIFF=(smcc.dctoc leo)SUNWCleo
       SUNW_CSRMBRIFF=(smcc.dctoc sx)SUNWCsx
       ...
       END

       parse_dynamic_clustertoc(1M), cdtoc(4), order(4), packagetoc(4), pkginfo(4)

       The  current  implementation  of the initial system installation programs depend on the .clustertoc describing three required meta-clusters
       for the base OS product:

       SUNWCall        Contains all of the software packages in the OS distribution.

       SUNWCuser       Contains the typical software packages for an end-user of the OS distribution.

       SUNWCreq        Contains the bare-minimum packages required to boot and configure the OS to the point of running a multi-user shell.

                                                                    18 Feb 2003                                                      clustertoc(4)