Resolving LSC 8.2 librxtxSerial Undefined Symbol minor on Linux

1. Problem Overview

Siemens LOGO! Soft Comfort (LSC) V8.2 is the engineering tool for the LOGO! 8 logic module family. The Windows installer is straightforward, but the Linux archive (LOGOComfort_V8.2_Linux.zip) ships a bundled JRE and native helper libraries that must load against a compatible distribution. When the engineering tool is launched on a non-validated distribution (notably Gentoo and current openSUSE LEAP), the Dialog → Tools → Select Hardware step that enumerates Ethernet adapters fails before the LOGO! base unit can be selected.

Two distinct Java exceptions appear, depending on the network configuration in /etc/sysconfig:

1. java.lang.UnsupportedOperationException: adapter type is not supported — thrown by siemens.ad.logo.util.dipmgr.NetworkAdapterSuseUtil when the expected interface stub file is absent.
2. java.lang.UnsatisfiedLinkError: /usr/lib64/rxtx-2/librxtxSerial-2.2pre1.so: undefined symbol: minor — thrown by the JVM when the bundled RXTX JNI cannot resolve a glibc/kernel symbol it expects.

2. Environment Requirements and Compatibility Matrix

The following table consolidates the version matrix that LSC 8.2 is designed against versus the distros that are typically attempted by integrators.

3. Root Cause Analysis: Java RXTX Library Linkage

LSC 8.2 ships an RXTX 2.2pre1 Java Native Interface (JNI) shared object under install_dir/LOGOComfort_V8.2/rxtx-2.2pre1/. On 64-bit installations the LSC launcher will look in /usr/lib64/rxtx-2/ first. The library declares an external symbol that, in the bundled build, is provided by the kernel/glibc combination of SLED 11 SP3.

The exact JVM error observed on Gentoo is:

java.lang.UnsatisfiedLinkError: /usr/lib64/rxtx-2/librxtxSerial-2.2pre1.so:
   /usr/lib64/rxtx-2/librxtxSerial-2.2pre1.so: undefined symbol: minor

The minor symbol referenced is a legacy Linux kernel helper. The bundled librxtxSerial-2.2pre1.so was linked against an older kernel UAPI header set where minor() was an exported helper macro used in the termios path. Modern glibc (≥ 2.31) and modern kernel headers (≥ 5.x) have removed or no longer export this helper, so the dynamic loader resolves it as an undefined symbol at JNI load time and the Java side falls over before any network scan is attempted.

Why the symbol is missing

• Kernel ≥ 5.5 removed the legacy minor() inlines from the UAPI headers that the prebuilt rxtx 2.2pre1 consumed.
• glibc ≥ 2.31 no longer provides a compatibility shim for legacy minor macros used in some linux/fs.h paths.
• Gentoo, by design, tracks the latest stable kernel/glibc, so the bundled rxtx library cannot resolve the symbol at dlopen() time.

This is a link-time failure, not a permission problem and not a Java classpath problem. The library itself loads and ldd shows the dependencies are satisfied; the failure is in the symbol resolution against the process address space at first use.

4. Root Cause Analysis: NetworkAdapterSuseUtil Detection Path

Before RXTX is exercised, LSC enumerates the host's Ethernet adapters. On Linux, the Java class responsible is:

Decompilation of this class (using javap -c -p or a free decompiler) reveals a hard-coded path probe:

if (!new File("/etc/sysconfig/netsuse/ifcfg-eth0").exists()) {
    throw new UnsupportedOperationException("adapter type is not support");
}

The path /etc/sysconfig/netsuse/ is non-standard. SLED 11 SP3 ships interfaces configured under /etc/sysconfig/network/; netsuse is a vendor-specific legacy directory LSC 8.2 expects to find on the validated image. On a clean Gentoo or openSUSE LEAP install, neither /etc/sysconfig/netsuse/ nor /etc/sysconfig/network/ exists because those distributions use NetworkManager or wicked with a different state directory.

5. Diagnostic: Decompiling NetworkAdapterSuseUtil.class

To confirm the path and branch logic on a given install, run the bundled Java disassembler or a third-party decompiler against the class file. The procedure is non-invasive.

1. Locate the class: find $LSC_HOME -name NetworkAdapterSuseUtil.class
2. Use javap from the bundled JRE: $LSC_HOME/jre/bin/javap -c -p -classpath $LSC_HOME/lib/DE siemens.ad.logo.util.dipmgr.NetworkAdapterSuseUtil
3. Confirm the constant pool entry: /etc/sysconfig/netsuse/ifcfg-eth0 as a UTF-8 string.
4. Identify the call to java.io.File.exists() immediately before the UnsupportedOperationException construction.

Output should include a line similar to:

String str = "/etc/sysconfig/netsuse/ifcfg-eth0";
if (!new File(str).exists()) throw new UnsupportedOperationException(...);

Once confirmed, the engineer has two field-proven mitigations: a symlink for openSUSE (where the directory tree exists but the directory name differs) and a stub file for Gentoo (where the entire sysconfig tree is absent).

6. Step-by-Step Resolution: Create the ifcfg-eth0 Stub on Gentoo

For distributions that do not ship a /etc/sysconfig tree, the simplest verified workaround is to create the directory and an empty stub file matching the name LSC probes for.

Prerequisites

• Root access on the engineering workstation.
• LSC 8.2 extracted (e.g. /opt/LOGOComfort_V8.2).
• At least one physical or virtual Ethernet interface (e.g. eth0).

Procedure

1. Identify the active Ethernet interface: ip -o link show | awk -F': ' '$2 != "lo" {print $2}'
2. Create the SUSE-shaped sysconfig tree: sudo mkdir -p /etc/sysconfig/netsuse
3. Create the empty stub file for the active interface: sudo touch /etc/sysconfig/netsuse/ifcfg-eth0
4. For additional interfaces (e.g. wlo1, vmnet1) used in fallback detection, repeat: sudo touch /etc/sysconfig/netsuse/ifcfg-wlo1, sudo touch /etc/sysconfig/netsuse/ifcfg-vmnet1
5. Verify the file is readable by the user that will launch LSC: ls -l /etc/sysconfig/netsuse/
6. Launch LSC using the bundled launcher: cd /opt/LOGOComfort_V8.2 && ./LOGOComfort.sh
7. Open Tools → Select Hardware and confirm at least one adapter is enumerated.

7. Step-by-Step Resolution: openSUSE netsuse Symlink

On openSUSE the directory /etc/sysconfig/network/ exists and contains the standard interface configuration files. Creating a parallel /etc/sysconfig/netsuse/ tree is unnecessary — a symlink is enough.

1. Confirm the sysconfig network directory exists: ls -d /etc/sysconfig/network
2. Create the symlink: sudo ln -s /etc/sysconfig/network /etc/sysconfig/netsuse
3. Verify the symlink resolves: ls -l /etc/sysconfig/netsuse/ifcfg-eth0
4. Launch LSC 8.2 and open Tools → Select Hardware.

This approach is preferred over the stub file method on openSUSE because the existing ifcfg-eth0 file already carries valid SUSE-format key/value pairs (BOOTPROTO, IPADDR, etc.) and the symlink avoids the cosmetic duplication of state files.

8. Step-by-Step Resolution: rxtx Library Symbol Recovery

If the ifcfg stub is in place and LSC still reports undefined symbol: minor, the JNI side is failing. The recovery requires either pinning the kernel/glibc back to versions that export minor() (not recommended in production) or isolating the bundled rxtx library so that LSC's launcher uses the bundled JRE consistently.

1. Force the use of the bundled JRE: ensure JAVA_HOME is unset or points at $LSC_HOME/jre when invoking the launcher.
2. Confirm the rxtx library path the launcher is probing: strings $LSC_HOME/rxtx-2.2pre1/librxtxSerial-2.2pre1.so | grep -E "rxtx-2|/usr/lib"
3. Inspect the launcher script LOGOComfort.sh for any hard-coded LD_LIBRARY_PATH entries and ensure the bundled rxtx-2.2pre1 directory is listed first.
4. Pre-load a compatibility shim that re-exports minor() for older JNI consumers. Create /usr/local/lib/librxtxcompat.so with a single re-export function and add it to LD_PRELOAD for the LSC process only: LD_PRELOAD=/usr/local/lib/librxtxcompat.so ./LOGOComfort.sh
5. Re-test: Tools → Select Hardware should now enumerate the network adapter without throwing UnsatisfiedLinkError.

Shim source (rxtxcompat.c)

#include <sys/types.h>
/* Re-export minor() for legacy rxtx 2.2pre1 JNI consumers */
unsigned int minor(dev_t dev) { return (dev & 0xFFFFFUL) >> 20; }
int gnu_dev_minor(dev_t dev) { return (int)(dev & 0xFFFFFUL); }

Compile with gcc -shared -fPIC -o /usr/local/lib/librxtxcompat.so rxtxcompat.c. The shim is opt-in via LD_PRELOAD and does not affect the rest of the system.

9. Step-by-Step Resolution: Gentoo-Specific Configuration

Gentoo requires three coordinated changes to host LSC 8.2 reliably:

1. Pin the kernel to a compatible version. If the workstation must run LSC 8.2, hold the kernel at the latest 4.x release (e.g. sys-kernel/gentoo-sources-4.19.x) where minor() is still present in the UAPI. Set =sys-kernel/gentoo-sources-4.19.* in /etc/portage/package.mask.
2. Pin glibc to ≤ 2.30. Add <sys-libs/glibc-2.31 to /etc/portage/package.mask. glibc 2.30 still ships the minor() compatibility macro that rxtx 2.2pre1 expects.
3. Stub the sysconfig tree. Follow the procedure in Section 6 above.

After any of these changes, recompile glibc-aware binaries (emerge -1v libtool gcc glibc binutils) and reboot. Verify with:

uname -r      # should show 4.19.x
ldd --version  # should show 2.30 or older
ls /etc/sysconfig/netsuse/ifcfg-eth0   # should exist

10. Verification Procedure

After applying any of the resolutions above, run the following end-to-end check to confirm the engineering tool can see the LOGO! base unit.

1. Launch LSC: cd $LSC_HOME && ./LOGOComfort.sh
2. Open Tools → Select Hardware.
3. Confirm at least one Ethernet adapter (typically the one matching ifcfg-eth0) is listed.
4. Select the adapter and click Detect. The MAC address of the LOGO! base unit should appear within 3–5 seconds.
5. Click OK. The status bar should switch from Offline to Online with the LOGO! firmware version reported.
6. Open Tools → Transfer → To Device and perform a small test download of a single ladder network with one contact and one coil to confirm full PC↔LOGO! communication.

11. Troubleshooting Matrix

The following matrix maps the observed error to the verified resolution. Use it as a decision tree before resorting to kernel/glibc pinning.

12. Field-Proven Caveats

• Distribution rotation. Some openSUSE LEAP point releases have shipped a glibc bump that reintroduces the undefined symbol: minor error even after the netsuse symlink is in place. Always re-verify after a system update.
• Multiple interfaces. If the workstation has both eth0 and wlo1 active, LSC will sometimes latch onto the wireless interface and fail to reach the LOGO! on the wired segment. Create the stub only for the wired interface that shares the subnet with the LOGO! base unit.
• Virtual machines. VMware vmnet1 (host-only) and vmnet8 (NAT) are visible to LSC and may appear in the Select Hardware dialog. They will never reach a LOGO! and should be ignored. The stub file /etc/sysconfig/netsuse/ifcfg-vmnet1 does not hurt but can be omitted.
• File mode. The stub file must be readable by the launching user. If the workstation is hardened with restrictive umasks, an empty file created by root will not be readable; use sudo chmod 644 /etc/sysconfig/netsuse/ifcfg-eth0.
• Session 0 detection. On minimal Gentoo installs without elogind or systemd-logind, the bundled JRE may fail to enumerate any network adapter even with the stub in place. Install sys-auth/elogind and add the user to the plugdev group.
• OpenSUSE symlink hygiene. The /etc/sysconfig/netsuse → /etc/sysconfig/network symlink will be wiped by any openSUSE pattern that re-applies the sysconfig layout (e.g. wicked package reconfigure). Re-create the symlink after such operations.

13. FAQ