Go to main content

Developer's Guide for Migrating to Oracle® Solaris 11.4

Exit Print View

Updated: November 2020
 
 

Preflight Applications Checker

The Oracle Solaris Preflight Applications Checker "Preflight Checker" enables you to identify potential issues when migrating Oracle Solaris 10 applications to Oracle Solaris 11. The tool runs a combination of source code, static binary, and runtime analysis modules on Oracle Solaris 10 to test existing applications and suggests the necessary code changes for the application to run successfully on Oracle Solaris 11.


Note -  The Oracle Solaris Preflight Applications Checker should be used only on development or test systems and should not be used on production systems.

About the Preflight Checker

The Oracle Solaris Preflight Applications Checker looks for potential issues and suggests better ways to implement application on an Oracle Solaris 11 system. The Preflight Applications Checker also includes the Oracle Solaris Preflight Kernel Checker, which helps you to find potential trouble spots in kernel modules. It includes the Source Code Analyzer and Binary Analyzer modules.

The primary purpose of these tools is to help developers test the readiness of an application before migration.

For more information, see the Oracle Solaris Guarantee Program.

Preflight Checker Modules

    The Preflight Applications Checker contains the following three main modules:

  • Binary Analyzer

  • Source Code Analyzer

  • Runtime Analyzer

The following figure shows a high-level view of the modules that are available to analyze binary compatibilities.

Figure 3  Modules for Analyzing Binary Compatibilities

image:This figure shows a graph of the modules that are available in the Application Analyzer and the Preflight Checker to analyze binary compatibilities.

Binary Analyzer Module

The Binary Analyzer module, also called the ELF analyzer, extracts all the bindings and associated symbol information from the application binaries. If running the application requires setting the LD_LIBRARY_PATH environment variable or if the system's default runtime linking environment is changed by using LD_CONFIG, you can provide a value for LD_LIBRARY_PATH.

The Preflight Checker uses the LD_LIBRARY_PATH value to determine the libraries being used by the application during runtime. This information helps to match the symbol bindings to the Oracle Developer Studio system shared libraries. While doing the binary analysis, if the application does not need the LD_LIBRARY_PATH variable to be set, the value must be blank. The lib path /usr/lib/64 (/usr/lib or /lib/64) is automatically used by the Binary Analyzer module.

The Preflight Checker has a built-in database populated with potential issues when migrating from Oracle Solaris 10 to Oracle Solaris 11. This database is accessed for every system symbol used in the application. Based on the output from the database lookup, the tool reports appropriate potential issues along with potential workarounds or suggestions to overcome the issues.

Source Code Analyzer Module

The Source Code Analyzer module checks for the use of removed, renamed, modified, or deprecated library functions in Oracle Solaris. This module also checks for issues in C and C++ source code, and detects potential issues in the shell scripts.


Note -  The default system shell /bin/sh and Korn shell /bin/ksh are replaced by the implementation of ksh93 in Oracle Solaris 11.

The shell scanner module helps to locate potential issues and report warning messages. In addition, this module also reports the use of files that are not available on Oracle Solaris 11.

The shell scanner module tries to resolve shell variables during scan time by looking into shell scripts available inside the target application directory. To get better results, you can set the environment variables outside the target scan directory and populate the init_script field with a comma-separated list of scripts through which the application environment is set. For example:

init_script = /export/home/user/.profile,/export/home/user/.bashrc,/export/home/user/setenv.sh

Note -  If the runtime environment information is not available during the static analysis of shell scripts, the shell scanner module might generate false positive results.

Runtime Analyzer Module

The Runtime Analyzer module can run on an existing Oracle Solaris 10 test environment and report the potential issues. This module of the Preflight Checker uses DTrace to look into process details. This module might also invoke other system tools available on Oracle Solaris 10.

    You can configure the Runtime Analyzer module to run with any of the following scopes:

  • System wide

  • All processes running inside a specific zone

  • All processes with a specific UID

  • All running processes for a given executable name

  • Specific PIDs

  • A user-specified custom command


Note -  The Runtime Analyzer module analyzes only user-initiated processes and ignores system processes.

The list of processes that are filtered out is maintained in the tool-base-dir/conf/SystemProcs.conf editable configuration file.

    The Runtime Analyzer module can report known issues in the following cases:

  • Invocation of removed, renamed, or relocated libraries, scripts, commands and devices, or other system-provided files.

  • Use or invocation of deprecated private or obsolete functions, APIs, and symbols.

  • dlopen() of removed, renamed, or moved libraries.

  • Use or invocation of private interfaces.

  • Use of outdated and removed versions of utilities or packages, for example, hard-coded paths to files that have been removed.

  • Use of files or libraries that are upgraded or replaced in a newer release of the Oracle Solaris OS.

Considerations When Using the Preflight Checker

If you use the dlopen() or mmap() functions, the Static Binary Analyzer and the Source Code Analyzer cannot access the shared object locations because the application is accessing a shared object that does not have its Oracle Solaris dependencies recorded. However, the Runtime Analyzer can access libraries loaded with dlopen() function and files loaded into memory by using mmap(). For more information, see the dlopen(3C) and mmap(9E) man pages.

    Other objects that Binary Analyzer and Source Code Analyzer cannot examine are as follows:

  • Executable files that do not have read/execute permission set

  • Non-ELF file executables

    Follow these guidelines when using the Preflight Checker:

  • You must provide correct environment details for the application while running the Preflight Checker. Differences in the environment could result in false positives for potential binary incompatibility or unresolved references to interfaces in the Oracle Solaris library. For example, if the LD_LIBRARY_PATH is not set correctly, the Preflight Checker reports additional unbound symbols.

  • To help ensure accurate Preflight Checker reporting, record dynamic library dependencies at compilation time by using the –z defs link option of Oracle Developer Studio. This option makes the object self-contained and better defined. It forces a fatal error if any undefined symbol remains at the end of the link. This option is the default when an executable is built.

  • The Runtime Analyzer module uses DTrace to look into process details, and might invoke other system tools available on Oracle Solaris 10. To limit the overhead of the Runtime Analyzer on overall system performance and responsiveness, restrict its scope to the minimum possible level. For example, avoid doing a system-wide runtime analysis if you already know specific PIDs of the targeted application.

Understanding Preflight Checker Reports

Oracle Solaris Preflight Applications Checker reports list the analyzed files (for binary and source code analysis) and processes (for runtime analysis) that are targeted during the corresponding phases of the scan.

A summary appears at the beginning of the report indicating the number of binaries examined and the number of potential binary stability problems that were found. The summary report can also be found under tool-install-dir/reports. By default, the report is created in HTML format.

    Reports also include suggestions for actions to be taken to resolve potential issues. Common issues reported by Preflight Checker after running a scan include the following:

  • Private symbol usage – If the symbol has not changed in the current release then the application can still run. However, future use of the symbol is not guaranteed and could cause problems. Eliminate the use of such private symbols.

  • Static linking – If an application is built by statically linking with libc.a, any kernel interface that it references is extracted from the libc.a archive and becomes a part of the application. This application runs only on a kernel that is in sync with the kernel interfaces used. Because you must link your application with shared versions of system-provided libraries, if the kernel interfaces change, the application might break.

  • Demoted or deprecated symbol – Eliminate the use of deprecated symbols.

  • No Bindings Found – Check environment variables such as LD_LIBRARY_PATH to ensure that they are correctly set so that the binary objects can find all of the libraries they depend on. For more information about how to cope with the possible problems resulting in unbound symbols, see the man pages of the corresponding APIs.

  • Obsolete library usage – Eliminate use of these symbols as soon as practical.

Defaults Used by the Preflight Checker

    If you do not provide custom information during the installation phase for the Preflight Checker or while starting the analysis, the tool uses the following default values:

  • LD_LIBRARY_PATH = ""

  • Report = tool-install-dir/reports

  • Report format = html

  • PATH

    • SPARC PATH = "/sbin:/bin:/usr/bin:/usr/bin/sparcv9:/bin/sparcv9"

    • x64 PATH = "/sbin:/bin:/usr/bin:/usr/bin/amd64:/bin/amd64"

  • Defined Macros = ""

  • System Include Directories = "/usr/include"

Installing the Preflight Checker

You can install and run the Preflight Checker on systems starting with Oracle Solaris 10.