usr/src/lib/libsldap/common/ns_connmgmt.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2008 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26
  27 #ifndef _NS_CONNMGMT_H
  28 #define _NS_CONNMGMT_H
  29
  30 #pragma ident   "%Z%%M% %I%     %E% SMI"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #include <thread.h>
  37 #include "ns_sldap.h"
  38 #include "ns_internal.h"
  39 #include "ns_cache_door.h"
  40
  41 struct ns_conn_user; /* connection user, forward definition */
  42 struct ns_conn_mt;   /* multi-threaded (MT) connection, forward definition */
  43 struct ns_conn_mgmt; /* connection management, forward definition */
  44
  45 #define NS_CONN_MT_USER_NO_MAX  -1
  46 #define NS_CONN_MT_USER_MAX     NS_CONN_MT_USER_NO_MAX
  47 #define NS_LIST_TRY_MAX         3
  48
  49 /*
  50  * Structure for handling the waiter of a pending multi-threaded (MT) connection
  51  */
  52 typedef struct ns_conn_waiter {
  53         cond_t                  waitcv;
  54         uint8_t                 signaled;
  55         struct ns_conn_user     *key;
  56         struct ns_conn_waiter   *next, *prev;
  57 } ns_conn_waiter_t;
  58
  59 /*
  60  * type of a connection user
  61  */
  62 typedef enum {
  63         NS_CONN_USER_SEARCH     = 1,
  64         NS_CONN_USER_WRITE      = 2,
  65         NS_CONN_USER_AUTH       = 3,
  66         NS_CONN_USER_GETENT     = 4
  67 } ns_conn_user_type_t;
  68
  69 /*
  70  * state of a connection user
  71  */
  72 typedef enum {
  73         NS_CONN_USER_UNINITED           = 0,
  74         NS_CONN_USER_ALLOCATED          = 1,
  75         NS_CONN_USER_FINDING            = 2, /* looking for an MT connection */
  76         NS_CONN_USER_WAITING            = 3, /* waiting for an MT connection */
  77         NS_CONN_USER_WOKEUP             = 4,
  78         NS_CONN_USER_CONNECT_ERROR      = 5,
  79         NS_CONN_USER_CONNECTED          = 6,
  80         NS_CONN_USER_DISCONNECTED       = 7,
  81         NS_CONN_USER_FREED              = 8
  82 } ns_conn_user_state_t;
  83
  84 /*
  85  * A connection user represents a request processed by libsldap. It
  86  * usually is a thread using the same connection from start to end.
  87  * Different connection users of the same type can share the same
  88  * connection opened for that type. But search and getent users can
  89  * share the same connection opened for either search or getent. AUTH
  90  * connection are not shareable.
  91  *
  92  * A getent user may have a longer lifespan and live outside of libsldap.
  93  * This is because the associated search cookie is passed back to the caller
  94  * via the firstEntry call and used in the subsequent nextEntry or endEntry
  95  * calls. Even though the firstEntry and the nextEntry/endEntry calls may
  96  * be running in a different thread, the connection being used will be the
  97  * same. It is the one assigend during the firstEntry call.
  98  */
  99 struct ns_conn_user {
 100         ns_conn_user_type_t     type; /* search, write, auth, getent, ... */
 101         ns_conn_user_state_t    state;
 102         thread_t                tid;   /* id of the thread starts the request */
 103         struct ns_conn_user     *next; /* next conn_user in the linked list */
 104         struct ns_conn_mt       *conn_mt; /* the MT connection being used */
 105         struct ns_conn_mgmt     *conn_mgmt; /* ref counted conn management */
 106         void                    *userinfo; /* private data of the request */
 107         ns_ldap_return_code     ns_rc; /* error return code */
 108         ns_ldap_error_t         *ns_error; /* error info */
 109         boolean_t               referral; /* using a referred server ? */
 110         boolean_t               retry; /* retry the request on certain error? */
 111         boolean_t               keep_conn; /* keep the conn for reuse ? */
 112         boolean_t               use_mt_conn; /* using/used an MT connection ? */
 113         boolean_t               bad_mt_conn; /* MT connection is not usable ? */
 114 };
 115
 116 /*
 117  * state of an MT connection
 118  */
 119 typedef enum {
 120         NS_CONN_MT_UNINITED             = 0,
 121         NS_CONN_MT_CONNECTING           = 1,
 122         NS_CONN_MT_CONNECT_ERROR        = 2,
 123         NS_CONN_MT_CONNECTED            = 3,
 124         NS_CONN_MT_CLOSING              = 4
 125 } ns_conn_mt_state_t;
 126
 127 /*
 128  * An ns_conn_mt (or MT connection) represents an ldap connection
 129  * that can be shared among multiple threads. It also represents
 130  * the set of connection users using the ldap connection. It contains
 131  * a pointer to the Connection structure that has the physical info
 132  * of the connection (server name, address, ldap handle, etc). It
 133  * also contains a linked list of all the conn_user using the ldap
 134  * connection. The connection users can wait on an MT connection
 135  * to become available or be told to abort and clean up when one of
 136  * the connection user detects an error and knows that the connection
 137  * is no longer usable. The error info is then saved in the structure
 138  * for other users to consume.
 139  *
 140  * An MT connection is meant to be shared concurrently and persistent.
 141  * Even when there's no current user, it will be kept by the connection
 142  * management, waiting for the next user. It will be closed when
 143  * a connection error is detected, when a better server should be
 144  * used, when the Native LDAP configuration change, or when the libsldap
 145  * is being unloaded.
 146  */
 147 typedef struct ns_conn_mt {
 148         mutex_t                 lock;
 149         ns_conn_mt_state_t      state;
 150         pid_t                   pid; /* process creates the connection */
 151         thread_t                tid; /* thread creates the connection */
 152         struct ns_conn_mt       *next; /* next conn_mt in the linked list */
 153         ns_conn_user_t          *cu_head; /* head of conn_user linked list */
 154         ns_conn_user_t          *cu_tail; /* tail of conn_user linked list */
 155         struct ns_conn_mgmt     *conn_mgmt; /* ref counted conn management */
 156         ns_conn_waiter_t        waiter; /* first of the connection waiters */
 157         uint_t                  cu_cnt; /* number of the using conn_user */
 158         int32_t                 cu_max; /* max. allowed number of conn_user */
 159         uint_t                  waiter_cnt; /* number of waiters */
 160         ns_conn_user_type_t     opened_for; /* type of conn_user opened for */
 161         Connection              *conn; /* name, IP address, ldap handle, etc */
 162         time_t                  create_time; /* time when connection created */
 163         time_t                  access_time; /* time when last used */
 164         ns_ldap_return_code     ns_rc; /* saved error code */
 165         ns_ldap_error_t         *ns_error; /* saved error info */
 166         boolean_t               close_when_nouser;  /* close connection when */
 167                                                     /* last user is done ? */
 168         boolean_t               detached; /* no longer in connection pool? */
 169         boolean_t               referral; /* using a referred server ? */
 170 } ns_conn_mt_t;
 171
 172 /*
 173  * state of a connection management
 174  * (a connection pool sharing the same native LDAP configuration)
 175  */
 176 typedef enum {
 177         NS_CONN_MGMT_UNINITED   = 0,
 178         NS_CONN_MGMT_INACTIVE   = 1, /* conn sharing not yet requested */
 179         NS_CONN_MGMT_ACTIVE     = 2, /* connection sharing required/requested */
 180         NS_CONN_MGMT_DETACHED   = 3  /* on the way down, no new user allowed */
 181 } ns_conn_mgmt_state_t;
 182
 183 /*
 184  * An ns_conn_mgmt (or connection management) represents the set of MT
 185  * connections using the same native LDAP configuration. It is a connection
 186  * pool that can adjust the MT connection status and usage based on the
 187  * change notifications it receives from the ldap_cachemgr daemon, OR When
 188  * the change is detected at config refresh time. When a server status
 189  * change (up or down) notification is received or detected, it will
 190  * close the MT connections using the server. Or mark them as to-be-closed
 191  * and close them when all users are done using them. When a config change
 192  * notice is received, it will detach itself and allow a new ns_conn_mgmt be
 193  * created for the new configuration. The old config would still be used
 194  * by the detached ns_conn_mgmt. Both will be destroyed when all existing
 195  * conn_user are done. Any conn_user and MT connection created after the
 196  * configuration switch will use the new configuration.
 197  *
 198  * Note that there's always just one current ns_conn_mgmt. Its usage is
 199  * reference counted. Any new conn_user or MT connection referencing
 200  * the ns_conn_mgmt adds 1 to the count, any release of the ns_conn_mgmt
 201  * decrement the count by 1. The ns_conn_mgmt can not be freed until
 202  * the reference count becomes zero.
 203  *
 204  * Each ns_conn_mgmt references a native LDAP configuration. The config
 205  * component of this library always maintains a global configuration. It is
 206  * referred to as the current global config. The current ns_conn_mgmt
 207  * uses that global config. When an ns_conn_mgmt is detached, or not
 208  * longer active/current, the config it uses is no longer the current global
 209  * one, which is referred as the per connection management config. When
 210  * the ns_conn_mgmt is freed, the config will also be destroyed.
 211  */
 212
 213 typedef struct ns_conn_mgmt {
 214         mutex_t         lock;
 215         ns_conn_mgmt_state_t state;
 216         pid_t           pid; /* process creates the conn_mgmt */
 217         thread_t        procchg_tid; /* id of the change monitor thread */
 218         ns_conn_mt_t    *cm_head; /* head of the conn_mt linked list */
 219         ns_conn_mt_t    *cm_tail; /* tail of the conn_mt linked list */
 220         mutex_t         cfg_lock; /* lock serializes access to config */
 221         ldap_get_chg_cookie_t cfg_cookie; /* used to detect if config changes */
 222         ns_config_t     *config; /* the native LDAP config being used */
 223         char            **pservers; /* preferred servers defined in config */
 224         uint_t          cm_cnt;  /* number of MT connection in the pool */
 225         uint_t          ref_cnt; /* number of reference by conn_MT/conn_user */
 226         boolean_t       is_nscd; /* running in a nscd ? */
 227         boolean_t       is_peruser_nscd; /* running in a per-user nscd ? */
 228         boolean_t       ldap_mt; /* libldap supports multi-threaded client ? */
 229         boolean_t       do_mt_conn;     /* need and able to do MT conn ? */
 230         boolean_t       shutting_down;  /* on the way down ? */
 231         boolean_t       cfg_reloaded;   /* config is not current ? */
 232         boolean_t       procchg_started; /* change monitor thread started ? */
 233         boolean_t       procchg_door_call; /* in door call and waiting ? */
 234         boolean_t       pservers_loaded; /* pservers array is set ? */
 235 } ns_conn_mgmt_t;
 236
 237 /*
 238  * For a connection management and the conn_mt connections it manages, it is
 239  * very helpful to know exactly when the Native LDAP configuration changes
 240  * and when the status of the configured servers change. If the config
 241  * changes, new connection management will be created. If servers go up
 242  * or down, conn_mt connections being used need to be dropped or switched.
 243  * For processes other than the main nscd, the changes has to be detected
 244  * in a less efficient way by libsldap. For the main nscd (not including
 245  * peruser nscd), the connection management which has active conn_mt
 246  * connections can rely on the ldap_cachemgr daemon to report if there's any
 247  * change in servers' status or if the native LDAP configuration has changed.
 248  *
 249  * The mechanism for reporting of the changes is a door call sent from
 250  * libsldap to ldap_cachemgr. The call will not be returned until changes
 251  * detected by ldap_cachemgr. When the change info is passed back to
 252  * libsldap, the change monitor thread will wake up from the door call
 253  * and process the notification. For servers went from up to down, the
 254  * associated MT connections will be closed, and then all conn_users'
 255  * state will be marked as closing. When a conn_user notices it, the
 256  * operations represented by that conn_user will be ended with error
 257  * info. When a more preferred server is up, MT connections using
 258  * less preferred servers will be marked as closed-when-all-user-done,
 259  * so that new connection will be opened and using the preferred server.
 260  * A configuration change causes the current connection management and
 261  * the configuration it uses to become detached but continually being
 262  * used by the old MT connections. Any new MT connection opened will
 263  * be put in a new connection management and uses the new configuration
 264  * immediately.
 265  */
 266 typedef enum {
 267         NS_SERVER_UP    = 1,
 268         NS_SERVER_DOWN  = 2
 269 } ns_server_status_t;
 270
 271 typedef struct ns_server_status_change {
 272         int                     num_server;
 273         boolean_t               config_changed;
 274         ns_server_status_t      *changes;       /* array of status change */
 275         char                    **servers;      /* array of server */
 276 } ns_server_status_change_t;
 277
 278 /*
 279  * connection management functions
 280  */
 281 ns_conn_mgmt_t *__s_api_conn_mgmt_init();
 282 int __s_api_setup_mt_ld(LDAP *ld);
 283 int __s_api_check_mtckey();
 284 void __s_api_use_prev_conn_mgmt(int, ns_config_t *);
 285 ns_conn_user_t *__s_api_conn_user_init(int, void *, boolean_t);
 286 void __s_api_conn_mt_return(ns_conn_user_t *);
 287 void __s_api_conn_user_free(ns_conn_user_t *);
 288 int __s_api_conn_mt_add(Connection *con, ns_conn_user_t *, ns_ldap_error_t **);
 289 int __s_api_conn_mt_get(const char *, const int, const ns_cred_t *,
 290         Connection **, ns_ldap_error_t **, ns_conn_user_t *);
 291 void __s_api_conn_mt_remove(ns_conn_user_t *, int, ns_ldap_error_t **);
 292 int __s_api_check_libldap_MT_conn_support(ns_conn_user_t *, LDAP *ld,
 293         ns_ldap_error_t **);
 294 void __s_api_conn_mt_close(ns_conn_user_t *, int, ns_ldap_error_t **);
 295 void __s_api_reinit_conn_mgmt_new_config(ns_config_t *);
 296 int __s_api_setup_retry_search(ns_conn_user_t **, ns_conn_user_type_t, int *,
 297         int *, ns_ldap_error_t **);
 298 int __s_api_setup_getnext(ns_conn_user_t *, int *, ns_ldap_error_t **);
 299 void __s_api_shutdown_conn_mgmt();
 300
 301 #ifdef __cplusplus
 302 }
 303 #endif
 304
 305 #endif /* _NS_CONNMGMT_H */