te
CDDL HEADER START

The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.

You can obtain a copy of the license at CDDL.txt
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at CDDL.txt.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]

CDDL HEADER END
Copyright 2006 Sun Microsystems, Inc. All rights
reserved. Use is subject to license terms
libschost.so.1 - shared object to provide logical host name instead of a physical host name

libschost.so.1 

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 Sun 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.

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.

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

.na SC_LHOSTNAME=hostname .ad 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.

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() Sun Cluster function and includes references to the scds_handle_t and scds_net_resource_list_t Sun 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], \e
 ld_64[PATHLENGTH];

 scds_get_rs_hostnames(scds_handle, &snrlp);
 if (snrlp != NULL && snrlp->num_netresources != 0) {
 snprintf(lhostname, HOSTLENGTH, "SC_LHOSTNAME=%s", \e
 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", \e
 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 \e
 -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

.na /usr/cluster/lib/libschost.so.1 .ad Default location of the shared object for 32-bit applications

.na /usr/cluster/lib/64/libschost.so.1 .ad Default location of the shared object for 64-bit applications

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWscdev
Interface Stability	Evolving

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)

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.

Terms of Use | Privacy | Trademarks | Copyright Policy | Site Guidelines | Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.