libschost.so.1

- shared object to provide logical host name instead of a physical host name

Synopsis

libschost.so.1 

Description

The libschost.so.1 shared object provides a mechanism by which the physical host name can be selectively configured for launched processes and their descendants.

In the Oracle Solaris Cluster environment, an application might attempt to access the same host name after a failover or switchover. As a result, the failover or switchover fails because the name of the physical host changes after a failover or switchover. In such a scenario, the application data service can use the libschost.so.1 shared object to provide a logical host name to the application rather than a physical host name.

To enable libschost.so.1, you need to set the SC_LHOSTNAME environment variable as well as the following two environment variables:

LD_PRELOAD_32=$LD_PRELOAD_32:/usr/cluster/lib/libschost.so.1
LD_PRELOAD_64=$LD_PRELOAD_64:/usr/cluster/lib/64/libschost.so.1

By setting both the LD_PRELOAD_32 and LD_PRELOAD_64 environment variables, you ensure that the libschost.so.1 shared object works with both 32-bit and 64-bit applications.

Security

The runtime linker accesses the default trusted directory /usr/lib/secure for 32-bit objects and /usr/lib/secure/64 for 64-bit objects. If your secure applications use the libschost.so.1 shared object, you need to ensure that the libschost.so.1 shared object is accessed from a trusted directory.

To do so, create a symbolic link from /usr/cluster/lib/libschost.so.1 to /usr/lib/secure/libschost.so.1 for 32-bit applications or from /usr/cluster/lib/64/libschost.so.1 to /usr/lib/secure/64/libschost.so.1 for 64-bit applications.

After you create these symbolic links, the LD_PRELOAD_32 and LD_PRELOAD_64 environment variables use the libschost.so.1 shared object from a trusted directory.

You can also use the crle command to specify additional trusted directories or to change the default trusted directory for secure applications. See the crle(1) man page.

Environment Variables

Once preloaded, the libschost.so.1 shared object reads the following environment variable and returns it as the host name.

SC_LHOSTNAME=hostname

SC_LHOSTNAME specifies the logical host name. The specified host name is available to all launched and descendant processes.

The hostname value can be a maximum of MAXHOSTNAMELEN characters long. The MAXHOSTNAMELEN constant is defined as 256 characters in the netdb.h header file.

Examples

Example 1 Configuring a Logical Host Name With a Logical Host Name at Runtime in C

The C code in the following example configures a host name with a logical host name. This example includes a call to the scds_get_rs_hostnames() Oracle Solaris Cluster function and includes references to the scds_handle_t and scds_net_resource_list_t Oracle Solaris Cluster data structures.

The scds_get_rs_hostnames() function provides a list of host names that are used by a resource. The code assigns the first host name value in this list to the SC_LHOSTNAME environment variable.

Any application that starts after you execute the following code gets a logical host name rather than a physical host name.

    /* 13 bytes to hold "SC_LHOSTNAME=" string */
    #define HOSTLENGTH (MAXHOSTNAMELEN + 13)

    /* 14 bytes to hold "LD_PRELOAD_XX=" string */
    #define PATHLENGTH (MAXPATHLEN + 14)

    char lhostname[HOSTLENGTH], ld_32[PATHLENGTH], \
         ld_64[PATHLENGTH];

    scds_get_rs_hostnames(scds_handle, &snrlp);
    if (snrlp != NULL && snrlp->num_netresources != 0) {
        snprintf(lhostname, HOSTLENGTH, "SC_LHOSTNAME=%s", \
            snrlp->netresources[0].hostnames[0]);
        putenv(lhostname);
    }

    /* Setting LD_PRELOAD_32 environment variable */
    if (getenv("LD_PRELOAD_32") == NULL)
        snprintf(ld_32, PATHLENGTH, "LD_PRELOAD_32="
            "/usr/cluster/lib/libschost.so.1");
    else
        snprintf(ld_32, PATHLENGTH, "LD_PRELOAD_32=%s:"
            "/usr/cluster/lib/libschost.so.1", \
             getenv("LD_PRELOAD_32"));

    putenv(ld_32);

    /* Setting LD_PRELOAD_64 environment variable */
    if (getenv("LD_PRELOAD_64") == NULL)
        snprintf(ld_64, PATHLENGTH, "LD_PRELOAD_64="
            "/usr/cluster/lib/64/libschost.so.1");
    else
        snprintf(ld_64, PATHLENGTH, 
            "LD_PRELOAD_64=%s:/usr/cluster/lib/"
            "64/libschost.so.1", getenv("LD_PRELOAD_64"));

    putenv(ld_64);

Example 2 Configuring a Logical Host Name With a Logical Host Name at Runtime With Shell Commands

The shell commands in the following example show how an application data service configures a host name with a logical host name by using the gethostnames command. The gethostnames command takes the following arguments:

• -R resource-name

• -G resourcegroup-name

• -T resourcetype-name

The gethostnames command returns all the logical host names that are associated with that resource, separated by a semicolon (;). The commands assign the first host name value in this list to the SC_LHOSTNAME environment variable.

phys-schost-1$ LD_PRELOAD_32=$LD_PRELOAD_32:/usr/cluster/lib/libschost.so.1
phys-schost-1$ LD_PRELOAD_64=$LD_PRELOAD_64:/usr/cluster/lib/64/libschost.so.1
phys-schost-1$ SC_LHOSTNAME=`/usr/cluster/lib/scdsbuilder/src/scripts/gethostnames \
               -R nfs-r -G nfs-rg -T SUNW.nfs:3.1 |cut -f1 -d","`
phys-schost-1$ export LD_PRELOAD_32 LD_PRELOAD_64 SC_LHOSTNAME

Example 3 Configuring a Logical Host Name for Secure Applications With Shell Commands

The shell commands in the following example configure the logical host name. Any secure application that starts after you execute the following shell commands gets the value of the SC_LHOSTNAME environment variable (that is, a logical host name) rather than a physical host name.

phys-schost-1$ cd /usr/lib/secure
phys-schost-1$ ln -s /usr/cluster/lib/libschost.so.1 .
phys-schost-1$ cd /usr/lib/secure/64
phys-schost-1$ ln -s /usr/cluster/lib/64/libschost.so.1 .
phys-schost-1$ LD_PRELOAD_32=$LD_PRELOAD_32:/usr/lib/secure/libschost.so.1
phys-schost-1$ LD_PRELOAD_64=$LD_PRELOAD_64:/usr/lib/secure/64/libschost.so.1
phys-schost-1$ SC_LHOSTNAME=test
phys-schost-1$ export LD_PRELOAD_32 LD_PRELOAD_64 SC_LHOSTNAME

Files

/usr/cluster/lib/libschost.so.1

Default location of the shared object for 32-bit applications

/usr/cluster/lib/64/libschost.so.1

Default location of the shared object for 64-bit applications

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

crle(1), cut(1), hostname(1), ld(1), ld.so.1(1), proc(1), uname(1), exec(2), sysinfo(2), uname(2), gethostname(3C), putenv(3C), snprintf(3C), system(3C), proc(4)

Notes

The logical host name is inherited.

User programs that fetch a host name by calling the following commands or functions can obtain a logical host name rather than a physical host name:

• hostname command

• uname command

• uname() function

• sysinfo() function

• gethostname() function

User programs that fetch a host name by other commands or functions cannot obtain a logical host name.