OpenVMS System Manager's Manual
17.9 Using INSTALL to Install Known Images
The Install utility (INSTALL) stores information about images in
memory. Use INSTALL for the following reasons:
||For More Information
To conserve memory use for images that are used concurrently
To improve system performance
++On Alpha systems, to improve performance by using images with shared
To make executable images that require enhanced privileges available
for general use
To allow a nonprivileged image to call the privileged functions of a
To mark a sharable image as trusted so it can be invoked by privileged
The site-independent startup command procedure, STARTUP.COM, uses
INSTALL to install certain system images when the system boots. You use
INSTALL to install other selected images, according to the needs of
Installed images must be reinstalled each time the system reboots. To
do so, include INSTALL commands in the site-specific startup command
procedure SYSTARTUP_VMS.COM, as explained in Section 5.2.7.
The Install utility (INSTALL) only installs images that are linked with
the /NOTRACEBACK qualifier.
Note that INSTALL commands perform a different function than System
Generation utility (SYSGEN) INSTALL commands.
The following sections explain installed images and how to use the
17.9.1 Understanding Images and Known Images
An image is a collection of procedures and data bound
together by the Linker utility. Executable images can be executed (or
run) in a process, either by a command line interpreter (CLI) or the
$CREPRC system service. Usually, executable programs have the file type
There are three types of images:
An image linked with the /EXECUTABLE qualifier (or without the
/SHAREABLE qualifier) of the Linker utility. For more information,
refer to the OpenVMS Linker Utility Manual.
An image linked with the /SHAREABLE qualifier of the Linker utility.
Shareable images are sometimes referred to as linkable images because
they can be specified---implicitly or explicitly---as input files to
the link of another file. A shareable image is not copied into the
executable images that link with it. Thus, only one copy of the
shareable image needs to be on disk, no matter how many executable
images have linked with it. For more information, refer to the
OpenVMS Linker Utility Manual.
An image that does not run under the control of the operating system.
It is intended for standalone operation only. The content and format of
a system image differs from that of shareable images and executable
images. For more information, refer to the OpenVMS Linker Utility Manual.
When you install an image with INSTALL, the image is assigned
attributes and becomes known to the system. For this reason, an
installed image is also called a known image.
The image activator processes search lists in two passes, in order to
favor known images. On its first pass through the search list, the
image activator looks up images as known files. If needed, on a second
pass through the search list, the image activator looks up images on
17.9.2 Understanding Known File Entries
The system defines known images in internal data structures called
known file entries. Each entry identifies the file
name of the installed image and the attributes with which it was
installed (for information about attributes of installed images, see
Known file entries last only while the system is operating. If the
system is shut down or fails for any reason, you must reinstall all
known images after the system is rebooted.
17.9.3 Understanding Attributes You Can Assign to Known Images
By specifying appropriate qualifiers to INSTALL commands, you can
assign attributes to known images. Table 17-1 describes these
attributes and the qualifiers that are used to assign them to known
Table 17-1 Attributes of Known Images
The header of the image file (native images only) remains permanently
resident, saving one disk I/O operation per file access. For images
with single-block file headers, the cost is less than 512 bytes of
paged dynamic memory per file; for images with multiblock headers, the
cost varies according to the header block count. Images installed
header resident are implicitly installed permanently open.
The image file remains open, so access to the image does not require a
call to the file system.
Amplified privileges are temporarily assigned to any process running
the image, permitting the process to exceed its user authorization file
(UAF) privilege restrictions during execution of the image. In this
way, users with normal privileges can run programs that require
higher-than-normal privileges. This attribute (and the /PRIVILEGED
qualifier that creates it) applies only to executable images.
When the image is activated, the address space for the image is
protected against modification by user-mode code. This is critical for
shareable code that runs in kernel or executive mode.
On Alpha systems, code or read-only data for an image is made
permanently resident in a system region of memory. This improves
performance by using a special page mapping to reduce translation
buffer (TB) miss rates. The resident attribute applies to shareable or
executable images that have been linked with the qualifier
More than one user can access the read-only and non-copy-on-reference
read/write sections of the image concurrently, so that only one copy of
those sections needs to be in physical memory. (Copy-on-reference
sections always require a separate copy for each process.) The image is
implicitly declared permanently open.
When a shareable non-copy-on-reference writable section is removed from
physical memory (for paging reasons or because no processes are
referencing it), it is written back to the image file. Any updates made
by processes mapped to the section, therefore, are preserved (while the
initial values are lost). The image must also be declared shareable.
17.9.4 Determining Which Images to Install
You can install images for the following reasons:
- Improve image activation performance
- On Alpha systems, improve execution performance of shared images
- Conserve physical memory
- Enhance privileges of images during excution
Because an installed file requires system resources, such as paged
dynamic memory, install those files that most improve system
performance and site requirements. The INSTALL command LIST provides
information about installed images to help you evaluate the merits of
installing images. For example, the LIST command calculates the number
of times each image is accessed, and shows the number of concurrent
accesses, so you can determine if the installation of the images is
worth the overhead.
17.9.5 Installing Images to Improve Image Activation Performance
You can improve image activation performance by installing images that
run frequently. Image activation performance improves when programs are
installed because the operating system opens installed files by file ID
rather than by file name, thus eliminating costly directory operations.
Installing images as header resident further enhances activation
performance because the system avoids the overhead of I/O operations to
read the image header into memory.
To install an image as header resident, specify the /HEADER_RESIDENT
qualifier when you install the image.
This makes the header of the image file remain permanently resident,
saving disk I/O. Specifying the /HEADER_RESIDENT qualifier implicitly
makes the images permanently open.
Image headers are stored in paged dynamic memory. The size of the image
Frequently accessed images, critical to a site's operations, can be
installed as open images. To install an image as permanently open,
specify the /OPEN qualifier when you install the image. The image file
remains open, so access to the image does not require a call to the
file system. The cost of keeping an image file permanently open is
approximately 512 bytes of nonpaged dynamic memory per file.
17.9.6 Installing Images with Shared Address Data
Using shared address data on OpenVMS Alpha systems improves performance
at the following times:
- At run time, shared address data saves physical memory because of
increased memory sharing between processes.
- At image activation, shared address data reduces CPU and I/O time
because fixup is performed at installation time.
For details, refer to the INSTALL section of the OpenVMS System Management Utilities Reference Manual.
Explanations of terms related to shared address data follow.
- Image section
An image consists of a number of image sections. An image section
- Instructions (code)
- Read-only data (constants)
- Read/write data
- Shared known images
You can make an image a shared known image by using the following
$ INSTALL ADD image-name /SHARED
When you enter this command, the Install utility creates global
sections for read-only image sections, allowing the sections to be
shared by all the processes that run the image.
- Address data
One kind of image section contains address data. At execution time,
address data sections are read-only. However, the addresses are not
known until image activation; therefore, the image section is
read/write until the end of image activation. Addresses for a shareable
image generally vary with the process because different processes are
likely to have different collections of mapped images.
- Shared address data
The shared address data feature assigns unique P1 space
addresses for shareable images from the P1 image region. (The
IMGREG_PAGES system parameter determines the size of the P1 space.)
With the assigned address, the Install utility determines the content
address data section when the image is installed. A global section is
created to allow shared access to each address data image section.
Executable (main) images can also use shared address data sections;
these images are not assigned P1 addresses, however, because the base
address for an executable image is determined when the image is linked.
22.214.171.124 System-Provided Images
Many images that are part of the OpenVMS software product are installed
as shared known images with shared address data. This provides the
performance benefit without requiring the system manager to take any
126.96.36.199 Application Images
As system manager, you might choose to install additional images with
shared address data. In considering this option, you need to
investigate application dependencies on sharable images.
17.9.7 Installing Images to Conserve Physical Memory
You can conserve physical memory by installing images that usually run
concurrently from several processes. When an image is not installed, or
is installed without the shared attribute, each process running the
image requires private sections in memory. Shared images conserve
physical memory because only one copy of the code needs to be in memory
at any time, and many users can access the code concurrently. Use the
/SHARED qualifier to install images as shared images.
When you install an image with the shared attribute, permanent system
global sections are created. Execution of non-copy-on-reference global
sections requires only one copy per section to be in physical memory,
no matter how many processes are running the image to which the
The number of images you can install with the shared attribute is
restricted by the GBLPAGES and GBLSECTIONS system parameters. For more
information about these system parameters, refer to the OpenVMS System Management Utilities Reference Manual.
17.9.8 Installing Images to Enhance Privileges of Images
There are two ways to allow an image to execute in an enhanced
- Installing executable images with privileges to allow a
nonprivileged process to perform the privileged functions of the image.
Use the /PRIVILEGED qualifier with the INSTALL commands CREATE or
Installing an image with enhanced privilege can compromise system
security. Make sure the image does not enable a user to regain control
with extra privileges enabled.
- Installing protected shareable images (which are used to implement
user-written system services), allowing other, nonprivileged images to
execute select portions of privileged code without enhancing the
privileges of those individual images.
Use the /PROTECTED and
/SHARED qualifiers with the INSTALL commands CREATE or REPLACE.
188.8.131.52 Privileged Executable Images
A nonprivileged process can perform the privileged functions of an
executable image when the image is installed with privileges. Install
executable images with enhanced privileges by using the /PRIVILEGED
qualifier; amplified privileges are temporarily assigned to any process
running the image (executable images only), permitting the process to
exceed its user authorization file (UAF) privilege restrictions during
execution of the image. In this way, users with normal privileges can
run programs that require higher-than-normal privileges.
For an image installed with privileges to activate another image, such
as a shareable image, either by having it linked to the privileged
image or by using LIB$FIND_IMAGE_SYMBOL, the following conditions hold:
- The shareable image must be installed as a known image using
- Logical names and table names used to find the image must be
defined in executive or kernel mode. In particular, the standard
executive-mode definition of LNM$FILE_DEV translates only to
LNM$SYSTEM; definitions in the process, job, or group tables are not
- Only images linked with the Linker utility qualifiers /NODEBUG and
/NOTRACE can be installed with enhanced privilege.
184.108.40.206 Privileged Shareable Images
A privileged shareable image is a shareable image with defined entry
points that execute in inner (executive or kernel) mode. Inner-mode
entry points in shareable images are referred to as user-written system
To create a privileged shareable image, you must:
- Create a program section with the VECTOR attribute containing a PLV
(privileged library vector) data structure.
- Link the shareable image with the /PROTECT command qualifier or the
PROTECT= option of the Linker utility, so that the image acquires its
particular form of enhanced privileges.
- Use the /PROTECT command qualifier when all parts of an image
- Use the PROTECT= option when only part of a privileged shareable
image requires protection.
- Install the privileged shareable image with the Install utility,
specifying both the /PROTECTED and the /SHARED qualifiers. The
/PROTECTED qualifier assigns the protected attribute. The /SHARED
qualifier assigns the shareable attribute. See Section 17.9.3 for
information about these attributes.
You cannot grant privileges to a shareable image using the /PRIVILEGED
qualifier for the INSTALL commands ADD or CREATE. This qualifier works
only for executable images.
For more information about creating privileged shareable images, refer
to the OpenVMS Programming Concepts Manual.
17.9.9 Activating Images in a Privileged Context
When a process performs one of the following actions, the image
activator enters a restricted mode of operation similar to that entered
when a privileged program is run:
- Runs an executable or shareable image to which it has execute but
not read access.
- Activates an executable image installed with the /PRIVILEGE or
- Activates an image called by a privileged shareable image.
In this mode of operation:
- All shareable images activated during the life of the execute-only
image must be installed.
- The image activator directs OpenVMS RMS to use only trusted
logical names (logical names associated with executive or
kernel mode) when opening image files.
The executable image that calls an execute-only shareable image must be
installed with the /EXECUTE_ONLY qualifier, which enables the
executable image to activate shareable images to which the process has
execute but not read access.
The /EXECUTE_ONLY qualifier has meaning only for executable images.
This restriction assures that shareable images running in a privileged
context can be trusted to behave as expected.
17.9.10 Specifying File Names in INSTALL
When you use INSTALL commands, your file specifications must name
existing executable or shareable images. OpenVMS RMS resolves each file
specification using the following defaults:
- A device and directory type of SYS$SYSTEM
- A file type of .EXE
You can specify a specific version of the file as the known version of
the image with the CREATE or REPLACE command. Even if other versions of
the file exist, the version that you specify will be the version that
satisfies all known file lookups for the image.
17.9.11 Installing Images with INSTALL
Before performing this task, you should understand the following points:
- Attributes of installed images. For information, see Section 17.9.3.
- File specifications for the Install utility. For information, see
How to Perform This Task
- Give yourself the CMKRNL privilege by entering the following
$ SET PROCESS/PRIVILEGES=CMKRNL
- Invoke INSTALL by entering the following command:
- Enter the CREATE command in the following format:
CREATE file-spec [/qualifier...]
Specify one or more of the following qualifiers, depending on which
attributes you want to assign to the image:
/RESIDENT (Alpha systems only)
For more information about installing images, refer to the INSTALL
command CREATE in the OpenVMS System Management Utilities Reference Manual.
Installing the Install utility itself requires that a number of
shareable images have been previously installed. If any of those
required shareable images (such as SMG$SHR, LIBOTS, and so on) is
unavailable, the execution of the Install utility fails. Since INSTALL
will not work in this situation, you cannot simply install the missing
images. To work around this problem, redefine the INSTALL command as
$ DEFINE INSTALL SYS$SYSTEM:INSTALL.EXE;0
When you now enter the INSTALL command, the image activator does not
check the known files list for INSTALL.EXE, and the INSTALL command
will complete, allowing you to install the required shareable images.