 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
clua_registerservice(3)
NAME
clua_registerservice, clua_unregisterservice - Register or release a
dynamic port as eligible for incoming cluster alias connections
LIBRARY
Cluster Alias Library (libclua.a and libclua.so)
SYNOPSIS
#include <clua/clua.h>
clua_status_t clua_registerservice (
u_short portno ,
int type ,
int options );
clua_status_t clua_unregisterservice (
u_short portno ,
int type );
PARAMETERS
portno The number of the port to register or release. The port number
must be specified in host order, not network order. Therefore, if
you get a port number using a function such as getsockname(), use
ntohs() to convert it from network to host order.
type The type of socket to use (SOCK_STREAM or SOCK_DGRAM).
options Options as defined in the clua.h file (the following list also
contains the equivalent strings from /etc/clua_services):
CLUASRV_MULTI
(in_multi) Port can be used by a multi-instance
service.
For TCP, the cluster alias software distributes
connection requests from clients using a round-robin
algorithm. Each connection is bound to a single alias
member, but different connections to the service from
the same client might be established on different alias
members.
For UDP, the cluster alias software distributes
messages using a round-robin algorithm. Each packet
might go to a different alias member.
See cluamgr(8) for information on parameters that
affect the round-robin algorithm.
CLUASRV_SINGLE
(in_single) Port must be used as a single-instance
service with failover. Multiple listen()s are
permitted, but only one at a time will be given cluster
alias packets. As each service binds to the single-
instance port, the first is flagged as active for the
alias, and the others flagged as inactive. If the
active service fails, one of the inactive daemons is
marked as active.
CLUASRV_SINGLE is the default alias attribute for TCP
ports.
CLUASRV_IN_NOALIAS
(in_noalias) Port cannot receive inbound alias
messages.
CLUASRV_OUT
(out_alias) The default cluster alias will be used as
the source address whenever this port is used as a
destination. Normally, outbound connections (or UDP
messages) use the local IP address of the cluster
member on which the client is running. (Note that
cluster-aware applications can bind explicitly to any
cluster alias address.)
It is important to remember that CLUASRV_OUT applies
only when a TCP connection or an outbound UDP send
originates from the cluster; that is, the cluster is
the client. If a process running on a cluster member
initiates an outbound connection, and the destination
port (the port representing that half of the connection
that is not in the cluster) is flagged by a call to
clua_registerservice(,,CLUASRV_OUT), the connection
will use the default alias as its source address. (Note
that the CLUASRV_OUT flag forces the default cluster
alias as the source address only if the destination
port for the service has the out_alias attribute set in
the clua_services file.)
The same logic holds true when the outbound traffic is
a UDP send, because each send can be viewed as a
micro-connection.
See the clua_services(4) description of out_alias for
examples that use the default cluster alias as the
source address.
CLUASRV_IN_NOLOCAL
(in_nolocal) Port will not honor connection requests to
nonalias addresses. For TCP, will not accept
connections; for UDP, will drop messages.
CLUASRV_STATIC
(static) Port cannot be assigned as a dynamic port. The
port cannot be globally locked (dedicated to a single
node) by the cluster alias subsystem.
Dynamic (ephemeral) ports are automatically handed out
by the system in response to wildcard bind requests.
Extending the range of ephemeral ports beyond port 5000
to accommodate more concurrent outbound connections
results in overlaying the port address space that was
previously reserved for user well-known ports. (The
upper limit of the user range is determined by the
value of the sysconfigtab attribute
ipport_userreserved.)
An application using a well-known port in this extended
range runs the risk of having that port assigned as an
ephemeral port before the application has a chance to
bind to it (especially if the service does not start
when the system boots). Marking a port as
CLUASRV_STATIC means that the port will not be assigned
in response to a wildcard bind request. For example,
an application that has been using port 6000 as a
well-known port can mark it CLUASRV_STATIC and be
assured that if the application starts up late or is on
a cluster node that joins late, another process will
not be given port 6000 to use as an ephemeral port.
The same principle holds for the well-known privileged
ports between 512-1024. An application is using a
well-know privileged port marked static should start at
boot time, for example through a mechanism like
inetd.conf. Otherwise, an application trawling for a
reserved port might get the port even though it is
marked static. (There is no way to differentiate
between an application that is searching for a
privileged port and one that knows which well-known
port it wants.)
Specifying a port as CLUASRV_STATIC also prevents a
port from being globally locked by the cluster alias
subsystem. This lets unmodified applications binding
to a well-known port run on several nodes in the
cluster. Note that unless CLUASRV_MULTI is also set,
the first application run will always be selected by
the round-robin algorithm.
DESCRIPTION
The clua_registerservice() function defines the cluster alias attribute for
port portno on the calling node. In effect, the clua_registerservice()
function creates a dynamic entry for an ephemeral or privileged port that
would be defined in the /etc/clua_services file if it were a well-known
port. Typically this happens when a port-mapper service binds to a dynamic
port and registers it with the port mapper.
The CLUASRV_MULTI, CLUASRV_SINGLE, and CLUASRV_IN_NOALIAS options are
mutually exclusive. If you attempt to set more than one of these options,
clua_registerservice() returns CLUA_EBADOPTION.
The CLUASRV_IN_NOLOCAL and CLUASRV_IN_NOALIAS options are mutually
exclusive. If you attempt to set more than one of these options,
clua_registerservice() returns CLUA_EBADOPTION.
The strings used in the /etc/clua_services file have a 1:1 mapping to the
CLUASRV_* flags used by clua_registerservice(). Some of these strings/flags
also have a relationship with the cluster alias setsockopt() options. The
following table shows these relationships.
______________________________________________________________
clua_services clua_registerservice() setsockopt()
______________________________________________________________
in_multi CLUASRV_MULTI
in_single CLUASRV_SINGLE
in_noalias CLUASRV_IN_NOALIAS SO_CLUA_IN_NOALIAS
out_alias CLUASRV_OUT* SO_CLUA_DEFAULT_SRC**
in_nolocal CLUASRV_IN_NOLOCAL SO_CLUA_IN_NOLOCAL
static CLUASRV_STATIC
SO_REUSEALIASPORT
______________________________________________________________
* The CLUASRV_OUT flag forces the default cluster alias as the source
address only if the destination port for the service has the out_alias
attribute set in the clua_services file.
** The SO_CLUA_DEFAULT_SRC option does not check the attributes associated
with the destination port. (Note that neither CLUASRV_OUT nor
SO_CLUA_DEFAULT_SRC will override the manual setting of an address. These
two options set the source address to the default cluster alias only if the
address is not yet set.)
The clua_unregisterservice() function releases a port registration created
using the clua_registerservice() function. It is provided in the event that
a dynamic port reservation must be released (making the port available only
for nonalias use until it is released by closing the socket(s) using it).
Programs that use cluster alias functions include the cluster alias header
file, <clua/clua.h>, and are compiled with the cluster alias library,
libclua. Programs that use the clua_getaliasaddress(), clua_getaliasinfo(),
clua_getdefaultalias(), clua_isalias(), clua_registerservice(), or
clua_unregisterservice() functions are also compiled with the configuration
management library, libcfg.
EXAMPLES
The following short program shows portions of a typical calling sequence:
#include <sys/socket.h>
#include <sys/types.h>
#include <netinet/in.h>
#include <clua/clua.h>
int main()
{
int sockfd, len;
struct sockaddr_in sin;
u_short portno;
clua_status_t result;
len = sizeof(sin);
if ((sockfd = socket(AF_INET, SOCK_STREAM, 0)) < 0) {
perror("socket create failed");
exit(1);
}
sin.sin_family = AF_INET;
sin.sin_addr.s_addr = htonl(INADDR_ANY);
if ( bind(sockfd,
(struct sockaddr *)&sin,
len) < 0) {
perror("bind failed");
exit(1);
}
if (getsockname(sockfd, (struct sockaddr *)&sin, &len) != 0) {
perror("getsockname failed");
exit(1);
}
portno = ntohs(sin.sin_port);
if (result = clua_registerservice(portno,
SOCK_STREAM,
CLUASRV_MULTI) != CLUA_SUCCESS) {
perror("clua_registerservice failed");
exit(1);
}
/* service connection requests */
if (result = clua_unregisterservice(portno,
SOCK_STREAM) != CLUA_SUCCESS) {
perror("clua_unregisterservice failed");
exit(1);
}
/* clean up and prepare to exit */
}
RETURN VALUES
The clua_registerservice() and clua_unregisterservice() functions return
one of the following values:
CLUA_SUCCESS
Successful completion.
CLUA_EBADOPTION
Illegal value in options parameter.
CLUA_EBADTYPE
Illegal value in type parameter.
CLUA_ENOCLUSTER
Caller is not in a cluster.
CLUA_ENOCONFIG
Cluster alias subsystem is not configured.
FILES
/etc/clua_services
Static configuration file where services using well-known ports
are registered for cluster alias connections.
SEE ALSO
Commands: cluamgr(8), clua_active(8)
Functions: clua_error(3), clua_getaliasaddress(3), clua_getaliasinfo(3),
clua_getdefaultalias(3), clua_isalias(3), clusvc_getcommport(3) ntohs(3)
Files: clua_services(4), clu_alias.config(4), exports.aliases(4)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|