OpenSolaris_b135/cmd/svc/dtd/service_bundle.dtd.1
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2009 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.
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
-->
<!--
Service description DTD
Most attributes are string values (or an individual string from a
restricted set), but attributes with a specific type requirement are
noted in the comment describing the element.
-->
<!--
XInclude support
A series of service bundles may be composed via the xi:include tag.
smf(5) tools enforce that all bundles be of the same type.
-->
<!ELEMENT xi:include
(xi:fallback)
>
<!ATTLIST xi:include
href CDATA #REQUIRED
parse (xml|text) "xml"
encoding CDATA #IMPLIED
xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
>
<!ELEMENT xi:fallback
ANY
>
<!ATTLIST xi:fallback
xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
>
<!--
stability
This element associates an SMI stability level with the parent
element. See attributes(5) for an explanation of interface
stability levels.
Its attribute is
value The stability level of the parent element.
-->
<!ELEMENT stability EMPTY>
<!ATTLIST stability
value ( Standard | Stable | Evolving | Unstable |
External | Obsolete ) #REQUIRED >
<!-- Property value lists -->
<!--
value_node
This element represents a single value within any of the typed
property value lists.
Its attribute is
value The value for this node in the list.
-->
<!ELEMENT value_node EMPTY>
<!ATTLIST value_node
value CDATA #REQUIRED>
<!--
count_list
integer_list
opaque_list
host_list
hostname_list
net_address_v4_list
net_address_v6_list
time_list
astring_list
ustring_list
boolean_list
fmri_list
uri_list
These elements represent the typed lists of values for a property.
Each contains one or more value_node elements representing each
value on the list.
None of these elements has attributes.
-->
<!ELEMENT count_list
( value_node+ )>
<!ATTLIST count_list>
<!ELEMENT integer_list
( value_node+ )>
<!ATTLIST integer_list>
<!ELEMENT opaque_list
( value_node+ )>
<!ATTLIST opaque_list>
<!ELEMENT host_list
( value_node+ )>
<!ATTLIST host_list>
<!ELEMENT hostname_list
( value_node+ )>
<!ATTLIST hostname_list>
<!ELEMENT net_address_v4_list
( value_node+ )>
<!ATTLIST net_address_v4_list>
<!ELEMENT net_address_v6_list
( value_node+ )>
<!ATTLIST net_address_v6_list>
<!ELEMENT time_list
( value_node+ )>
<!ATTLIST time_list>
<!ELEMENT astring_list
( value_node+ )>
<!ATTLIST astring_list>
<!ELEMENT ustring_list
( value_node+ )>
<!ATTLIST ustring_list>
<!ELEMENT boolean_list
( value_node+ )>
<!ATTLIST boolean_list>
<!ELEMENT fmri_list
( value_node+ )>
<!ATTLIST fmri_list>
<!ELEMENT uri_list
( value_node+ )>
<!ATTLIST uri_list>
<!-- Properties and property groups -->
<!--
property
This element is for a singly or multiply valued property within a
property group. It contains an appropriate value list element,
which is expected to be consistent with the type attribute.
Its attributes are
name The name of this property.
type The data type for this property.
override These values should replace values already in the
repository.
-->
<!ELEMENT property
( count_list | integer_list | opaque_list | host_list | hostname_list |
net_address_v4_list | net_address_v6_list | time_list |
astring_list | ustring_list | boolean_list | fmri_list |
uri_list )? >
<!ATTLIST property
name CDATA #REQUIRED
type ( count | integer | opaque | host | hostname |
net_address_v4 | net_address_v6 | time |
astring | ustring | boolean | fmri | uri ) #REQUIRED
override ( true | false ) "false" >
<!--
propval
This element is for a singly valued property within a property
group. List-valued properties must use the property element above.
Its attributes are
name The name of this property.
type The data type for this property.
value The value for this property. Must match type
restriction of type attribute.
override This value should replace any values already in the
repository.
-->
<!ELEMENT propval EMPTY>
<!ATTLIST propval
name CDATA #REQUIRED
type ( count | integer | opaque | host | hostname |
net_address_v4 | net_address_v6 | time | astring |
ustring | boolean | fmri | uri ) #REQUIRED
value CDATA #REQUIRED
override ( true | false ) "false" >
<!--
property_group
This element is for a set of related properties on a service or
instance. It contains an optional stability element, as well as
zero or more property-containing elements.
Its attributes are
name The name of this property group.
type A category for this property group. Groups of type
"framework", "implementation" or "template" are primarily
of interest to the service management facility, while
groups of type "application" are expected to be only of
interest to the service to which this group is attached.
Other types may be introduced using the service symbol
namespace conventions.
delete If in the repository, this property group should be removed.
-->
<!ELEMENT property_group
( stability?, ( propval | property )* )>
<!ATTLIST property_group
name CDATA #REQUIRED
type CDATA #REQUIRED
delete ( true | false ) "false" >
<!--
service_fmri
This element defines a reference to a service FMRI (for either a
service or an instance).
Its attribute is
value The FMRI.
-->
<!ELEMENT service_fmri EMPTY>
<!ATTLIST service_fmri
value CDATA #REQUIRED>
<!-- Dependencies -->
<!--
dependency
This element identifies a group of FMRIs upon which the service is
in some sense dependent. Its interpretation is left to the
restarter to which a particular service instance is delegated. It
contains a group of service FMRIs, as well as a block of properties.
Its attributes are
name The name of this dependency.
grouping The relationship between the various FMRIs grouped
here; "require_all" of the FMRIs to be online, "require_any"
of the FMRIs to be online, or "exclude_all" of the FMRIs
from being online or in maintenance for the dependency to
be satisfied. "optional_all" dependencies are satisfied
when all of the FMRIs are either online or unable to come
online (because they are disabled, misconfigured, or one
of their dependencies is unable to come online).
restart_on The type of events from the FMRIs that the service should
be restarted for. "error" restarts the service if the
dependency is restarted due to hardware fault. "restart"
restarts the service if the dependency is restarted for
any reason, including hardware fault. "refresh" restarts
the service if the dependency is refreshed or restarted for
any reason. "none" will never restart the service due to
dependency state changes.
type The type of dependency: on another service ('service'), on
a filesystem path ('path'), or another dependency type.
delete This dependency should be deleted.
-->
<!ELEMENT dependency
( service_fmri*, stability?, ( propval | property )* ) >
<!ATTLIST dependency
name CDATA #REQUIRED
grouping ( require_all | require_any | exclude_all |
optional_all ) #REQUIRED
restart_on ( error | restart | refresh | none ) #REQUIRED
type CDATA #REQUIRED
delete ( true | false ) "false" >
<!-- Dependents -->
<!--
dependent
This element identifies a service which should depend on this service. It
corresponds to a dependency in the named service. The grouping and type
attributes of that dependency are implied to be "require_all" and
"service", respectively.
Its attributes are
name The name of the dependency property group to create in the
dependent entity.
grouping The grouping relationship of the dependency property
group to create in the dependent entity. See "grouping"
attribute on the dependency element.
restart_on The type of events from this service that the named service
should be restarted for.
delete True if this dependent should be deleted.
override Whether to replace an existing dependent of the same name.
-->
<!ELEMENT dependent
( service_fmri, stability?, ( propval | property )* ) >
<!ATTLIST dependent
name CDATA #REQUIRED
grouping ( require_all | require_any | exclude_all |
optional_all) #REQUIRED
restart_on ( error | restart | refresh | none) #REQUIRED
delete ( true | false ) "false"
override ( true | false ) "false" >
<!-- Method execution context, security profile, and credential definitions -->
<!--
envvar
An environment variable. It has two attributes:
name The name of the environment variable.
value The value of the environment variable.
-->
<!ELEMENT envvar EMPTY>
<!ATTLIST envvar
name CDATA #REQUIRED
value CDATA #REQUIRED >
<!--
method_environment
This element defines the environment for a method. It has no
attributes, and one or more envvar child elements.
-->
<!ELEMENT method_environment (envvar+) >
<!ATTLIST method_environment>
<!--
method_profile
This element indicates which exec_attr(5) profile applies to the
method context being defined.
Its attribute is
name The name of the profile.
-->
<!ELEMENT method_profile EMPTY>
<!ATTLIST method_profile
name CDATA #REQUIRED >
<!--
method_credential
This element specifies credential attributes for the execution
method to use.
Its attributes are
user The user ID, in numeric or text form.
group The group ID, in numeric or text form. If absent or
":default", the group associated with the user in the
passwd database.
supp_groups Supplementary group IDs to be associated with the
method, separated by commas or spaces. If absent or
":default", initgroups(3C) will be used.
privileges An optional string specifying the privilege set.
limit_privileges An optional string specifying the limit
privilege set.
-->
<!ELEMENT method_credential EMPTY>
<!ATTLIST method_credential
user CDATA #REQUIRED
group CDATA #IMPLIED
supp_groups CDATA #IMPLIED
privileges CDATA #IMPLIED
limit_privileges CDATA #IMPLIED >
<!--
method_context
This element combines credential and resource management attributes
for execution methods. It may contain a method_environment, or
a method_profile or method_credential element.
Its attributes are
working_directory The home directory to launch the method from.
":default" can be used as a token to indicate use of the
user specified by the credential or profile specified.
project The project ID, in numeric or text form. ":default" can
be used as a token to indicate use of the project
identified by getdefaultproj(3PROJECT) for the non-root
user specified by the credential or profile specified.
If the user is root, ":default" designates the project
the restarter is running in.
resource_pool The resource pool name to launch the method on.
":default" can be used as a token to indicate use of the
pool specified in the project(4) entry given in the
"project" attribute above.
-->
<!ELEMENT method_context
( (method_profile | method_credential)?, method_environment? ) >
<!ATTLIST method_context
working_directory CDATA #IMPLIED
project CDATA #IMPLIED
resource_pool CDATA #IMPLIED >
<!-- Restarter delegation, methods, and monitors -->
<!--
exec_method
This element describes one of the methods used by the designated
restarter to act on the service instance. Its interpretation is
left to the restarter to which a particular service instance is
delegated. It contains a set of attributes, an optional method
context, and an optional stability element for the optional
properties that can be included.
Its attributes are
type The type of method, either "method" or "monitor".
name Name of this execution method. The method names are
usually a defined interface of the restarter to which an
instance of this service is delegated.
exec The string identifying the action to take. For
svc.startd(1M), this is a string suitable to pass to
exec(2).
timeout_seconds [integer] Duration, in seconds, to wait for this
method to complete. A '0' or '-1' denotes an infinite
timeout.
delete If in the repository, the property group for this method
should be removed.
-->
<!ELEMENT exec_method
( method_context?, stability?, ( propval | property )* ) >
<!ATTLIST exec_method
type ( method | monitor ) #REQUIRED
name CDATA #REQUIRED
exec CDATA #REQUIRED
timeout_seconds CDATA #REQUIRED
delete ( true | false ) "false" >
<!--
restarter
A flag element identifying the restarter to which this service or
service instance is delegated. Contains the FMRI naming the
delegated restarter.
This element has no attributes.
-->
<!ELEMENT restarter
( service_fmri ) >
<!ATTLIST restarter>
<!--
Templates
-->
<!--
doc_link
The doc_link relates a resource described by the given URI to the
service described by the containing template. The resource is
expected to be a documentation or elucidatory reference of some
kind.
Its attributes are
name A label for this resource.
uri A URI to the resource.
-->
<!ELEMENT doc_link EMPTY>
<!ATTLIST doc_link
name CDATA #REQUIRED
uri CDATA #REQUIRED >
<!--
manpage
The manpage element connects the reference manual page to the
template's service.
Its attributes are
title The manual page title.
section The manual page's section.
manpath The MANPATH environment variable, as described in man(1)
that is required to reach the named manual page
-->
<!ELEMENT manpage EMPTY>
<!ATTLIST manpage
title CDATA #REQUIRED
section CDATA #REQUIRED
manpath CDATA ":default" >
<!--
documentation
The documentation element groups an arbitrary number of doc_link
and manpage references.
It has no attributes.
-->
<!ELEMENT documentation
( doc_link | manpage )* >
<!ATTLIST documentation>
<!--
loctext
The loctext element is a container for localized text.
Its sole attribute is
xml:lang The name of the locale, in the form accepted by LC_ALL,
etc. See locale(5).
-->
<!ELEMENT loctext
(#PCDATA) >
<!ATTLIST loctext
xml:lang CDATA #REQUIRED >
<!--
description
The description holds a set of potentially longer, localized strings that
consist of a short description of the service.
The description has no attributes.
-->
<!ELEMENT description
( loctext+ ) >
<!ATTLIST description>
<!--
common_name
The common_name holds a set of short, localized strings that
represent a well-known name for the service in the given locale.
The common_name has no attributes.
-->
<!ELEMENT common_name
( loctext+ ) >
<!ATTLIST common_name>
<!--
units
The units a numerical property is expressed in.
-->
<!ELEMENT units
( loctext+ ) >
<!ATTLIST units>
<!--
visibility
Expresses how a property is typically accessed. This isn't
intended as access control, but as an indicator as to how a
property is used.
Its attributes are:
value 'hidden', 'readonly', or 'readwrite' indicating that
the property should be hidden from the user, shown but
read-only, or modifiable.
-->
<!ELEMENT visibility EMPTY>
<!ATTLIST visibility
value ( hidden | readonly | readwrite ) #REQUIRED >
<!--
value
Describes a legal value for a property value, and optionally contains a
human-readable name and description for the specified property
value.
Its attributes are:
name A string representation of the value.
-->
<!ELEMENT value
( common_name?, description? ) >
<!ATTLIST value
name CDATA #REQUIRED >
<!--
values
Human-readable names and descriptions for valid values of a property.
-->
<!ELEMENT values
(value+) >
<!ATTLIST values>
<!--
cardinality
Places a constraint on the number of values the property can take
on.
Its attributes are:
min minimum number of values
max maximum number of values
Both attributes are optional. If min is not specified, it defaults to
0. If max is not specified it indicates an unlimited number of values.
If neither is specified this indicates 0 or more values.
-->
<!ELEMENT cardinality EMPTY>
<!ATTLIST cardinality
min CDATA "0"
max CDATA "18446744073709551615">
<!--
internal_separators
Indicates the separators used within a property's value used to
separate the actual values. Used in situations where multiple
values are packed into a single property value instead of using a
multi-valued property.
-->
<!ELEMENT internal_separators
(#PCDATA) >
<!ATTLIST internal_separators>
<!--
range
Indicates a range of possible integer values.
Its attributes are:
min The minimum value of the range (inclusive).
max The maximum value of the range (inclusive).
-->
<!ELEMENT range EMPTY>
<!ATTLIST range
min CDATA #REQUIRED
max CDATA #REQUIRED >
<!--
constraints
Provides a set of constraints on the values a property can take on.
-->
<!ELEMENT constraints
( value*, range* ) >
<!ATTLIST constraints>
<!--
include_values
Includes an entire set of values in the choices block.
Its attributes are:
type Either "constraints" or "values", indicating an
inclusion of all values allowed by the property's
constraints or all values for which there are
human-readable names and descriptions, respectively.
-->
<!ELEMENT include_values EMPTY>
<!ATTLIST include_values
type ( constraints | values ) #REQUIRED >
<!--
choices
Provides a set of common choices for the values a property can take
on. Useful in those cases where the possibilities are unenumerable
or merely inconveniently legion, and a manageable subset is desired
for presentation in a user interface.
-->
<!ELEMENT choices
( value*, range*, include_values* ) >
<!ATTLIST choices>
<!--
prop_pattern
The prop_pattern describes one property of the enclosing property group
pattern.
Its attributes are:
name The property's name.
type The property's type.
required
If the property group is present, this property is required.
type can be omitted if required is false.
-->
<!ELEMENT prop_pattern
( common_name?, description?, units?, visibility?, cardinality?,
internal_separators?, values?, constraints?, choices? ) >
<!ATTLIST prop_pattern
name CDATA #REQUIRED
type ( count | integer | opaque | host | hostname |
net_address_v4 | net_address_v6 | time | astring |
ustring | boolean | fmri | uri ) #IMPLIED
required ( true | false ) "false" >
<!--
pg_pattern
The pg_pattern describes one property group.
Depending on the element's attributes, these descriptions may apply
to just the enclosing service/instance, instances of the enclosing
service, delegates of the service (assuming it is a restarter), or
all services.
Its attributes are:
name The property group's name. If not specified, it
matches all property groups with the specified type.
type The property group's type. If not specified, it
matches all property groups with the specified name.
required
If the property group is required.
target The scope of the pattern, which may be all, delegate,
instance, or this. 'all' is reserved for framework use
and applies the template to all services on the system.
'delegate' is reserved for restarters, and means the
template applies to all services which use the restarter.
'this' would refer to the defining service or instance.
'instance' can only be used in a service's template block,
and means the definition applies to all instances of this
service.
-->
<!ELEMENT pg_pattern
( common_name?, description?, prop_pattern* ) >
<!ATTLIST pg_pattern
name CDATA ""
type CDATA ""
required ( true | false ) "false"
target ( this | instance | delegate | all ) "this" >
<!--
template
The template contains a collection of metadata about the service.
It contains a localizable string that serves as a common,
human-readable name for the service. (This name should be less than
60 characters in a single byte locale.) The template may optionally
contain a longer localizable description of the service, a
collection of links to documentation, either in the form of manual
pages or in the form of URI specifications to external documentation
sources (such as docs.sun.com).
The template has no attributes.
-->
<!ELEMENT template
( common_name, description?, documentation?, pg_pattern* ) >
<!ATTLIST template>
<!-- Services and instances -->
<!--
create_default_instance
A flag element indicating that an otherwise empty default instance
of this service (named "default") should be created at install, with
its enabled property set as given.
Its attribute is
enabled [boolean] The initial value for the enabled state of
this instance.
-->
<!ELEMENT create_default_instance EMPTY >
<!ATTLIST create_default_instance
enabled ( true | false ) #REQUIRED >
<!--
single_instance
A flag element stating that this service can only have a single
instance on a particular system.
-->
<!ELEMENT single_instance EMPTY>
<!ATTLIST single_instance>
<!--
instance
The service instance is the object representing a software component
that will run on the system if enabled. It contains an enabled
element, a set of dependencies on other services, potentially
customized methods or configuration data, an optional method
context, and a pointer to its restarter. (If no restarter is
specified, the master restarter, svc.startd(1M), is assumed to be
responsible for the service.)
Its attributes are
name The canonical name for this instance of the service.
enabled [boolean] The initial value for the enabled state of
this instance.
-->
<!ELEMENT instance
( restarter?, dependency*, dependent*, method_context?,
exec_method*, property_group*, template? ) >
<!ATTLIST instance
name CDATA #REQUIRED
enabled ( true | false ) #REQUIRED >
<!--
service
The service contains the set of instances defined by default for
this service, an optional method execution context, any default
methods, the template, and various restrictions or advice applicable
at installation. The method execution context and template elements
are required for service_bundle documents with type "manifest", but
are optional for "profile" or "archive" documents.
Its attributes are
name The canonical name for the service.
version [integer] The integer version for this service.
type Whether this service is a simple service, a delegated
restarter, or a milestone (a synthetic service that
collects a group of dependencies).
-->
<!ELEMENT service
( create_default_instance?, single_instance?, restarter?,
dependency*, dependent*, method_context?, exec_method*,
property_group*, instance*, stability?, template? ) >
<!ATTLIST service
name CDATA #REQUIRED
version CDATA #REQUIRED
type ( service | restarter | milestone ) #REQUIRED >
<!--
service_bundle
The bundle possesses two attributes:
type How this file is to be understood by the framework (or
used in a non-framework compliant way). Standard types
are 'archive', 'manifest', and 'profile'.
name A name for the bundle. Manifests should be named after
the package which delivered them; profiles should be
named after the "feature set nickname" they intend to
enable.
-->
<!ELEMENT service_bundle
( service_bundle* | service* | xi:include* )>
<!ATTLIST service_bundle
type CDATA #REQUIRED
name CDATA #REQUIRED>