.ig
######################################################################## 
#
# File:         midaemon.1
# Description:  midaemon man pages
#
# (c) Copyright 1989-2008, Hewlett-Packard Development Company, L.P. 
#
######################################################################## 
.\" @(#) $Header: midaemon.1 2004/07/09 $ 
..
.TH midaemon 1 " "
.ds )H Hewlett-Packard Company
.SH NAME
midaemon - Performance Measurement Interface daemon. 
.SH SYNOPSIS
.BR midaemon 
[options]
.SH DESCRIPTION
The  
.I Measurement Interface
daemon,
.B midaemon,
provides an interface between ARM Transaction Tracking and 
the Performance Collectors. This program translates
trace data into Measurement Interface counter data using a memory based 
.I MI Performance Database
to hold the counters. This database is accessed by collector programs 
such as
.I glance\fP,
.I xglance\fP,
.I gpm\fP,
and
.I scopeux\fP.
     
The Measurement Interface daemon,
.I midaemon\fP,
must be executed as root
or with the set-user-id bit set to root. Attempting to run the 
.I midaemon
process without user-id of root results in an immediate termination.
     
     
The     
.I midaemon
backgrounds itself when started. Status and errors are written to the file:
.B /var/opt/perf/status.mi\fP.
     
.SH COMMAND LINE OPTIONS
     
.B midaemon
recognizes the following command line options: 
.TP 10
.B \-?
Displays the mode dependent available options on standard error. 
.TP
.B \-bufsize <value>
the
.I midaemon
process uses
.I bufsize
buffers to communicate with ARM Transaction Tracking. This option changes the 
buffer default value. The default value is defined by experience and 
validation
tests. Avoid changing this value unless the performance tools 
or the daemon process itself report losing buffers. If the passed value 
is less 
than 4096, the value is reset to the default value for performance 
reasons.
.br
DEFAULT:
.B 131072\fP bytes.
.TP
.B \-debug <level>
enables or disables the
.B midaemon
debugging mode. Possible debugging level values are: 
.br
0 - disables all debugging levels,
.br
1 - enables the first (lowest) level of debugging 
.br
2 - enables the second (medium) level of debugging 
.br
3 - enables the third (highest) level of debugging. 
.br
The debugging information is related to the midaemon activity and to the
collectors requests and is printed in the 
.B status.mi
file.
.br
DEFAULT:
.B 0 \fP[\fBoff\fP].
.TP
.B \-fg
allows the
.I midaemon
process to execute in foreground. This option should only be used when 
debugging.
.br
DEFAULT:
.B off\fP.
.TP
.B \-k
sends a termination request to an active 
.I midaemon
process. This will cause the running 
.I midaemon
to release the MI Performance Database and to exit.
If performance collectors are still active and attached to the MI 
Performance Database the active
.I midaemon
will ignore the termination flag and will continue to run. If this 
daemon 
process was in the debugging level 1, a message 
describing the attempt to terminate is written to the 
.B status.mi
file. If an
.I midaemon
process has been killed because of a SIGKILL signal, the 
.B \-k
option can be used to delete the still existing MI Performance Database. 
.br
DEFAULT:
.B off\fP.
.TP
.B \-K
sends the no_permanent and termination requests to an active 
.I midaemon
process. This will cause the running 
.I midaemon
process to become no_permanent, to release the MI Performance Database 
and to exit. This option is as an alias of the
.B 'no_p -k'
options.
.br
DEFAULT:
.B off\fP.
.TP
.B \-lvm_off
This specifies the LVM collection off request to the midaemon. This means that 
midaemon process wont collect LVM metrics when started with this option.
This option is only available in Linux.
.br
DEFAULT:
.B off\fP.
.TP
.B \-mlock
specifies the locking of the MI Shared Memory Performance Database in 
memory. By
default, MI does not lock the database and pages in only the active 
memory
pages, creating less intrusiveness on the system memory utilization. 
.br
DEFAULT:
.B off\fP.
.TP
.B \-no_mlock
tells the
.I midaemon
process not to lock the MI Shared Memory Performance Database in 
physical 
memory. In control mode, this request can be sent to the active 
.I midaemon
process to unlock the database.
.br
DEFAULT:
.B on\fP.
.TP
.B \-no_p
sends the no_permanent request to the 
.I midaemon
process. This means that when the last performance tools will exit, the 
.I midaemon
process will exit by releasing the MI Performance Database. 
.br
DEFAULT:
.B off\fP.
.TP
.B \-normal_prio
specifies that the
.I midaemon
process starts in the normal scheduling priority.
.br
DEFAULT:
.B off\fP.
.br
WARNING: This option must not be used if ARM instrumented data is collected. 
If this option is used when ARM instrumented data is collected, the transaction
throughput handled by
.I midaemon
is affected. 
.br
The local zones runs in normal priority.
.br
On Solaris local zones, the default value is ON and it cannot be overridden. 
midaemon cannot be moved to real time priority inside local zones as priocntl 
does not work due to privilege issues inside minimum configured local zones.
.TP
.B \-p
specifies that the
.I midaemon
process runs permanently, even if no performance tools are attached to 
the 
Measurement Interface. To stop this behavior, the control mode 
.B \-no_p
request has to be sent to the active daemon. To stop a permanent daemon, 
the 
requests
.B \-no_p,
.B \-k
or
.B \-K
should be used.
.br
DEFAULT:
.B on\fP.
.TP
.B \-rtprio <priority>
specifies the process real-time priority to be used for the 
.I midaemon
process. The default value was chosen by experience and tests with other 
system
daemons.
.br
DEFAULT:
.B Real time priority.\fP.
.br
On Solaris local zones, real-time  priority for midaemon is disabled.
.TP
.B \-sizes
specifies that the
.I midaemon
process writes the sizes of the enabled Classes of the MI Shared Memory 
Performance Database in the
.B status.mi
file.
.br
DEFAULT:
.B off\fP.
.TP
.B \-smdaddr <address>
specifies the virtual address, in hexadecimal, to be used for the
MI Shared Memory Performance Database.
The default address is kernel dependent. This option is particularly useful on
X86 64-bit Linux systems with randomized address space, when requesting
more than the standard shared memory virtual set size. An address typically
working on such systems is
.B 0x400000000000.
.br
DEFAULT:
.B kernel dependent\fP.
.TP
.B \-smdvss <value>
specifies the maximum virtual set size of the MI Shared Memory 
Performance 
Database. This option limits the amount of memory used by the database 
and 
should be used to limit the dynamic expansion of the performance 
Classes.
The default size is kernel dependent. The 
.B \-sizes
option can be used to determine the MI Performance Database sizing 
values.
.br
DEFAULT:
.B kernel dependent\fP.
.TP
.B \-timeout <value>
specifies that the
.I midaemon
process sets a specific timeout value for the kernel instrumentation 
interface.
Do not modify the default value, unless in a debug situation. 
.br
DEFAULT:
.B 300 msecs\fP.
.TP
.B \-T
specifies that the active
.I midaemon
process terminates immediately without any regard to attached 
performance tools.
This option is for use only during software installation or removal 
procedures.
     
.br
DEFAULT:
.B off\fP.
.TP
.B \-udts <value>
specifies the maximum number of UDT entries for the
.B ARM Transaction Tracking data class in the MI Performance Database. 
DEFAULT:
.B 20\fP.
.TP
.B \-V
prints the
.I midaemon
version to standard out.
     
.SH MI ERROR MESSAGES
In case of errors,
.I midaemon
was designed to use well defined exit values and to write explicit error
messages in the
.I /var/opt/perf/status.mi
file. The error meesages are formatted: 
.br
- name of the running midaemon program - timestamp, 
.br
- name of the routine generating the error - error message, 
.br
- error message generated by a perror(3C) call if a system call has failed.
This information may be of use when reporting problems.
     
.SH EXAMPLES
.br
The standard
.I midaemon
process execution is
.br
     
% midaemon
     
.br
To specify the MI Shared Memory Database size up to 1 Megabyte at the 
MI 
initialization:
.br
     
% midaemon -smdvss 1M
.br
     
.SH WARNINGS
.br
The
.I midaemon
program is automatically executed by performance tools such as 
.B GlancePlus (glance, gpm or xglance)\fP
or
.B HP Performance Agent (scopeux)\fP.
However, it can be executed manually to customize the 
.I MI Performance Database
or to send to the active
.I midaemon
process specific requests.
     
If the creation of the
.B status.mi
file failed,
.I midaemon
will use the error file
.I /tmp/status.mi\fP.
     
.SH SEE ALSO
\fBttd(1)\fP, \fBttd.conf(4)\fP, \fBarm(3)\fP.