admkernel(1M) DG/UX R4.11MU05 admkernel(1M)
NAME
admkernel - manipulate the system's kernel
SYNOPSIS
admkernel -o autoconfigure [ -C [ -B client-boot-device ] ] [ -d
build-directory ] system-name
admkernel -o build [ -d build-directory ] [ -X ] system-name
admkernel -o build -R release-area -c client [ -X ] system-name
admkernel -o configure [ -C [ -B client-boot-device ] ] [ -d build-
directory ] [ -qv ] [ -e default-config-file ] [ -g
default-config-file ] [ -i custom-config-file ] [ -s
software-package ] [ -X ] system-name
admkernel -o configure -R release-area -c client [ -qv ] [ -e
default-config-file ] [ -g default-config-file ] [ -i
custom-config-file ] [ -s software-package ] [ -X ] system-
name
admkernel -o install [ -R release-area ] [ -c client ] [ -Cr ] [ -d
build-directory ] [ -X ] system-name
admkernel -o link [ -R release-area ] [ -c client ] [ -c client-list
] system-name
admkernel -o list [ -qv ] [ -d build-directory ] [ system-name ... ]
DESCRIPTION
admkernel configures, builds and installs system kernels.
A system's kernel is the image which is loaded into memory when
booting the system. The admkernel command manages this system's
kernel and may also manage the kernels of any operating system
clients of this system.
Operations
autoconfigure
Create a system file in the build-directory which lists the
hardware devices currently attached to the system, as well
as the pseudo-devices and configuration variables of any
loaded packages. The resulting system file, system.system-
name, can be used to build a custom kernel for the system.
build Build a new system kernel from an existing system file in
the build-directory. This includes running the config(1M)
program on a system file and compiling the resulting file
(with cc(1) and ld(1)) with the kernel libraries into a
bootable kernel image, called dgux.system-name. Note that
kernels will be built for the PRIMARY release area unless
the -R option is set.
configure Configure a system file by replacing the existing system
file that contains device and parameter specifications.
The system configuration file is generated from the
persistent default-config-files and/or custom-config-files.
The resulting system file can be used to build a custom
kernel for the system
If no custom-config-files are specified, two default-config
files are used to generate the system file:
system.device.system-name and system.params.system-name.
Other options allow for the exclusion of either or both of
the default-config-files, as well as inclusion of custom-
config-files. The order of inclusion of config-files in the
system file is: the default device file, followed by the
default params file, followed by any custom config-files in
the order they were specified in the -i option.
Any modifications made to the file system.system-name will
be lost the next time a kernel configure operation is
performed. For changes to persist they must be made to in
the system.device.system-name and system.params.system-name
files.
Kernels are configured for the PRIMARY release area unless
the -R option is set.
install Copy a kernel from the build-directory into some other
directory where it can be booted as the system's kernel.
If the operation is successful, the kernel is deleted from
the build directory. Note that kernels will be installed
in the PRIMARY release area unless the -R option is set.
link Link a kernel to the default kernel (/dgux) for this host
or for clients of this host. Note that kernels will be
linked in the PRIMARY release area unless the -R option is
set.
list Display information about system-names. If there is no
system-name or the system-name is all, the list of valid
system-names is displayed.
Options
-B client-boot-device
Configure the OS client kernel to boot from the client-
boot-device device. This option is meaningful only when
used with -C. The default is dgen().
-C Perform the operation for an operating system client. For
the autoconfigure operation, this option indicates that the
kernel will be used by an operating system client. For the
install operation, this option indicates that the kernel
will be installed for an operating system client of this
host.
-c client or client-list
When used with -R, the operation is performed in the
specified release area for the specified client. client
must be singular when used with the -R option.
For the Link operation, a list of clients can be specified
when the -R option is not used. In this case, a single
kernel is linked as the default kernel for each client in
client-list. client-list is either a comma-separated list
of clients, or may be "all" to indicate that the kernel
should be linked for all clients of this host.
-d build-directory
The directory in which system files and new kernels reside.
The default is /var/Build
-e default-config-file
Exclude the specified default-config-file(s) when creating
a new system configuration file. Accepted values for the
default-config-file parameter include "device" and
"params". This option can be used with the -i option to
create a system configuration file using config files other
than the default parameters and/or device files.
The default behavior is to include both the
system.device.system-name and system.params.system-name in
the system.system-name file.
-i custom-config-file
Include the specified custom-config-file(s) by appending
them to the end of the new system configuration file.
Use of a simple file name with no directory path
specification indicates that the configure operation should
use the file in build-directory/system.custom.system-name.
Use of a name with directory path indicates that the
operation should include the file as exactly referenced by
path and name. Files are referenced relative to the
effective build-directory. To include a file in the build-
directory that does not follow the system.custom.system-
name convention, reference it by ./custom.
By default the system file will be generated from the
appropriate default-config-files.
-g default-config-file
Generate a new version of one or both of the default-
config- files before creating a new system file. Accepted
values for the default-config-file parameter include
"device", "params" "and/or generic". Please note that
regenerating the "device" default-config-file will
overwrite existing device customizations and regenerating
the "params" config file will overwrite existing parameter
customizations. The "generic" option will generate a new
"device" default-config-file that contains specifications
for all valid DG/UX devices. When used with the -R
release-area option the -g generic option provides for
standaside kernel configurations where one host can
configure a kernel for another host or node.
The -g option is useful for automatically configuring new
devices into the device default-config-file. However, as
noted above, existing device customizations will not
persist.
By default both default-config-files (device and params)
are left as is if they already exist. Non-existent default-
config-files will be generated automatically unless the -e
option is used.
-R release-area
Configure, build, install or link a kernel from the
specified release-area using the appropriate kernel
libraries, commands, protos, configuration files, etc, from
that release-area. Default is the release currently
mounted at / and /usr. This option is only meaningful when
used with -c.
-s software-pkg
An #include entry for the software packages prototype
kernel configuration file is appended to the default-config
params file. system.params.system-name if it is not
already in the file. This option is useful for configuring
new software package variables into the parameters default-
config-file.
Note that each #include entry in the config file is
prefaced by a comment line identifying the software
package. This comment line is the tag that indicates to the
admkernel command that a given software package has been
included in the config file. If you leave the comment line
and remove the actual #include line then the configure will
assume the package has been configured into the system
file. This can be useful for turning off messages during
kernel builds about installed packages that have not been
configured.
By default the default params config file is left as is.
-r Remove the old kernel ( dgux.system-name ), if it exists.
Without this option, the old kernel is saved to
dgux.system-name.old before the new kernel is installed.
-X eXpress. Execute the additional operations required to
complete the process of linking in a new kernel. When used
with the -o configure operation, the appropriate build,
install, and link operations are also performed if the
initial configure executed without error. Likewise, when
the -X switch is used with the -o build operation, the
appropriate install, and link operations are also
performed. When used with -o install operation, the
appropriate link operation is performed.
-q Quiet. Omit header lines from the output of the list
operation.
-v Verbose. Include header lines in the output of the list
operation. This option is enabled by default.
EXAMPLES
To generate a system file based on the system's current
configuration, use
admkernel -o autoconfigure aviion
or
admkernel -o configure -g device,params aviion
which creates /var/Build/system.device.aviion and
/var/Build/system.params.aviion and then concatenates those two files
to a new version of /var/Build/system.aviion
To generate a system configuration file based on a regenerated device
default-config-file and the current parameter default-config-file,
use
admkernel -o configure -g device aviion
which creates /var/Build/system.device.aviion, keeps the existing
/var/Build/system.params.aviion and then concatenates those two files
to a new version of /var/Build/system.aviion
To generate a system configuration file based on information
contained in the default config-files, use
admkernel -o configure aviion
which uses the existing /var/Build/system.device.aviion, and
/var/Build/system.params.aviion and then concatenates those two files
to a new version of /var/Build/system.aviion
To generate a system configuration file which includes parameters
necessary for the specified packages, use
admkernel -o configure -s aPackage,anotherPackage aviion
which uses the existing /var/Build/system.device.aviion, and adds an
include entry for the aPackage and anotherPackage to the
/var/Build/system.params.aviion and then concatenates those two files
to a new version of /var/Build/system.aviion
To generate a system configuration file based on the default config
files as well as configuration information contained in a custom-
config file located in some other part of the system, use
admkernel -o configure -i /local/sysdefs/myConfig aviion
which uses the existing /var/Build/system.device.aviion, and
/var/Build/system.params.aviion as well as the user specified file
/local/sysdefs/myConfig and then concatenates those three files to a
new version of /var/Build/system.aviion
To build, install, and link a kernel based on the "aviion" system
file, use
admkernel -o build aviion
admkernel -o install aviion
admkernel -o link aviion
which builds dgux.aviion and links it to /dgux.
To build, install, and link a kernel for two diskless clients of this
host, first create /var/Build/system.diskless with the appropriate
parameters, then use these command lines
admkernel -o build diskless
admkernel -o install -C diskless
admkernel -o link -c myclient,yourclient diskless
ENVIRONMENT VARIABLES
Several environment variables are used to control which tools are
used for building new kernels. Some of the more useful variables are
listed below.
CC Name of the compiler, with its options, to use when
compiling the configuration file into an object file. The
default is "/usr/bin/gcc -mno-underscores".
LD Name of the linker, with its options, to use when linking
the kernel libraries to form the kernel image. The default
is "/usr/bin/ld -x -F 0555".
LIB_DIR Directory where kernel libraries are found. Define this
variable to build with a non-default set of libraries. The
default is "/usr/src/uts/aviion/lb".
You should exercise great care when defining these variables in your
environment, because some combinations of settings may cause the
resulting kernel image to be unbootable.
FILES
/var/Build
Build directory.
/var/Build/system.device.system-name
Default-confic device file which by default contains the
output of the probedev(1m) command. This file can be edited
to add, modify or delete system device specifications. The
file is not modified by the configure operation unless the
-g device option is used.
/var/Build/system.params.system-name
Default-config parameter file which by default contains the
generic parameters suitable for all systems as well as
#include entries for each package on the system with a
prototype system file. This file can be edited to add,
modify or delete system device specifications. The file is
not modified by the configure operation unless the -g
params option is used.
/var/Build/system.system-name
This file is regenerated as part of each configure
operation from the config files specified for the
operation. Modifications made to this file will not persist
across configure operations.
/usr/src/uts/aviion/cf
Directory containing prototype system files.
/dgux.system-name
Name of the installed kernel for this host.
/srv/release/PRIMARY/_Kernels/dgux.system-name
Name of the installed kernel for operating system clients
of this host.
OUTPUT
The list operation displays the system name and date of last
modification for each of the system-names.
DIAGNOSTICS
Warnings
- The file system.system-name does not exist. It will be created
from the prototype files in /usr/src/uts/aviion/cf.
Errors
- There is no C compiler on the system.
- One of the necessary directories under /usr/src/uts/aviion is
missing or incomplete.
- The kernel failed to configure (with config(1M)) or failed to
link (with ld(1)).
- One of the clients in the client-list does not exist.
Exit Codes
0 The operation was successful.
1 The operation was unsuccessful.
2 The operation failed due to access restrictions.
3 There was an error in the command line.
SEE ALSO
cc(1), config(1M), ld(1), probedev(1M), sysadm(1M), system(4).
cap_defaults(5).
NOTES
The autoconfigure operation uses probedev(1M) to determine which
hardware devices to include in the system file.
The autoconfigure and build operations require write permission in
the build-directory1. The install and link operations require write
permission in the target root directory. To perform these four
operations, a user must have appropriate privilege. On a traditional
DG/UX system, appropriate privilege means that you have superuser
privilege, or an effective UID of root. See the
appropriate_privilege(5) man page for more information.
On a system that supports the DG/UX Capability option, appropriate
privilege is defined as having one one or more specific capabilities
enabled in the effective capability set of the user. See
cap_defaults(5) for the default capabilities for this command.
Licensed material--property of copyright holder(s)