MASTER(5,F) AIX Technical Reference MASTER(5,F)
-------------------------------------------------------------------------------
master
PURPOSE
Contains master configuration information.
DESCRIPTION
The master file is an attribute file that contains stanzas that describe all
device drivers and the system parameters that could be configured into the
system.
There are two general kinds of stanzas in the master file. They are:
o AIX device driver stanzas describing attributes relevant to the
configuration of the drivers.
o Stanzas describing system parameters that are relevant to the system
configuration.
The type keyword in each stanza identifies the kind of stanza it is. AIX
driver stanzas specify drivers to link into the kernel.
The use of extended characters in the master file is not supported.
AIX Driver Stanzas
A unique set of keywords is associated with each type of stanza. It is not
necessary, however, for a stanza to contain all the keywords associated with
that type. If a keyword is omitted from the stanza, the default is used.
Mandatory keywords must be supplied and are not defaulted. The name of each
stanza is a logical AIX driver name referenced in other stanzas.
The lines interpreted by the config and osconfig commands are:
block Indicates if the device driver supports block interface (TRUE or
FALSE).
char Interpreted by the config program. char has the same interpretation
as character; that is, the device is a CHARACTER device as opposed to
a BLOCK device.
config Indicates that this device has a customization helper program, which
provides assistance in decoding other options. This value is the
name of the helper program in the /etc directory.
devhdrreqd
Used by the config program. If TRUE, config adds the information
listed below to the conf.c file it builds. Note that this keyword
Processed November 7, 1990 MASTER(5,F) 1
MASTER(5,F) AIX Technical Reference MASTER(5,F)
should not be used in PS/2 systems unless the driver is included in
the base system provided, since the conf.c file is not compiled.
o If the device is a BLOCK device, a #define B_hndlr devmajor where
hndlr is replaced with the value from the prefix keyword and
devmajor is replaced with the value from the major keyword.
o If the device is a CHARACTER device, a #define C_hndlr devmajor
where hndlr is replaced with the value from the prefix keyword
and devmajor is replaced with the value from the major keyword.
o If the device is neither a BLOCK nor a CHARACTER device, a
#define M_hndlr devmajor where hndlr is replaced with the value
from the prefix keyword and devmajor is replaced with the value
from the major keyword.
o A #define U_hndlr naddrs where hndlr is replaced with the value
from the prefix keyword and subunits is replaced with the count
of the configured subunits (not the keyword) for the given
device.
o A #define N_hndlr naddrs where hndlr is replaced with the value
from the prefix keyword and naddrs is replaced with the number of
configured addresses for the device.
o A #include hndlconf.h where hndlr is replaced with the value from
the prefix keyword.
devtable Used by the config program. If TRUE, config adds the information
listed below to the conf.c file it builds. Note that this keyword
should not be used in PS/2 systems unless the PS/2 driver is included
in the base system provided, since the conf.c file is not compiled.
o An initialized declaration for struct dev_unit hndlrdevs[], where
hndlr is replaced with the value from the prefix keyword. This
structure is initialized with values taken from the device,
including stanzaname, and the driver, units, and address
keywords.
o If devtable is TRUE, then the name of the handler table is output
into the appropriate slot in the gensw table for the device. If
devtable is false, this slot initializes with a zero.
major Identifies the major device number for this driver. This is
mandatory.
mandatory Identifies this driver to be included into the AIX system kernel
whether or not the system file asks for it. If this value is TRUE,
include this driver.
Processed November 7, 1990 MASTER(5,F) 2
MASTER(5,F) AIX Technical Reference MASTER(5,F)
maxminor States the maximum number of minor devices this driver supports.
This number should agree with the driver code.
mpx Identifies a multiplexed special file when this value is TRUE.
prefix Provides a prefix for the driver routines. For example, if this
value is "abc", then the open routine in the driver is "abc"open.
This keyword is mandatory. Note that all drivers are assumed to be
archived into the system object libraries.
routines Identifies the routines actually defined for this driver. The
possible routines are open, close, read, write, strategy, ioctl,
init, and select.
struct Indicates the name of the iobuf structure associated with a
block-type device.
subunits This keyword is not used.
type Specifies the type of stanza. The possible values for device drivers
are:
alias Allows two names for the same device driver.
dev Indicates that this device is associated with an adapter.
sw Indicates that this device is not associated with hardware,
for example, the pseudo-device driver.
tty Specifies that this stanza is a line discipline device driver.
type=linedisc
Provides the same attributes as type=tty;.
block=TRUE:
Interpreted by the config program. This causes struct iobuf hndlrtab
entries to be generated in the conf.c file, with their addresses
initialized in devsw. Indirectly causes the hndlrstragety entry
points to be generated in the conf.c file, with their addresses
initialized in devsw. Causes the b entries in the device types
summary section of the configuration summary file. Causes block or
bl/ch entries in the block and character device tables section of the
configuration summary file.
nocount=TRUE:
Interpreted by the config program. Suppresses the declaration of int
hndlr_cnt = numunits. Normally output to the conf.c file, where
hndlr is replaced with the value from the prefix keyword and numunits
represents the number of configured devices of that type.
Processed November 7, 1990 MASTER(5,F) 3
MASTER(5,F) AIX Technical Reference MASTER(5,F)
oneonly=TRUE:
Interpreted by the config program. Causes an error to be generated
if more than one stanza for this device is encountered.
line=n Interpreted by the config. program. In stanzas with type=tty or
type=linedisc, this is used to indicate the position within linesw,
which this line discipline is to occupy.
The line interpreted by crash and pstat is:
ttyflg=alloc,ttysum,cntsym:
If a device supports tty output and thus maintains a tty structure,
the programs crash and pstat need to be able to read these
structures. They read the /etc/master file for information on how
these structures are allocated. The value of alloc describes the
method the driver uses to allocate the struct tty:
"static" -> struct tty xx_tty[COUNT];
"static*" -> struct tty *xx_tty[COUNT];
"auto" -> struct tty *xx_tty;
"auto*" -> struct tty *xx_tty;
The ttysym is the symbol name of the tty structure as declared in the
device driver.
The cntsym is the symbol name of the number of tty structures
present, as declared in the device driver.
System Parameter Stanzas
SYSTEM PARAMETER KEYWORDS:
The following is a list of keywords used to define system parameters in the
master file:
default The default value of the system parameter.
patchaddr The address in the kernel which stores the value of the parameter.
patchlen The parameter's length in bytes in the kernel.
symbol The name of the system parameter as it appears temporarily in the
defines of /tmp/sysgen.<machine-id>/conf.c; this file is removed
during system build.
type The type of the stanza. The following are the valid values of
type:
parm System parameters.
Processed November 7, 1990 MASTER(5,F) 4
MASTER(5,F) AIX Technical Reference MASTER(5,F)
special Special system parameters used in system
configuration.
text The file specified by default is included in conf.c
when /etc/config is run.
udev Special files like rootdev are for the system device.
SYSTEM PARAMETERS:
The following are object-code options for the PS/2 only:
ipc43 Includes TCP/IP code in the kernel.
kerndbg Includes kernel debugger code in the kernel.
merge Includes the DOS Merge code in the kernel.
nfserver Includes the NFS code in the kernel.
Note: All system parameters that are listed in /etc/master/ may have their
default values overriden by the values in /etc/system.
Site-Specific Parameters
Note: Stanzas which do not have the patchaddr attribute cannot be patched.
The parameters dump, dumplow, nswap, pipe, root, swap, swaplow, swapmap,
and swbufs are automatically configured by the kernel. However, they
can be overridden in /etc/system.
bhash Buffer hash group size.
buffers Buffers are used to provide the means to regroup I/O requests to a
block device. Often user and file system block sizes differ, and it
is more efficient to perform the I/O in an increment that optimizes
slow device access. So when writing to a block device, for example,
the kernel buffers the data until a convenient amount has been stored
for writing all at once to the device. Also, buffers allow data to
be cached so that disk I/O can be reduced. Normally this parameter
is set to 0 and at system run-time 20% of free memory is allocated to
buffers. This is bounded by the minbufs and maxbufs parameters.
However, by changing this value, these calculations are not
performed, and the user supplied value is used instead.
callout Callouts are used by the kernel as a means of performing some task
after a certain amount of time. It is possible that a user, upon
purchasing a new device driver, could cause the system to reach its
upper limit on the number of callouts allowed. Should this happen,
the system would panic with "Timeout table full". If the new
functionality added to the system is error-free, increasing the
number of callouts (which cost 24 bytes each) could solve the
problem.
Processed November 7, 1990 MASTER(5,F) 5
MASTER(5,F) AIX Technical Reference MASTER(5,F)
clist Clists (character lists) transfer data between user input and the
kernel. If there aren't enough clists, users notice long delays in
even simple character echos. If there are a lot of users on the
system, try increasing the number of clists. It costs 74 bytes per
extra member.
cluster_id
Specifies the cluster ID in the Internet Protocol (IP) format
(a.b.c.d.).
daylight Nonzero if daylight savings time in effect.
dcbuffs, dchash
Directory cache buffers are an optimization for performing directory
searches. For example, in the command cd /foo/bar, the following
happens: in the directory /, the entry foo is searched in a linear
fashion. Once the entry is found, its information is stored in a
directory cache buffer on the theory that if a user needed that
information once, he may need it again soon. The cache eliminates
the need to linearly search the directory for the entry foo if it is
referenced in the near future. To access the directory cache buffer
efficiently, a directory hash table is used. The dchash parameter
indicates the number of directory hash groups. The smaller the
number, the larger the size of the hash table. Increasing the number
of buffers could cause a performance increase in directory access.
Each buffer costs 52 bytes plus any increase in the size of the hash
table.
depsite Indicates that the kernel is to run on a site that does not store a
copy of the root file system.
dump Kernel core images (called a dump) are made when the system stops
working. On systems with a dump minidisk located on the hard disk,
the kernel auto-configures the dump properly. The user can change
the dump device, by placing an entry in the system file and
rebuilding the kernel using the newkernel command. The dump
parameter should reference any unused portion of a minidisk.
dumplow Offset in the dump minidisk to begin dumping a kernel image. This
offset is in 4K blocks. Normally the value of the dumplow parameter
is 0, but it can be changed to allow dumping to an arbitrary point on
a minidisk. This could allow for the dump minidisk to overlap with
another minidisk. The dumplow parameter is then set to last used
block of the minidisk.
errsize The size (in bytes) of the error buffer used for error logging. If
error logs are wrapping too much, increasing this number helps.
files This is the number of entries in the file table. The file table
contains 1 entry per open file access in the system. If users find
that programs are failing with ENFILE, the system administrator
Processed November 7, 1990 MASTER(5,F) 6
MASTER(5,F) AIX Technical Reference MASTER(5,F)
should check /dev/osm to discover which table overflowed. If it
contains "File table full at 'n' entries", try increasing the value
of the files parameter. The cost is 20 bytes per entry.
generic Indicates an installation-mode kernel.
ghash Specifies the optimum length of the hash chain for the mount table.
Typically, the smaller the ghash parameter, the better the
performamce.
gmounts Maximum number of mounted filesystems in cluster.
gpgscln Get pages clean. When the number of free pages on the swap device
plus the number of free memory pages divided by 2 is less than this
limit, the kernel removes unreferenced pages from working sets of the
process.
gpgslo, gpgshi
Get pages low/high. These are low and high water marks indicating
when to begin stealing memory from processes. If there is a lot of
free memory available, AIX waits until gpgslo free pages are
remaining before beginning to page out. Page out continues until
gpgshi is reached.
hz Frequency of hardware clock interrupts.
ihash Inode (incore inodes) hash group size.
killem When the amount of free swap space plus free memory space divided by
2 reaches this threshold, the kernel begins killing processes to free
more swap space and memory.
The gpgscln and killem parameters are used to calculate three
additional parameters (internal to the kernel):
danger = gpgscln - ((gpgscln - killem) / 3)
nofork = danger - ((gpgscln - killem) / 3)
killcur = killem / 2
Altogether, these five parameters indicate to the kernel what actions
to take when the number of free pages falls below the specified
value:
gpgscln: Get pages clean.
danger: Send SIGDANGER to all processes.
nofork: Disallow nonsuperuser forks.
killem: Kill processes with a large number of pages.
killcur: Kill current process.
Processed November 7, 1990 MASTER(5,F) 7
MASTER(5,F) AIX Technical Reference MASTER(5,F)
locks These are responsible for locking files. Should the number of locks
be too small, applications such as passwd will fail because the lockf
system calls will fail. Increasing the number of locks costs 32
bytes each.
locsite Uniquely identifies a TCF cluster site.
maxbufs The maximum number of buffers that the system allocates.
maxinod,mininod
The inode table (described by its minimum and maximum values)
contains mininod- one entry per open file in the system. This is
different from the files parameter in that, while a file may have
multiple entries in the file table, there is only one entry in the
inode table. If the system administrator checks /dev/osm and notices
"Inode table full at 'n' entries", then he should try increasing the
maximum number of inodes. The kernel begins allocating mininods and
progressively more (as needed) until maxinod is reached.
maxproc Maximum number of processes per user. If a user exceeds this limit,
he won't be able to run any more programs. It keeps one user from
tying up an entire system's resources.
minbufs The minimum number of buffers that the system allocates.
mounts Not used.
msfiles Maximum swap minidisks allowed.
msgmax The maximum message size that can be transmitted.
msgmnb The maximum bytes allowed on the message queue.
msgmni The number of message queue identifiers.
msgssz Message segment size.
msgtql Number of system message headers.
name Each machine has a name associated with it.
net Contains the major number of the TCF Network File System.
nfs Contains the number of the NFS logical device.
nmasz Target number of netmsgs per allocation.
nnetmsg Maximum number of netmsgs in system.
npacks Number of packlist structures.
Processed November 7, 1990 MASTER(5,F) 8
MASTER(5,F) AIX Technical Reference MASTER(5,F)
npbuf Number of physio buffers. These buffers are used when swapping out
processes and copying them between memory and the swap device.
nswap Size (in 4K blocks) of the swap minidisk. Together with the swaplow
parameter, these can describe any arbitrary region of the swap
device.
ntyunits The maximum number of AIX Access for DOS sessions that the host
machine can handle at once. The default value is 8. Allowing one
additional session costs 64 bytes plus 444 bytes once it's used.
osmsize Size of the osm buffer (in bytes).
phash Process hash group size.
pipe The bootable AIX minidisk containing the kernel.
procs Each process on the system has an entry in the process table. If
there are many simultaneous tasks on the system, the process table
could overflow. This creates a situation where users would often
find that any command entered does not execute. Each member of the
process table costs 224 bytes. However, there are many other
parameters which are allocated based on the size of the process
table, and so of course they will grow too.
props Size of propagation table.
ptrace Number of available local ipc structures.
pvsegs The number of process vsegs is based on this value. The formula used
is (number of processes * the pvsegs parameter). AIX assumes an
average of 6 pvsegs per process (pvsegs has a 32-byte overhead).
ptyunits The maximum number of pseudo-terminal login sessions that the host
machine can handle at once. The default value is 8. Allowing one
additional session costs 68 bytes plus 380 bytes once it is actually
used.
root The minidisk where the root file system is located.
rprocs Relevant to number of remote processes this site originates.
rsleep Remote sleep records.
rwake Remote wakeup records.
semaem Maximum value of the adjust on exit status.
semopm Maximum number of operations per semop system call.
semume Maximum number of undo entries per process.
Processed November 7, 1990 MASTER(5,F) 9
MASTER(5,F) AIX Technical Reference MASTER(5,F)
semvmx Maximum value of a semaphore.
semmni Number of semaphore identifiers.
semmns Upper limit on number of semaphores in the system.
semmsl Maximum number of semaphores per semaphore ID.
shash Sleep hash group size.
These parameters control the size of their respective hash tables.
If the hash tables are often empty, then the hash group sizes could
be increased, thereby freeing more memory. However, if the tables
are continually full, decreasing the hash group sizes increases the
size of the hash tables.
shmbrk The gap (in clicks) between data and shared memory.
shmseg Maximum number of shared memory segments per process.
shmmax Maximum shared memory segment size.
shmmin Minimum shared memory segment size.
shmmni Number of shared memory identifiers. The upper limit of the shmmni
parameter is dependent upon the procs parameter as defined in the
following formula:
1 < = shmmni < = 4 * procs - 50
By default, the procs parameter is set to 74. This can be verified in
the procs stanza in the /etc/master file and the definition of users
can be noted in the sysparms stanza of the /etc/system file. The
shmmni parameter has the following range:
1 < shmmni < 250
To use more than 250 shared memory segments, increase the value of
the procs parameter.
sites Maximum number of possible sites in network.
sphiwat Idle count that causes sever processes to shut down.
splowat Idle count that causes more sever processes to start up.
swap When there is insufficient room for all active processes on the
machine to reside in main memory, the kernel begins removing some
processes. The swap device is the temporary location where these
processes spend time waiting to run again. Like the dump device, the
swap device is auto-configured so the user need not worry about
Processed November 7, 1990 MASTER(5,F) 10
MASTER(5,F) AIX Technical Reference MASTER(5,F)
setting it. However, this can be overridden, and the swap device can
be set to any unused portion of a minidisk.
swaplow Starting offset in the swap minidisk (in 4K blocks) where swapping
occurs.
swapmap Maximum number of fragments of swap space.
swbufs Number of buffers for swapping.
timeslew: The time synchronization control parameter.
timezone Local time zone.
For this release, this value is always 1. Install/Maint changes the
machine name if the user wishes. If the machine name differs from
the default, aixps, Install/Maint places an entry in /etc/system to
indicate that this value will be patched when the user rebuilds his
kernel.
tokens Number of file access tokens.
tokloc Number of entries in token site request table.
users Estimate of number of users on site.
ulim_file The limit on the file size that a user may have. The units are in
512-byte blocks.
ulim_data The limit on the largest data segment size that a user may have. The
units are in bytes.
ulim_stack
The limit on the largest stack segment size that a user may have.
The units are in bytes.
vbuf The vbuf parameter is not used.
vsasz, pvsasz
These parameters are strictly for optimizing the number of dynamic
allocation calls. vsasz is the number of vsegs allocated at one
instance and pvsasz is the number of pvsegs. Increasing these values
decreases the calls to the memory allocator but also decreases the
amount of free memory available at a given instant. If vseg use is
low, having high values would mean that memory utilization is being
wasted. However, if vseg use is high, higher numbers could cause a
performance increase.
vsegs vsegs (virtual segments) describe virtual objects such as user data,
shared memory, executable text, and so on. Associated with each
process are pvsegs (process virtual segments). pvsegs relates the
vseg resources to a given process. Multiple processes may share the
Processed November 7, 1990 MASTER(5,F) 11
MASTER(5,F) AIX Technical Reference MASTER(5,F)
same vseg resource. The number of vsegs allocated reflects the
number of separate system resource objects allowed. The value for
this variable is based on the number of processes allowed for the
system, so it does not need to change. The current formula is
(number of processes * 4). Each vseg has a 104-byte overhead for the
data structure.
vhandr Virtual hand rate. The frequency in ticks at which the page daemon
wakes up and looks for memory to free. If this value is too high,
the system spends too much time scanning the page tables and
performance is decreased. If it is too low, then the system won't be
able to react quickly enough to fluctuations in system behavior, and
again performance decreases.
vhandfrc Virtual hand fraction. Controls when the pager starts to run. It
runs every vhandr ticks if free memory is greater than maximum memory
divided by vhandfrc.
EXAMPLE
The following sample system parameter stanza contains AIX Operating System
information:
locsite: type = parm
symbol = LOCSITE
patchaddr = loc_site
default = 0
FILE
/etc/master
RELATED INFORMATION
In this book: "mount," "attributes," "system," and "pty."
The newkernel, osconfig and config commands in AIX Operating System Commands
Reference.
See "Generating a New Kernel" in Managing the AIX Operating System.
Processed November 7, 1990 MASTER(5,F) 12