HP-UX 11i Technical Whitepaper Node and Host Name Sizes on HP-UX Using the Expanded Capabilities of HP-UX Revision 2.0 ABSTRACT HP-UX 11i v2 and v3, as well as later versions, provides expanded system node and host name interfaces. This capability allows longer node and host names than were previously supported. HP has provided this enhancement to support the system naming conventions used by some customers. This paper is intended for system administrators and program developers.
Table of Contents Introduction ................................................................................................................................... 3 Publication History ...................................................................................................................... 3 Activating and Setting Expanded Node and Host Names ...................................................................... 4 Activating Expanded Node and Host Names..........................................
Introduction System node and host names on HP-UX have default length limits of 8 and 64 bytes, respectively. The system administrator can configure the system to expand both these limits to 255 bytes. Some customers who have thousands of systems use a naming convention to clearly identify the physical location and purpose of each machine. For instance, the convention might encode: the geographical location, the computer room name, the purpose (such as application), and an index.
Activating and Setting Expanded Node and Host Names This section describes how to activate the capability to set longer node and host names, and how to actually set the longer names. Note the following important considerations: • • • • • • • • • • • You must verify that the versions of all applications that use node or host names are validated for expanded node and host name sizes before setting the names to longer values.
kctune expanded_node_host_names=1 To turn off this parameter, use the same command, but set the value to 0. For more information, see kctune(1m). Note that changing this parameter does not affect any current node and host name settings, regardless of their length. The node and host names should be changed to 8 or 64 bytes (or less) before turning off the parameter.
HP Product Limitations This section describes the limitations of HP software products in support of node names longer than 8 bytes or host names longer than 64 bytes. Some of these limitations might be removed in product or OS updates made available after the publication of this document. Providers of third-party and proprietary software can also have some limitations. Note that this list might not be complete. Any other important limitations encountered by customers should be reported to HP.
Expanding the window size in some applications (such as, dtfile – CDE file manager) shows the first component of the host name. The CDE login window cannot be resized. Core Files The application core file format on HP-UX 11i v3 has been updated so that it can accommodate the maximum node-name length. This updated format was introduced as an option with HP-UX 11i v2 (and likely used only on systems with the optional NodeHostNameXpnd product bundle installed).
names generally do not get sufficiently large to cause mail IDs to exceed the original 255byte limit. The sendmail utility can create files that include the host name (such as .forward.hostname+). With longer host names, it is somewhat more likely that the path to these files can exceed the PATH_MAX value, thus causing failures. Because the PATH_MAX value is 1023, this should be a problem only when the directory path itself already exceeds 756 bytes. For more information, see “File Names”.
Serviceguard The Serviceguard product supports host names up to 39-bytes (not including null terminator). Shared LVM In a Shared LVM SGeRAC environment the vgdisplay command displays the host names of activated/shared volumes. In this environment it supports up to 39 bytes (not including null terminator). UUCP UNIX-to-UNIX Copy Protocol (UUCP) on HP-UX supports node names only up to 8 bytes. The intersystem protocols cannot support longer node names.
Programmer Notes: Overview for Updating Programs Most application code is unaffected by the node and host name expansion. However, some applications need to be recompiled with options that select name expansion. In a subset of those cases, some code modification might be necessary. This section describes how software developers can determine whether a product might need modification and, if so, how to enhance the product to accommodate expanded node and host names.
Note that it does not have to be a system with the tunable expanded_node_host_names turned on in order to build with this option or to run the resulting binary. However, the resulting binary might be able to execute correctly only if HP-UX 11i v2 September 2004 Update or higher is installed, as that update contains the expanded programming interfaces.
All programmers are advised to read Appendix C, “Source Code Issues with Expanded Node and Host Names,” and inspect their programs for actual usage of the names, to ensure the program operates correctly when recompiled. Building for Execution on Multiple Releases This section describes how to build a program to handle expanded node or host names to be executed on systems regardless of release or update level.
However, since the expanded version of the uname(2) function and associated structure does not exist on versions prior to HP-UX 11i v2 September 2004 Update, it is not possible to build a binary that uses expanded uname(2) on those versions. The solution is to employ the approach described in the previous section, and to compile the program on the earliest HP-UX version on which it is to be run.
However, the rebuilt interfaces will not be binary compatible with existing client binary programs. Existing application binaries do not have a compatible layout for struct abdx. Calling muddle() could result in an application buffer overrun and undetermined behavior.
Summary HP has provided expanded node and host names in response to the needs expressed by customers. This feature increases the maximum node and host name lengths from 8 bytes and 64 bytes, respectively, to 255 (plus terminating null) for both. Because of the interface changes this involves, an interface version (or level) has been introduced that includes expansions for the node name and host name-related APIs.
APPENDIX A: Rules for Constructing Host and Node Names This appendix describes some rules, established by Internet standards bodies, for the formation of host names. The Domain Name Service (DNS), as documented in RFC 1034, limits a fully qualified host name to a total of 255 octets (bytes). A name is composed of labels separated by dots (.) where each label is limited to 63 octets. A label can be composed of letters, digits, and hyphens (-). Letters are treated in a case-insensitive manner.
APPENDIX B: HP-UX Node and Host Name Interfaces This appendix provides additional information about how the OS interfaces that directly manipulate the node and host name are affected by the support of expanded names. In some cases, the changes were effective in 11i v2 September 2004 Update. In all cases, the default configuration environment will be compatible with that of HP-UX releases and updates prior to the 11i v2 September 2004 Update (8-byte node names and 64-byte host names).
Programmatic Constant Interfaces SYS_NMLN, UTSLEN These are symbolic constants used to determine the size of fields in the utsname structure. Their values are 257 if the program is compiled with –D_HPUX_API_LEVEL=20040821. Otherwise, their values are 9. SNLEN This is a symbolic constant used to determine the size of the idnumber field in the utsname structure. Its value is 257 if the program is compiled with –D_HPUX_API_LEVEL=20040821. Otherwise, its value is 15.
Command Interfaces uname(1) The uname command displays up to 256 bytes of the node name, when invoked with the –n or the –a option (effective in HP-UX 11i v2 September 2004 Update). It allows setting of the node name with the –S option, up to 256 bytes (plus null) when the expanded_node_host_names tunable is 1 (on), or up to 8 bytes when the tunable is 0 (off).
APPENDIX C: Source Code Issues with Expanded Node and Host Names This appendix describes potential issues that might need to be addressed in existing programs. General Program Issues This section describes problems that application programs might exhibit that require attention from developers. In most cases the solution is to recompile to the API level that includes the expanded interfaces (that is, _HPUX_API_LEVEL=20040821).
Arrays Dimensioned by UTSLEN, SYS_NMLN, SNLEN, or MAXHOSTNAMELEN A program might use one of the symbolic constant interfaces (UTSLEN, SYS_NMLN, SNLEN, or MAXHOSTNAMELEN) to declare the size of array buffers to hold the node or host name. If not rebuilt with the compiler option –D_HPUX_API_LEVEL=20040821, the program’s buffer is not large enough to hold the entire node or host name. In most cases, when recompiling to use the expanded version, these symbol references adapt cleanly to the expanded values.
this, the program needs to recognize that it has encountered a nonexpanded format, and it must be able to use the nonexpanded structure layout to read it. Updating the the stored format to the expanded version is optional. Second, if other programs are expected to read the expanded stored format, they must be updated to use the expanded version. If the other programs are user programs, this can be compatibility issue if older user programs need to be supported.
• • • Rebuild all clients of the application library to use the expanded HP-UX node/host name interfaces. This satisfies the rule that all programs comprising an application be built in the same manner. The library and all clients are expanded node/host name clean. Do nothing. The library and clients support only the nonexpanded node and/or host name interfaces. This prevents the library and its client programs from fully supporting systems on which the administrator has set a long node and/or host name.
Scripts Scripts that use the uname(1) or hostname(1) command typically do not have problems with long node or host names. Yet, problems can occur. The script might parse the output of the uname(1) command to obtain a desired field. This is very unlikely because the uname(1) command provides options to obtain the individual argument, making parsing unnecessary. Furthermore, any parsing scheme must already deal with the variability of individual field widths.
Your network administrator should be able to provide a host/node name label of 63 bytes. The local network domain can be added (with dot delimiters) to form an FQDN. This results in an FQDN that is longer than 63 bytes and ensures that the host name string manipulated by the application exceeds the default limits. You might want to set up a separate domain hierarchy with 255-63-1 = 191 total bytes, including delimiters (you’ll need at least three levels).
APPENDIX D: FLV Concepts and Usage Function-Level Versioning (FLV) is a feature of the HP-UX compiler and linker that assists in the management of changes to interfaces. It provides the capability to define and export multiple versions of a function or data interface. To ensure correct operation, client references to the interfaces are bound to the desired version at link time.
The following subsections also refer to this example. Source and Binary Names and the Version Attribute Before proceeding with the description of FLV, note the following terms need. These are used when referring to interfaces exported from or imported into a compilation module. source name The name of an interface as written in the program’s source code file.
clientA.o - source file specifies no version_id attribute log.o (original version) - source file specifies no version_id attribute - object symbol table references “logevent()” - object symbol table exports “logevent()” clientB.o - source file specifies “rev2” version_id attribute log_rev2.
Note that only exported or referenced scalar and structure names appear in the object’s linker symbol table. By tagging the exported or referenced data with the version identifier, the linker ensures that objects bind to the desired data format. Type and structure definitions do not appear in the symbol table, but the ability to apply a version identifier is important, as described in the next section.
• • • • • • • For an array, pointer, or reference type, if the base type has an attached version identifier, the compiler associates the same version identifier with the derived type. For a C++ pointer-to-member type, if either the class or the base type has an attached version identifier, the compiler determines which of these version identifiers is lexically greater. It associates this highwater mark as the version identifier for the type.
Debuggers The debugger does not have access to source names. It has access only to the binary names. Thus, displays (such as stack traces) provide binary names. When looking up functions or data, the binary name must be supplied. Note also that a breakpoint set in one version of a function does not affect calls to another version. Assembly and Fortran: No Version The assembler and the Fortran language ignore the version attributes. The binary names are the same as the source names.
Fortunately, for node names, it is possible to switch to using the host name with a large buffer and avoid using the versioned utsname structure and uname() function, thereby avoiding use of the FLV mechanisms. For a description of this approach see “Building for Execution on Multiple Releases.” Providing Multiple Interface Versions in a Library FLV enables a library provider to export multiple versions of the same interface. This is done by including in the library two object files.
time_t hdr_lastmodifytime; #ifdef NEWVERS time_t hdr_lastaccesstime; #endif } This single source file can be compiled into two object files by using the following commands: cc –c fetch_hdr.c; mv fetch_hdr.o fetch_hdr_orig.o cc –DNEWVERS –c fetch_hdr.c; mv fetch_hdr.o fetch_hdr_new.o The result is that fetch_hdr_orig.o exports fetch_hdr(), and fetch_hdr_new.o exports fetch_hdr{rev2}().
Multiple Data Interfaces The preceding discussion concentrated on function interfaces. Another possibility is that a data structure exported by a library is accessed directly by client code that uses the library. For data that is read-only by clients, the general approach to be used by the provider is to update both the original and enhanced versions of the data structure at the same time (where the two have common fields).
# # } char idnumber[SNLEN]; if _INCLUDE_HPUX_API_LEVEL >= 20040821 char reserved1[SYS_NMLN]; char reserved2[SYS_NMLN]; endif extern int uname(struct utsname *) ATTR; If an application is built with no special options, it has the original layout for the utsname structure, and the binary name of the uname() function is uname(). Applications that are enhanced for the expanded node name are built with the compiler option –D_HPUX_API_LEVEL=20040821.
The approach taken is entirely dependent on the flexibility or demands of those who maintain the client programs. If the node name is not considered to be important to the interface (even though the whole utsname structure is included) it might be tempting to support only the nonexpanded version. One drawback to this is that client programs might want to use utsname structure and uname() function elsewhere in their program to support long node names.
In this case, the last two options will require explicit version attributes. Explicit Version Attributes Because interfaces that re-export constants do not inherit a version identifier, it is important to add one explicitly. The version attribute macro defined in sys/stdsyms.h can be used for this purpose. For example: #include
Glossary 11i v2 Update Bundled updates to HP-UX 11i v2. Included in 11i v2 September 2004 Update is preenablement for expanded node name and host name. This includes the compiler versions which support FLV, and the header, kernel, and libc support of expanded node name (using FLV) and host name. It also includes updates to many commands and utilities to accommodate the long names. The remaining enablement for 11i V2 is provided in the optional NodeHostNameXpnd product bundle.
fully qualified domain name (FQDN) Internet host names can be either a single system name label such as “myhost”, or include the hierarchical Internet domain labels, such as “myhost.corp.hp.com”. The latter is a fullyqualified domain name. The full name is limited to 64 octets (bytes) on HP-UX versions prior to 11i v2 (and any 11i v2 system with the tunable expanded_node_host_names==0 or not available). Name labels are limited to 63 octets by DNS.
node name can be accessed by the uname(1) command or by the uname(2) system function. nodename, utsname.nodename The nodename is the field within the utsname structure as returned by the uname(2) system function. For programs compiled with _HPUX_API_LEVEL=20040821, it can be up to 255 bytes (plus null terminator). re-export of interfaces The definition of an exported interface (A) can include part of some other interface definition (B). In this case A “re-exports” B.
uname_eoverflow The kernel tunable parameter that controls whether the EOVERFLOW error is reported by the uname(2) system function. The default value on HP-UX 11i v3 is 1 (on). UTSLEN See SYS_NMLN. utsname The program data structure that is returned by the uname() API. It contains the nodename field. See also SYS_NMLN, SNLEN, and UTSLEN. UUCP UNIX to UNIX file copy. UUCP is a pre-Internet protocol and set of commands to support transfer of files. It appears as part of some standards.
© 2005-2007 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
