Template Version: @(#)sac_nextcase 1.66 04/17/08 SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
rpc.kstatd: Remote Kstat Access Service
1.2. Name of Document Author/Supplier:
Author: Nicolas Williams
1.3 Date of This Document:
05 August, 2008
4. Technical Description
1. Introduction
1.1. Project/Component Working Name:
rpc.kstatd: Remote Kstat Access Service
1.2. Name of Document Author/Supplier:
Erik O'Shaughnessy
1.3. Date of This Document:
08/05/08
2. Project Summary
2.1. Project Description:
This project introduces a new RPC service which enables remote
read-only access to kernel statistics (kstats). The project
consists of: a RPC protocol description and header file, a RPC
daemon, and extensions to libkstat(3LIB), Kstat(3perl) and
kstat(1m) to utilize the service.
4. Technical Description:
4.1. Details:
This project has several dimensions: a new RPC protocol definition,
a new RPC daemon, additions to the libkstat API and finally changes
to the perl kstat tools to take advantage of the new service.
Future projects may wish to extend other kstat-based observation
tools to take advantage of this new feature (vmstat, iostat,
mpstat, etc).
RPC Kstat Protocol
------------------
The RPC kstat protocol seeks to emulate the interfaces
offered by /dev/kstat, specifically:
KSTAT_IOC_CHAINID
KSTAT_IOC_READ
KSTAT_IOC_WRITE
This approach is desirable so that libkstat does not require
extensive retooling to take advantage of the new service.
The RPC cognates are:
KSTAT_RPC_CHAINID
KSTAT_RPC_READ
KSTAT_RPC_WRITE
It should be noted that while the write interface is offered
by the protocol, the daemon which implements the service does
not support the remote writing of kstat data.
The protocol definition and header files will be shipped as:
/usr/include/rpcsvc/kstat.x
/usr/include/rpcsvc/kstat.h
The RPC program number has been allocated and is recorded as
100149.
The protocol definition also supplies XDR routines for kstat
specific data:
bool_t xdr_kstat_t(XDR *, kstat_t *)
bool_t xdr_kstat_hdr(XDR *, kstat_t *)
bool_t xdr_kstat_data(XDR *, kstat *)
bool_t xdr_kstat_named(XDR *, kstat_named_t *, char *)
bool_t xdr_kstat_intr(XDR *, kstat_intr_t *)
bool_t xdr_kstat_io(XDR *, kstat_io_t *)
bool_t xdr_kstat_timer(XDR *, kstat_timer_t *)
These routines are not automatically generated and future
changes/additions to the kstat pantheon of data structures
will need to be tracked here. A comment should be placed in
/usr/include/sys/kstat.h to warn future developers of the
need to update kstat.x if data structures change or are added.
rpc.kstatd
----------
The daemon which implements the protocol will be located at:
/usr/lib/netsvc/kstatd/rpc.kstatd
The daemon uses RPC automatic multi-threading, spawning a maximum
number of threads equal or less than the number of configured CPUs
discovered upon daemon start-up. Changes in CPU availability during
the lifetime of the daemon are not tracked. Threads are allocated
and released as client request load dictates, starting with the
minimum number of threads required.
The daemon uses syslog to report error conditions.
libkstat API additions
----------------------
In order to utilize the RPC service, libkstat will get a new
flavor of kstat_open:
kstat_ctl_t *kstat_open_host(char *)
This new function is similar to the existing kstat_open(),
except that it allows the caller to supply a string which
can be used to locate a suitable remote source of kstats. The
current proposed implementation interprets the string as a
hostname or IPv[4|6] address which is passed to RPC for resolution.
Future enhancements could include support of URIs using
alternate RPC mechanisms (SOAP, XML-RPC, etc) or any other
new technology which may be deemed appropriate.
All other libkstat API usage will remain the same.
kstat(1m) and Kstat(3perl)
--------------------------
The final change introduced by this project is to enhance kstat(1m)
and the Sun supplied kstat perl library module, Kstat(3perl), to
take advantage of the alternate open interface.
This project proposes adding a new command-line option to
kstat(1m) which takes a hostname or IPv[4|6] address as an
argument. The author recommends "-H" but will bow to the wishes
of the command-line UI deities.
Subsequent output from a non-localhost source will have the
source identifier embedded so as to be able to disambiguate
output from different sources. This will have the side-effect
of disrupting tools which parse kstat(1m) output.
Given that perl function calling conventions are very flexible,
this project proposes to add a new "host=>hostname" argument to
the new() method in Kstat.pm. The XS component which implements
the new method will be updated to process the new argument and
call kstat_open_host() with the requested hostname.
4.2. Bug/RFE Number(s):
6733853 RPC Service for Remote Access to Kstat Data
4.4. Out of Scope:
Updating other kstat-based observation tools (vmstat, mpstat,
iostat, etc) is desirable but not necessary for this project
to move forward.
4.5. Interfaces:
Exported Interfaces
===================
/usr/include/rpcsvc/kstat.x Committed
/usr/include/rpcsvc/kstat.h Committed
KSTATPROG = 100149 Committed
KSTATVER = 1 Committed
KSTAT_RPC_CHAINDID = 1 Committed
KSTAT_RPC_READ = 2 Committed
KSTAT_RPC_WRITE = 3 Committed
kstat_rpc_chainid_1() Committed
kstat_rpc_chainid_1_svc() Committed
kstat_rpc_read_1() Committed
kstat_rpc_read_1_svc() Committed
kstat_rpc_write_1() Committed
kstat_rpc_write_1_svc() Committed
kstatprog_1_freeresult() Committed
xdr_kstat_t() Committed
xdr_kstat_hdr() Committed
xdr_kstat_data() Committed
xdr_kstat_named() Committed
xdr_kstat_intr() Committed
xdr_kstat_io() Committed
xdr_kstat_timer() Committed
xdr_size_t() Committed
kstat_ctl_t *kstat_open_host(char *) Committed
/usr/bin/kstat .. [-H hostname] Committed
Imported Interfaces
===================
/dev/kstat
/usr/include/sys/kstat.h
KSTAT_IOC_CHAIN_ID
KSTAT_IOC_READ
4.6. Doc Impact:
New: /usr/share/man/man1m/rpc.kstatd.1m
New: /usr/share/man/man3rpc/kstat.3rpc
Updated: /usr/share/man/man1m/kstat.1m
Updated: /usr/share/man/man3lib/libkstat.3lib
Updated: /usr/share/man/man3kstat/kstat_open.3kstat
4.7. Admin/Config Impact:
Responsibility for initiating and restarting the daemon will
be delegated to inetd(1m). Administrative control will be
performed using svcadm(1m) and svcs(1). The daemon's SMF
service identifier will be:
svc:/network/rpc/kstat:default
The service currently has no configurable attributes.
4.11. Security Impact:
This service will be shipped unconfigured by default and will
require an administrator to explicitly enable it. Given that
/dev/kstat does not require any specific priviledge for
read-only access, no authentication or authorization of RPC
requests is performed. This behavior is in keeping with the
rest of the other RPC-based APIs currently shipped with Solaris
( rstat, rusers, rwall, etc ).
4.12. Dependencies:
/dev/kstat - kernel driver which provides data to user space
5. Reference Documents:
PSARC 1999/495 kstat(1m) and kstat(3perl)
RFE 1099474 Need a more powerful kernel statistics
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
