I'm submitting this fasttrack on behalf of Antonello Cruz. We
request a Patch binding, and new interfaces introduced are
Committed.
The timer is set for 28 January, 2008.
liane
---
Process Contract Decorations
Antonello Cruz
1/22/2008
1. Summary
This proposal adds new terms to process contracts for the service
fmri and additional information that will enable one to identify the
provenance of a process contract. It also updates SMF(5), ctrun(1),
and init(1M) to publish this information. Unmodified process
contract consumers will continue to work in a compatible fashion.
We are requesting patch release binding for these changes.
2. Problem Solved
svc.startd and inetd currently track which contracts they created
for which services. While this information is made available to
other consumers, it isn't conveniently accessed: the data is indexed
by service, not contract; the data isn't available in kernel or
post-mortem environments; and data on sub-contracts (contracts
created by contracts created by svc.startd/inetd) doesn't exist.
With these changes:
Administrators will be able to easily (i.e. in one step only)
identify where a contract originated.
Contracts without an existing genealogical link to contracts known
to SMF will still be identifiable.
Observation and debugging tools (e.g. DTrace) in both userland and
the kernel will be able to efficiently obtain and use the service
owner of a contract.
Post-mortem tools will be able to identify the ownership of
contracts.
3. Description Details
3.1 New process contract terms
The following new terms are added to the process contract:
Service FMRI:
This term contains the service FMRI for the process contract
members. The value is set on the contract template and if left
undefined, it will be inherited from the parent's process
contract.
Creator Auxiliary:
This term allows a particular creator to further describe the
purpose of a contract. In general, the values of this term are
undefined by this case; it is up to individual creators to
create and follow conventions. For example, svc.startd could
(and will, see below) use this field to store the method name.
The primary consumers of this term are observation tools that
could be running in a variety of locales; we recommend producers
(which are typically daemons or system tools) limit their
content to the C locale (ASCII).
In addition to the above terms, the kernel will publish the
following information for each process contract:
Service Contract ID
The contract ID of the first contract in this service. The
first contract is the youngest ancestor for which the Service
FMRI was set (i.e. not inherited).
Creator
The name of the process that created the process contract.
3.2 New privileges
In order to be able to reliably identify a process contract based
on the service FMRI value, we will require privilege to set the
term in the process contract template. There is no current
privilege that could be leveraged for the purpose of contract
identification. Thus, we introduce a new privilege,
{PRIV_CONTRACT_IDENTITY}, that will be required of processes that
set the Service FMRI term.
3.3 Change to existing software
The following interfaces were added to libcontract(3LIB) to access
the new terms in the template and process contracts. These
descriptions can be found in the man pages.
ct_pr_tmpl_set_svc_fmri()
ct_pr_tmpl_get_svc_fmri()
ct_pr_tmpl_set_svc_aux()
ct_pr_tmpl_get_svc_aux()
ct_pr_status_get_svc_fmri()
ct_pr_status_get_svc_aux()
ct_pr_status_get_svc_ctid()
ct_pr_status_get_svc_creator()
To permit a user to define values to the new term, new options
were introduced to ctrun. Option -F to set the value for service
FMRI and option -A to set the value for service auxiliary
New contract term values of well-known process contracts.
init(1M)
term set by value
----------------------------------------------------------------
FMRI kernel svc:/system/init:default
ctid kernel init's contract id
creator kernel "sched"
aux kernel ""
init-started "services"
term set by value
-----------------------------------------------------------------
FMRI init(1M) init:/<inittab entry id>
ctid kernel service's contract id
creator kernel "init"
aux init(1M) inittab entry id
svc.startd(1M) (special case of the above)
term set by value
----------------------------------------------------------------
FMRI init(1M) svc:/system/svc/restarter:default
ctid kernel svc.startd's contract id
creator kernel "init"
aux init(1M) "smf" (svc.startd's inittab entry id)
svc.configd(1M)
term set by value
----------------------------------------------------------------
FMRI svc.startd(1M) svc:/system/svc/repository:default
ctid kernel svc.configd's contract id
creator kernel "svc.startd"
aux svc.startd(1M) "svc.configd"
services
term set by value
----------------------------------------------------------------
FMRI restarter service FMRI
ctid kernel service's contract id
creator kernel restarter execname (e.g svc.startd)
aux restarter method (e.g start, stop)
subcontract of services/commands unaware of new terms
e.g. ssh, console-login, zlogin
term set by value
----------------------------------------------------------------
FMRI kernel service FMRI inherited from parent
ctid kernel service's contract id
creator kernel contract creator's execname (e.g sshd)
aux kernel ""
ctrun(1)
term set by value
----------------------------------------------------------------
FMRI ctrun(1) defined by option -F, if omitted it
will inherit the value from parent's
contract
ctid kernel service's contract id (or the
contract's id, if a new FMRI was
specified using -F
creator kernel "ctrun"
aux ctrun(1) defined by option -A, if omitted it
will be ""
4. Examples
The following example obtains a verbose report of contract which its
id is 1:
example% ctstat -vi 1
CTID TYPE STATE HOLDER EVENTS QTIME NTIME
1 process owned 100579 0 - -
informative event set: none
critical event set: hwerr core
fatal event set: hwerr
parameter set: none
member processes: 100600 100601
inherited ctids: none
service fmri: svc:/system/init:default
service fmri's ctid: 1
creator: sched
aux:
Here is a dtrace example for aggregating system calls by FMRI.
#!/usr/sbin/dtrace -s
syscall:::entry
{
@[stringof(curthread->t_procp->p_ct_process->conp_svc_fmri->
rs_string)] = count();
}
dtrace: script './svc_sys_aggr.d' matched 232 probes ^C
svc:/system/fmd:default 7
svc:/system/utmp:default 11
svc:/system/system-log:default 18
svc:/network/rpc/keyserv:default 20
svc:/system/hal:default 20
svc:/system/intrd:default 36
svc:/system/zones:default 72
svc:/network/smtp:sendmail 122
svc:/network/inetd:default 292
svc:/network/rpc/bind:default 372
svc:/system/cryptosvc:default 394
svc:/network/nfs/mapid:default 439
svc:/network/rpc/gss:default 623
svc:/network/nfs/cbd:default 668
svc:/system/filesystem/autofs:default 1402
svc:/network/nfs/status:default 1556
svc:/system/webconsole:console 1842
svc:/network/nfs/nlockmgr:default 1977
svc:/application/graphical-login/cde-login:default 2449
svc:/system/svc/restarter:default 2851
svc:/system/name-service-cache:default 3819
svc:/system/console-login:default 5124
svc:/system/svc/repository:default 9686
svc:/network/ssh:default 10819
5. Interface table
The new libcontract(3LIB) interfaces created by this project are
listed below.
This is the set of interfaces used to modify and retrieve values in
the process contract template structure.
ct_pr_tmpl_set_svc_fmri() Committed
ct_pr_tmpl_get_svc_fmri() Committed
ct_pr_tmpl_set_svc_aux() Committed
ct_pr_tmpl_get_svc_aux() Committed
This is the set of interfaces used to retrieve values in the process
contract status structure.
ct_pr_status_get_svc_fmri() Committed
ct_pr_status_get_svc_aux() Committed
ct_pr_status_get_svc_ctid() Committed
ct_pr_status_get_svc_creator() Committed
Modified commands interface
ctrun invocation Committed
ctstat output Not-an-Interface
Privilege created
PRIV_CONTRACT_IDENTITY Committed
6. Documentation changes
See the 'materials' subdirectory of the case directory for
manpage diffs.
