テンプレートはサービス開発者によって定義され、サービスに関するメタデータを記述します。サービスの全体的な構成プロパティーや個別の構成プロパティーに記述され、人間が読める形式の説明と、有効な構成の定義を含んでいます。
管理者は SMF コマンドを介してテンプレートにアクセスし、構成値を記述したり、テンプレートと照合して構成を検証したりできます。
ツール開発者はテンプレートを使用して、サービスの構成に役立つユーザーインタフェースを作成できます。
サービスのメタデータは、テンプレートでサービスマニフェストの一部として定義されます。
svcs -lv コマンドと svccfg describe コマンドを使用すると、人間が読める形式でプロパティーに関するメタデータにアクセスできます。
svccfg(1M) の validate サブコマンドを使用すると、テンプレートデータと照合してサービスインスタンスやマニフェストを検証できます。テンプレートデータにアクセスするには、一連の libscf(3LIB) インタフェースを使用できます。
テンプレートを定義するための唯一のインタフェースはサービスマニフェストです。
サービスの作成者は、サービス固有のプロパティーグループおよびそれらに導入されるプロパティーに、common_names、descriptions、choices、constraints などのテンプレートメタデータを指定するようにしてください。サービスの作成者は、少なくともプロパティーグループとプロパティーの説明を C ロケールで指定する必要があります。サービスの作成者は、メソッドや依存関係といったフレームワークによって提供されるプロパティーグループには、テンプレートメタデータを指定しないようにしてください。
サービスのテンプレート定義の作成例については、「使用例」のセクションを参照してください。
すべてのテンプレートインタフェースは、プロパティーグループに関するテンプレートデータを、最初にインスタンスで、次にサービスで、3 番目にサービスのリスタータで、最後にグローバルに検索します。
プロパティーグループのテンプレートはその作成者によって定義され、特定のインスタンス、サービスとそのすべてのインスタンス、リスタータの委任、あるいはグローバルに適用されます。通常、サービスの作成者はインスタンスまたはサービスにテンプレートを定義します。インスタンスに定義されたテンプレートは、そのインスタンスだけに適用され、サービスに定義されているそのプロパティーグループのテンプレートよりも優先されます。サービスに定義されたテンプレートは、そのサービスのすべてのインスタンスに適用されます。
リスタータの作成者は、そのリスタータを使用するすべてのサービスに適用されるテンプレートをマニフェストで定義できます。これは「委任」とも呼ばれます。SMF フレームワークの作成者は、SMF フレームワーク全体に対する既知の意味を指定したプロパティーグループのテンプレートを svc:/system/svc/global のマニフェストに定義してあります。
グローバルにまたはリスタータによって定義されたテンプレートは、サービスまたはインスタンスで再定義されると、検証エラーとしてフラグが設定されます。サービスの作成者は、SMF フレームワークでは使用されない、そのサービスに固有のプロパティーグループだけにテンプレートを作成することで、このようなエラーを避けることができます。
プロパティーグループのテンプレートは、名前やタイプによるワイルドカード方式でも指定できます。プロパティーグループに適用可能なテンプレート定義のうち、もっとも限定的なものだけが適用されます。
template 要素は、template ブロックの開始を定義します。後述するほかの定義はすべて、template ブロックに含めることができます。template 要素は、service 要素または instance 要素に含めることができます。service 要素に含めた場合は、サービスおよびそのサービスのすべてのインスタンスに適用されます。instance 要素に含めた場合は、サービスのそのインスタンスだけに適用されます。
可能な場合は常に、サービス全体のテンプレートデータを定義することをお勧めします。
<service ... > <template> </template> </service>サービスおよびインスタンスの一般的な名前
サービス全体またはインスタンスには、そのサービスまたはインスタンスの目的を表す一般的な名前を定義できます。
<template>
<common_name>
<loctext xml:lang='C'>console login</loctext>
</common_name>
<template>
common_name は自由形式の文字列ですが、GUI または CLI でラベルとして使用されます。
一般的な名前を定義するときは、次のガイドラインに従ってください。
短くします。通常は、1 語または 2 語が適切です。名前の長さは 40 文字以下にしてください。
明確にします。サービス名、プロパティーグループ名、またはプロパティー名は人間にはわかりにくい場合がありますが、common_name はその目的を明確に示すようにしてください。
句読文字は使用しません。common_name は文章ではありません。節や句を含むべきではありません。句読文字は、商標で必要になる場合にかぎり使用するようにしてください。
大文字は頭字語または固有名だけに使用する必要があります。英語以外のロケールでは、文の要素に適切な大文字を使用してください。
description 要素には、ステータス行やツールヒントに適した、プロパティーグループに関する長い説明が記述されます。
<template>
<description>
<loctext xml:lang='C'>Provide the text login prompt on console.
</loctext>
</description>
<template>
description のガイドライン
正しい文法を使用します。description は人間が読むための文です。
短くします。通常は、数個の文がもっとも適切です。
このサービスのドキュメントを明示的に定義することにより、サービスで問題が発生した場合やサービスの利用者が詳細な情報を必要としている場合に、ドキュメントを簡単に見つけることができます。
<documentation> <manpage title='sendmail' section='1M' + manpath='/usr/share/man' /> <doc_link name='sendmail.com' + uri='http://sendmail.com' /> <external_logfile + path='/var/log/syslog' /> </documentation>
manpage 要素は、リファレンスマニュアルページをテンプレートサービスに関連付けます。使用可能な属性:
マニュアルページのタイトル。
マニュアルページのセクション。
man(1) で説明されているように、名前付きのマニュアルページを参照するには MANPATH 環境変数が必要です。
doc_link は、指定された URI によって表されるリソースを、包含するテンプレートによって表されるサービスに関連付けます。リソースは、なんらかのドキュメントまたは説明的リファレンスであると想定されます。使用可能な属性:
このリソースのラベル。
このリソースの URI。
external_logfile 要素を使用すると、サービス開発者はサービスで使用される外部ログファイルへのパスを指定できます。使用可能な属性:
外部ログファイルへのパス。
pg_pattern 要素には、プロパティーグループの定義が記述されます。
<template> <pg_pattern name="pgname" type="pgtype" target="this" required="true"> </pg_pattern> </template>
name はプロパティーグループの名前、type はプロパティーグループのタイプです。
target は、この定義の対象を指定します。"this" と指定すると、これを定義しているサービスまたはインスタンスを指します。"instance" は、サービスの template ブロックでのみ使用でき、定義がこのサービスのすべてのインスタンスに適用されることを意味します。"delegate" は、リスタータの template ブロックでのみ使用でき、そのリスタータに委任されたすべてのインスタンスに適用されることを意味します。"all" は、マスターリスタータでのみ使用でき、システム上のすべてのサービスを参照します。target のデフォルト値は "this" です。
required は、このプロパティーグループが必須かどうかを示します。required のデフォルト値は false です。required が true の場合は、name と type の両方を指定する必要があります。
name と type は、一方または両方を省略できます。これらの属性のいずれかが省略されている場合、その属性はワイルドカードとして扱われます。たとえば、pg_pattern 定義で name 属性が省略されている場合、pg_pattern は指定されたタイプのすべてのプロパティーグループに適用されます。
プロパティーグループの名前common_name 要素には、人間が読めるローカライズされた形式で、プロパティーグループの名前が記述されます。
<pg_pattern ...>
<common_name>
<loctext xml:lang='C'>start method</loctext>
</common_name>
</pg_pattern>
common_name は自由形式の文字列ですが、GUI または CLI でラベルとして使用されます。
前述の「サービスおよびインスタンスの一般的な名前」に示されている common_name に関するガイドラインを参照してください。
プロパティーグループの説明description 要素には、ステータス行やツールヒントに適した、プロパティーグループに関する長い説明が記述されます。
<pg_pattern ...>
<description>
<loctext xml:lang='C'>A required method which starts the service.
</loctext>
</description>
</pg_pattern>
前述の「サービスおよびインスタンスの説明」に示されている description の指定方法に関するガイドラインを参照してください。
プロパティーprop_pattern 要素には、特定のプロパティーの定義が記述されます。
<pg_pattern ...> <prop_pattern name="propname" type="proptype" required="true"> </prop_pattern> </pg_pattern>
name はプロパティーの名前、type はプロパティーのタイプです。
required は、このプロパティーが必須かどうかを示します。required のデフォルト値は false です。
name は常に必須です。required が false の場合のみ、type はオプションです。
プロパティーの名前common_name 要素には、人間が読めるローカライズされた形式で、プロパティーの名前が記述されます。
common_name は自由形式の文字列フィールドですが、GUI または CLI でラベルとして使用されます。
<prop_pattern ...> <common_name> <loctext xml:lang='C'>retry interval</loctext> </common_name> </prop_pattern>
前述の「サービスおよびインスタンスの一般的な名前」に示されている common_name に関するガイドラインを参照してください。
プロパティーの単位units 要素には、人間が読めるローカライズされた形式で、数値プロパティーの単位が記述されます。
<prop_pattern ...>
<units>
<loctext xml:lang='C'>seconds</loctext>
</units>
</prop_pattern>
units のガイドライン
短くします。1 語または 1 ラベルだけを使用するようにします。通常は、複数形がもっとも適切です。
句読文字は使用しません。units は文章ではありません。節や句を含むべきではありません。句読文字は、商標で必要になる場合にかぎり使用するようにしてください。
description 要素には、ステータス行やツールヒントに適した、プロパティーに関する長い説明が記述されます。
<prop_pattern ...>
<description> <loctext xml:lang='C'>
The number of seconds to wait before retry.
</loctext> </description>
</prop_pattern>
前述の「サービスおよびインスタンスの説明」に示されている description の指定方法に関するガイドラインを参照してください。
プロパティーの可視設定visibility 要素は、より上位のソフトウェアの簡易表示でこのプロパティーを表示するかどうかを指定します。
<prop_pattern ...> <visibility value="hidden | readonly | readwrite"/> </prop_pattern>
一部のプロパティーは、内部の実装の詳細であり、構成の設定として表示されるべきではありません。単に読み取り専用のものもあります。このプロパティーは、このような制約を指定するために使用されます。値 hidden は、そのプロパティーを表示するべきでないことを示します。readonly は、そのプロパティーを変更する予定がないことを意味します。readwrite は、そのプロパティーが変更可能であることを示します。
これはセキュリティーメカニズムでなく、単にユーザー自身の誤りを防ぎ、CLI の出力や GUI の表示から不要な情報を取り除くためのものです。非表示のプロパティーは、多くのコマンドおよび UI の完全開示モードで表示されます。
プロパティーの形式cardinality および internal_separators 要素は、プロパティーの構造を制約します。
<prop_pattern ...> <cardinality min="1" max="1"/> <internal_separators>,</internal_separators> </prop_pattern>
cardinality は、指定できるプロパティー値の数を示します。min は最小数、max は最大数です。どちらもオプションです。どちらも指定されていない場合、<cardinality/> はデフォルトと同じ、0 個以上の値になります。
internal_separators は、実際の値を複数保持するプロパティー値に使用する区切り文字を指定します。
値の制約constraints 要素は、プロパティーに使用できる値を指定します。
<prop_pattern ...>
<constraints>
<value name="blue" />
<range min="1" max="7"/>
<include_values type="values"/>
</constraints>
</prop_pattern>
value 要素には、プロパティーの取り得る値が記述されます。range には、整数の範囲が記述されます。
value と range は、使用を制限すると有効な説明の多くが使用できなくなるため、任意の組み合わせで使用できます。値の制約が指定されていない場合、そのプロパティーは任意の値を取ることができます。
include_values には、values ブロックで指定されたすべての値が記述されます (「値の説明」のセクションを参照)。
値の選択肢choices ブロックは、UI でユーザーに提供する値を示します。
<prop_pattern ...>
<choices>
<range min="1" max="3"/>
<value name="vt100" />
<value name="xterm" />
<include_values type="constraints"/>
<include_values type="values"/>
</choices>
</prop_pattern>
constraints と同様に、range と value には範囲と個々の値が記述されます。
include_values には、constraints ブロックまたは values ブロックで指定されたすべての値が記述されます (次のセクションを参照)。
値の説明プロパティー名と同様に、プロパティーが取る値にも、わかりにくい表現のものが存在します。values 要素には、人間が読めるローカライズされた形式で、特定のプロパティー値の説明が記述されます。
<prop_pattern>
<values>
<value name="blue">
<common_name>
<loctext xml:lang='C'>blue</loctext>
</common_name>
<description>
<loctext xml:lang='C>
The color between green and indigo.
</loctext>
</description>
</value>
</values>
</prop_pattern>
common_name は自由形式の文字列フィールドですが、GUI または CLI でラベルとして使用されます。
前述の「サービスおよびインスタンスの一般的な名前」に示されている common_name に関するガイドラインを参照してください。
次のような基本的なサービスがあり、その基本的なテンプレートデータを定義する場合を考えます。
<?xml version="1.0"?
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
<service_bundle type='manifest' name='FOOfoo:foo'>
<service name='system/foo' type='service' version='1'>
<dependency>
name='multi-user'
type='service'
grouping='require_all'
restart_on='none'
<service_fmri value='svc:/milestone/multi-user' />
</dependency>
<exec_method
type='method'
name='start'
exec='/opt/foo/food'
timeout_seconds='60'>
</exec_method>
<exec_method
type='method'
name='stop'
exec=':kill'
timeout_seconds='60'>
</exec_method>
<property_group name='config' type='application'>
<propval name='local_only' type='boolean' value='false' />
<propval name='config_file' type='astring'
value='/opt/foo/foo.conf' />
<property name='modules' type='astring'>
<astring_list>
<value_node value='bar'/>
<value_node value='baz'/>
</astring_list>
</property>
</property_group>
<instance name='default' enabled='false' />
</service>
</service_bundle>
このサービスを使用する管理者に役立つように、基本的なテンプレートデータを <service> タグの内側に定義できます。もっとも役立つのは、サービス自体の目的と、サービス固有の構成を記述することです。
<template>
<common_name> <loctext xml:lang='C'>
all-purpose demonstration
</loctext> </common_name>
<documentation>
<manpage title='food' section='1M'
manpath='/opt/foo/man' />
</documentation>
<pg_pattern name='config' type='application' target='this'
required='true'>
<description> <loctext xml:lang='C'>
Basic configuration for foo.
</loctext> </description>
<prop_pattern name='local_only' type='boolean'
required='false'>
<description> <loctext xml:lang='C'>
Only listen to local connection requests.
</loctext> </description>
</prop_pattern>
<prop_pattern name='config_file' type='astring'
required='true'>
<cardinality min='1' max='1'/>
<description> <loctext xml:lang='C'>
Configuration file for foo.
</loctext> </description>
</prop_pattern>
<prop_pattern name='modules' type='astring'
required='false'>
<description> <loctext xml:lang='C'>
Plugin modules for foo.
</loctext> /description>
<values>
<value name='bar'>
<description> <loctext xml:lang='C'>
Allow foo to access the bar.
</loctext> </description>
</value>
<value name='baz'>
<description> <loctext xml:lang='C'>
Allow foo to access baz functions.
</loctext> </description>
</value>
<value name='qux'>
<description> <loctext xml:lang='C'>
Allow foo to access qux functions.
</loctext> </description>
</value>
</values>
<choices>
<include_values type='values'/>
</choices>
<prop_pattern>
</pg_pattern>
</template>
/usr/share/lib/xml/dtd/service_bundle.dtd.1
svcs(1) , svccfg (1M), libscf(3LIB), service_bundle(4) , smf(5)
/usr/apache2/2.2/man