crle - configure runtime linking environment
crle [-FuvV] [-64] [-a name] [-A name] [-c conf] [-e env] [-E env]
[-l dir] [-o dir] [-s dir]
The crle utility provides for the creation and display of a runtime linking configuration file. The configuration file is read and interpreted by the runtime linker, ld.so.1(1), during process startup. The runtime linker attempts to read a default configuration file for all processes. For 32–bit processes, the default configuration file is /var/ld/ld.config. For 64–bit processes, the default configuration file is /var/ld/64/ld.config.
Without any arguments, or with just the –c option, crle displays configuration information. This information includes the contents of a configuration file, any system defaults and the command-line required to regenerate the configuration file. When used with any other options, a new configuration file is created or updated.
The runtime linker can also be directed to an alternative configuration file by setting one of the LD_CONFIG family of environment variable. LD_CONFIG applies to both 32–bit and 64–bit programs. Since 32–bit and 64–bit configuration files differ, a single configuration file cannot be used for both class of object. Hence, LD_CONFIG can adversely affect program execution in cases where a program of one class executes a program of the other class. LD_CONFIG cannot be successfully used in this case. Therefore, the use of the LD_CONFIG_32 and LD_CONFIG_64 environment variables, that precisely target the appropriate class of process, is recommended.
Creating an incorrect configuration file in the standard location, /var/ld, can prevent programs from running, and can therefore be difficult to recover from. To guard against this situation, crle performs sanitization of library directory paths. See the –F option. It is recommended that new configuration files first be created in a temporary location. Then set the appropriate LD_CONFIG environment variable to this new configuration file. This setting causes the new configuration file to be used by the runtime linker instead of any default. After verification, the new configuration file can be moved to the default location if desired. At any time, the environment variable LD_NOCONFIG can be set to any value to instruct the runtime linker to ignore any configuration files. This setting can prove useful during experimentation.
A configuration file can contain the following information.
The runtime linker uses a prescribed search path for locating the dynamic dependencies of an object. This search path starts with the components of any LD_LIBRARY_PATH definition, followed by the components of an object's runpath. Finally, any default search paths specific to the object's class are used. This last component of the search path can be expressed within the configuration file. Typically, use of this facility should be augmented with any system default. See the –F, –l and –u options.
When processing a secure application, the runtime linker restricts the use of LD_LIBRARY_PATH searches, and $ORIGIN token expansion. See Runtime Security in Oracle Solaris 11.4 Linkers and Libraries Guide. In addition, the directories from which preload and audit libraries can be located are also restricted. The path names that are associated with preload and audit libraries are restricted to known trusted directories. Trusted directories can be expressed within the configuration file. Typically, use of this facility should be augmented with any system defaults. See the –F, –s and –u options.
Any environment variable interpreted by the runtime linker can be specified within the configuration file.
Shared objects can have alternative objects specified for use at runtime.
Defining additional default search paths, or additional trusted directories can be useful for administrators who wish to install third party software in a central location, or otherwise alter the search path of applications that might not have been coded with a suitable runpath.
The declaration of alternative objects provides a means of replacing dependencies other than by using symbolic links or requiring LD_LIBRARY_PATH settings.
The declaration of environment variables that are interpreted by the runtime linker provides a means of centralizing their definition for all applications.
The following options are supported.
Specify to process 64–bit objects, the default is 32–bit. Use –64 to create a 64–bit specific configuration file.
Create an alternative path name for name, to a file with the same name, specified by a preceding –o option. The alternative path name is added to the configuration file.
The actual alternative file must be supplied by the user. Multiple occurrences of this option are permitted. name must be a file, and cannot specify a directory.
Create an optional alternative path name for name. This alternative path name is added to the configuration file.
This option mimics the –a option, except that if the alternative is unavailable at runtime, the original object name is used. This model mimics the use of auxiliary filters. See Generating Auxiliary Filters in Oracle Solaris 11.4 Linkers and Libraries Guide.
Specify to use the configuration file name conf. If this option is not supplied, the default configuration file is used.
Specify a replaceable environment variable, env. Only environment variables that are applicable to the runtime linker are meaningful. Multiple occurrences of this option are permitted. This option is similar to the –E option. However, the option differs in how configuration file definitions, and process environment definitions of the same name are resolved at runtime.
A definition established in a configuration file can be overridden by a process environment definition, or can be suppressed by a null-value process environment definition.
In other words, these configuration file definitions can be replaced, or removed by the process environment at runtime.
Specify a permanent environment variable, env. Only environment variables that are applicable to the runtime linker are meaningful. Multiple occurrences of this option are permitted. This option is similar to the –e option. However, the option differs in how configuration file definitions, and process environment definitions of the same name are resolved at runtime.
Environment variable definitions that are meaningful to the runtime linker fall into one of two categories. Singular definitions are definitions such as LD_NOLAZYLOAD=1 and LD_DEBUG_OUTPUT=file. List definitions, which can take one or more values, are definitions such as LD_LIBRARY_PATH=path, and LD_DEBUG=files,details.
A singular definition that is established in a configuration file takes precedence over a process environment definition. A list definition that is established in a configuration file is appended to a process environment definition. Any definition that is established in a configuration file can not be suppressed by a null-value process environment definition.
In other words, these configuration file definitions can not be replaced, or removed by the process environment at runtime.
Disable the default sanitization of directory paths applied when processing the –l, –s, and –u options. All directories specified are added to the specified path as given, and without interpretation.
When the –F option is not specified, crle applies the following rules to path directories specified with –l, or –s, or read from an existing configuration file. These checks prevent the creation of an incorrect configuration file that would prevent programs from running, and produce optimal paths that do not contain redundant entries.
All specified directories are checked to ensure that they exist, and are in fact directories rather than a different file type.
Duplicate directories are discarded, keeping only the initial instance. This includes duplicates that are lexically different, but which resolve to the same directory, as can occur when symbolic links are involved.
A check is made to ensure that all system default directories have been included.
All references to system default directories are modified as necessary to use the same lexical path as would be used by the runtime linker, ld.so.1, if it were supplying the system defaults. For example, the path /lib/sparcv9 is replaced with /lib/64.
Specify a new default search directory dir for ELF objects. Multiple occurrences of this option are permitted.
The default search paths for 32–bit ELF objects are /lib followed by /usr/lib. For 64–bit ELF objects, the default search paths are /lib/64 followed by /usr/lib/64.
Use of this option replaces the default search path. Therefore, a –l option is normally required to specify the original system default in relation to any new paths that are being applied. However, if the –u option is in effect, and a configuration file does not exist, the system defaults are added to the new configuration file. These defaults are added before the new paths specified with the –l option.
See the –F option for a description of the directory path sanitization that is applied to directories specified with –l.
When used with either the –a or –A options, specifies the directory dir in which any alternate objects exist. Multiple occurrences of this option are permitted, the directory dir being used to locate alternatives for any following command-line options.
Specify a new trusted directory dir for secure ELF objects. Multiple occurrences of this option are permitted.
See SECURITY in ld.so.1(1) for a definition of secure objects. See Runtime Security in Oracle Solaris 11.4 Linkers and Libraries Guide for a discussion of runtime restrictions imposed on secure applications.
The default trusted directories for secure 32–bit ELF objects are /lib/secure followed by /usr/lib/secure. For 64–bit secure ELF objects, the default trusted directories are /lib/secure/64 followed by /usr/lib/secure/64.
Use of this option replaces the default trusted directories. Therefore, a –s option is normally required to specify the original system default in relation to any new directories that are being applied. However, if the –u option is in effect, and a configuration file does not exist, the system defaults are added to the new configuration file. These defaults are added before the new directories specified with the –l option.
See the –F option for a description of the directory path sanitization that is applied to directories specified with –s.
Request that a configuration file be updated, possibly with the addition of new information. Additional arguments allow information to be appended to the existing contents. See NOTES.
If a configuration file does not exist, the configuration file is created as directed by the other arguments. In the case of the –l and –s options, any system defaults are first applied to the configuration file before the directories specified with these options.
The configuration file can be in an older format than that supported by the current system. In this case, crle writes the updated file using the current format. The resulting file cannot be read by older versions of Oracle Solaris that do not support that version.
See the –F option for a description of the directory path sanitization that is applied to paths read from an existing configuration file when –u is specified. Due to the importance of the checks disabled by the –F option, the –F option is not automatically enabled for subsequent update operations. If the –F option was specified when the configuration file to be updated was created, it may be necessary to specify –F with –u.
Specify verbose mode.
When printing the contents of a configuration file, more extensive directory and file information is provided.
When updating library paths, provides the details of path sanitization that transform the specified directories into the resulting path. See the –F option.
Print version information and immediately exit.
Print usage message and immediately exit.
By default, the runtime linker attempts to read the configuration file /var/ld/ld.config for each 32–bit application processed. /var/ld/64/ld.config is read for each 64–bit application. Applications can reference an alternative configuration file by setting the LD_CONFIG environment variable. An alternative configuration file can also be specified by recording the configuration file name in the application at the time the application is built. See the –c option of ld(1).
The following options were supported by previous versions of Oracle Solaris, and are now considered obsolete. Use of these options produces an error message to that effect.
Oracle Solaris 11.4 discontinued support for the configuration file directory cache, and for dumped objects created by the crle using the dldump(3C) function. Prior to this change, these options were used to manage the directory cache and object dumping functionality. These options are now obsolete. For the same reason, the use of crle to inspect old configuration files containing these features produces warning messages that the information is obsolete.
Oracle Solaris 11 discontinued support for SunOS 4.x AOUT executables on SPARC hardware. Prior to this change, the –t option provided a toggle for expressing the object type, ELF or AOUT, that affected any –l or –s options that followed. The –t option is now obsolete. For the same reason, the use of crle to inspect old configuration files containing AOUT information produces a warning message that the information is obsolete.
The following example creates a temporary configuration file with a new default search path for ELF objects. The environment variable LD_CONFIG_64 is used to instruct the runtime linker to use this configuration file for all 64–bit processes.
$ crle -64 -c /tmp/ld.config -u -l /local/lib/64
$ crle -c /tmp/ld.config
Configuration file [version 5]: /tmp/ld.config
Platform: 64-bit MSB SPARCV9
Default Library Path: /lib/64:/usr/lib/64:/local/lib/64
Trusted Directories: /lib/secure/64:/usr/lib/secure/64 \
(system default)
Command line:
crle -64 -c /tmp/ld.config -l /lib/64:/usr/lib/64:/local/lib/64
$ LD_CONFIG_64=/tmp/ld.config date
Wednesday, April 23, 2014 01:27:17 PM PDT
Example 2 Updating and Displaying a New Default Search Path for ELF Objects
The following example updates and displays a new default search path for ELF objects.
# crle -u -l /local/lib
# crle
Configuration file [version 5]: /var/ld/ld.config
Platform: 32-bit MSB SPARC
Default Library Path: /lib:/usr/lib:/local/lib
Trusted Directories: /lib/secure:/usr/lib/secure \
(system default)
Command line:
crle -c /var/ld/ld.config -l /lib:/usr/lib:/local/lib
# crle -u -l /ISV/lib
# crle
Configuration file [version 5]: /var/ld/ld.config
Platform: 32-bit MSB SPARC
Default Library Path: /lib:/usr/lib:/local/lib:/ISV/lib
Trusted Directories: /lib/secure:/usr/lib/secure \
(system default)
Command line:
crle -c /var/ld/ld.config -l /lib:/usr/lib:/local/lib:/ISV/lib
In this example, the default configuration file initially did not exist. Therefore, the new search path /local/lib is appended to the system default. The next update appends the search path /ISV/lib to those paths already established in the configuration file.
Example 3 Recovering From a Bad Configuration FileThe following example creates a bad configuration file in the default location. The file can be removed by instructing the runtime linker to ignore any configuration file with the LD_NOCONFIG environment variable. Note, it is recommended that temporary configuration files be created and the environment variable LD_CONFIG used to experiment with these files.
# crle -64 -F -l /local/lib # date ld.so.1: date: fatal: libc.so.1: open failed: \ No such file or directory Killed # LD_NOCONFIG=yes rm /var/ld/64/ld.config # date Friday, April 14, 2017 01:27:17 PM PDT
This configuration file does not include the system default search paths, and so the date utility is unable to locate the required system dependencies. This would not have been allowed if the –F option had not been specified. In this case, the –u option should have been used.
Example 4 Creating and Displaying a New Default Search Path and New Trusted Directory for ELF ObjectsThe following example creates and displays a new default search path and new trusted directory for ELF objects.
# crle -l /local/lib -l /lib -l /usr/lib \
-s /local/lib/secure -s /lib/secure -s /usr/lib/secure
# crle -v
Configuration file [version 5]: /var/ld/ld.config
Platform: 32-bit MSB SPARC
Default Library Path: /local/lib:/lib:/usr/lib
Trusted Directories: /local/lib/secure:/lib/secure:/usr/lib/secure
Command line:
crle -c /var/ld/ld.config \
-l /local/lib:/lib:/usr/lib \
-s /local/lib/secure:/lib/secure:/usr/lib/secure
With this configuration file, third party applications could be installed in /local/bin and their associated dependencies in /local/lib. The default search path allows the applications to locate their dependencies without the need to set LD_LIBRARY_PATH . The default trusted directories have also been augmented with this example.
Example 5 Creating an Alternative Path to Replace an ELF Shared ObjectThe following example defines an alternative object path to replace an ELF shared object. The example uses an application with a dependency on an object normally installed as /usr/local/lib/libapp.so.1.
$ ldd /usr/local/bin/app
libapp.so.1 => /usr/local/lib/libapp.so.1
....
# crle -c lib2.config -o /usr/local/lib2 -a /usr/local/lib/libapp.so.1
# crle -c lib2.config
Configuration file [version 5]: lib2.config
Platform: 32-bit MSB SPARC
Default Library Path: /lib:/usr/lib (system default)
Trusted Directories: /lib/secure:/usr/lib/secure \
(system default)
Alternative Objects:
Directory: /usr/local/lib
Alternative: /usr/local/lib2
libapp.so.1
Command line:
crle -c lib2.config -o /usr/local/lib2 -a /usr/local/lib/libapp.so.1
$ LD_CONFIG=lib2.config ldd /usr/local/bin/app
libapp.so.1 => /usr/local/lib2/libapp.so.1 (alternate)
....
With this configuration, any dependency that would normally resolve to /usr/local/lib/libapp.so.1 instead resolves to /usr/local/lib2/libapp.so.1.
Example 6 Setting Replaceable and Permanent Environment VariablesThe following example sets replaceable and permanent environment variables.
# crle -e LD_LIBRARY_PATH=/local/lib \
-E LD_PRELOAD=preload.so.1
# crle
.....
Environment Variables:
LD_LIBRARY_PATH=/local/lib (replaceable)
LD_PRELOAD=preload.so.1 (permanent)
.....
$ LD_DEBUG=files LD_PRELOAD=preload.so.2 ./main
.....
18764: file=preload.so.2; preloaded
18764: file=/local/lib/preload.so.2 [ ELF ]; \
generating link map
.....
18764: file=preload.so.1; preloaded
18764: file=/local/lib/preload.so.1 [ ELF ]; \
generating link map
.....
With this configuration file, a replaceable search path has been specified together with a permanent preload object which becomes appended to the process environment definition.
The creation or display of a configuration file results in a 0 being returned. Otherwise, any error condition is accompanied with a diagnostic message and a non-zero value being returned.
Care should be exercised when a configuration file is specified using the LD_CONFIG environment variable, as this environment variable is visible to any forked applications.
Configuration files contain platform specific binary data. A given configuration file can only be interpreted by software with the same machine class and byte ordering. Configuration files have system identification information at the beginning of the file. This information is used by crle and the runtime linker to check their compatibility with configuration files. This information also allows the file(1) command to properly identify configuration files.
Default configuration file for 32–bit applications.
Default configuration file for 64–bit applications.
There are no environment variables that are referenced by crle. However, several environment variables affect the runtime linkers behavior in regard to the processing of configuration files that are created by crle.
Provide an alternative configuration file.
Disable configuration file processing.
Disable environment variable processing from a configuration file.
Disable alternative object processing from a configuration file.
See attributes(7) for descriptions of the following attributes.
|
file(1), ld(1), ld.so.1(1), dldump(3C), tempnam(3C), attributes(7)