All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_config.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2023 Aerospike, Inc.
3  *
4  * Portions may be licensed to Aerospike, Inc. under one or more contributor
5  * license agreements.
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
8  * use this file except in compliance with the License. You may obtain a copy of
9  * the License at http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14  * License for the specific language governing permissions and limitations under
15  * the License.
16  */
17 #pragma once
18 
19 #include <aerospike/as_error.h>
20 #include <aerospike/as_host.h>
21 #include <aerospike/as_policy.h>
22 #include <aerospike/as_password.h>
23 #include <aerospike/as_vector.h>
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /******************************************************************************
30  * MACROS
31  *****************************************************************************/
32 
33 #ifdef __linux__
34 /**
35  * Default path to the user UDF files.
36  */
37 #define AS_CONFIG_LUA_USER_PATH "/opt/aerospike/client/usr/udf/lua"
38 #endif
39 
40 #if defined(__APPLE__) || defined(__FreeBSD__)
41 #define AS_CONFIG_LUA_USER_PATH "/usr/local/aerospike/client/usr/udf/lua"
42 #endif
43 
44 #if defined(_MSC_VER)
45 #define AS_CONFIG_LUA_USER_PATH "C:/aerospike/client/usr/udf/lua"
46 #endif
47 
48 /**
49  * The size of path strings
50  */
51 #define AS_CONFIG_PATH_MAX_SIZE 256
52 
53 /**
54  * The maximum string length of path strings
55  */
56 #define AS_CONFIG_PATH_MAX_LEN (AS_CONFIG_PATH_MAX_SIZE - 1)
57 
58 /**
59  * Max clear text password size.
60  */
61 #define AS_PASSWORD_SIZE 64
62 
63 /******************************************************************************
64  * TYPES
65  *****************************************************************************/
66 
67 /**
68  * IP translation table.
69  *
70  * @ingroup as_config_object
71  */
72 typedef struct as_addr_map_s {
73 
74  /**
75  * Original hostname or IP address in string format.
76  */
77  char* orig;
78 
79  /**
80  * Use this IP address instead.
81  */
82  char* alt;
83 
84 } as_addr_map;
85 
86 /**
87  * Authentication mode.
88  *
89  * @ingroup as_config_object
90  */
91 typedef enum as_auth_mode_e {
92  /**
93  * Use internal authentication when user/password defined. Hashed password is stored
94  * on the server. Do not send clear password. This is the default.
95  */
97 
98  /**
99  * Use external authentication (like LDAP) when user/password defined. Specific external
100  * authentication is configured on server. If TLS defined, send clear password on node
101  * login via TLS. Return error if TLS is not defined.
102  */
104 
105  /**
106  * Use external authentication (like LDAP) when user/password defined. Specific external
107  * authentication is configured on server. Send clear password on node login whether or
108  * not TLS is defined. This mode should only be used for testing purposes because it is
109  * not secure authentication.
110  */
112 
113  /**
114  * Authentication and authorization based on a certificate. No user name or
115  * password needs to be configured. Requires TLS and a client certificate.
116  */
118 } as_auth_mode;
119 
120 /**
121  * Cluster event notification type.
122  *
123  * @ingroup as_config_object
124  */
125 typedef enum as_cluster_event_type_e {
126  /**
127  * Node was added to cluster.
128  */
130 
131  /**
132  * Node was removed fron cluster.
133  */
135 
136  /**
137  * There are no active nodes in the cluster.
138  */
141 
142 /**
143  * Cluster event notification data.
144  *
145  * @ingroup as_config_object
146  */
147 typedef struct as_cluster_event_s {
148  /**
149  * Node name.
150  */
151  const char* node_name;
152 
153  /**
154  * Node IP address in string format.
155  */
156  const char* node_address;
157 
158  /**
159  * User defined data.
160  */
161  void* udata;
162 
163  /**
164  * Cluster event notification type.
165  */
168 
169 /**
170  * Cluster event notification callback function.
171  * as_cluster_event is placed on the stack before calling.
172  * Do not free node_name or node_address.
173  *
174  * @ingroup as_config_object
175  */
177 
178 /**
179  * lua module config
180  *
181  * @ingroup as_config_object
182  */
183 typedef struct as_config_lua_s {
184 
185  /**
186  * Enable caching of UDF files in the client
187  * application.
188  */
190 
191  /**
192  * The path to user's UDF files.
193  * Default location defined in: AS_CONFIG_LUA_USER_PATH
194  */
195  char user_path[AS_CONFIG_PATH_MAX_SIZE];
196 
197 } as_config_lua;
198 
199 /**
200  * TLS module config
201  *
202  * @ingroup as_config_object
203  */
204 typedef struct as_config_tls_s {
205 
206  /**
207  * Enable TLS on connections.
208  * By default TLS is disabled.
209  */
210  bool enable;
211 
212  /**
213  * Path to a trusted CA certificate file.
214  * By default TLS will use system standard trusted CA certificates.
215  * Use as_config_tls_set_cafile() to set this field.
216  * If cafile is populated, castring is ignored.
217  */
218  char* cafile;
219 
220  /**
221  * String containing trusted CA certificate(s).
222  * Use as_config_tls_set_castring() to set this field.
223  * If cafile is populated, castring is ignored.
224  */
225  char* castring;
226 
227  /**
228  * Path to a directory of trusted certificates.
229  * See the OpenSSL SSL_CTX_load_verify_locations manual page for
230  * more information about the format of the directory.
231  * Use as_config_tls_set_capath() to set this field.
232  */
233  char* capath;
234 
235  /**
236  * Specifies enabled protocols.
237  *
238  * This format is the same as Apache's SSLProtocol documented
239  * at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol
240  *
241  * If not specified (NULL) the client will use "-all +TLSv1.2".
242  *
243  * If you are not sure what protocols to select this option is
244  * best left unspecified (NULL).
245  *
246  * Use as_config_tls_set_protocols() to set this field.
247  */
248  char* protocols;
249 
250  /**
251  * Specifies enabled cipher suites.
252  *
253  * The format is the same as OpenSSL's Cipher List Format documented
254  * at https://www.openssl.org/docs/manmaster/apps/ciphers.html
255  *
256  * If not specified the OpenSSL default cipher suite described in
257  * the ciphers documentation will be used.
258  *
259  * If you are not sure what cipher suite to select this option
260  * is best left unspecified (NULL).
261  *
262  * Use as_config_tls_set_cipher_suite() to set this field.
263  */
265 
266  /**
267  * Path to a certificate blacklist file.
268  * The file should contain one line for each blacklisted certificate.
269  * Each line starts with the certificate serial number expressed in hex.
270  * Each entry may optionally specify the issuer name of the
271  * certificate (serial numbers are only required to be unique per
272  * issuer). Example records:
273  * 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA
274  * E2D4B0E570F9EF8E885C065899886461
275  *
276  * Use as_config_tls_set_cert_blacklist() to set this field.
277  */
279 
280  /**
281  * Path to the client's key for mutual authentication.
282  * By default mutual authentication is disabled.
283  * Use as_config_tls_set_keyfile() to set this field.
284  * If keyfile is populated, keystring is ignored.
285  */
286  char* keyfile;
287 
288  /**
289  * Decryption password for the client's key for mutual authentication.
290  * By default the key is assumed not to be encrypted.
291  *
292  * Use as_config_tls_set_keyfile_pw() to set this field.
293  */
294  char* keyfile_pw;
295 
296  /**
297  * Client's key string for mutual authentication.
298  * By default mutual authentication is disabled.
299  * Use as_config_tls_set_keystring() to set this field.
300  * If keyfile is populated, keystring is ignored.
301  */
302  char* keystring;
303 
304  /**
305  * Path to the client's certificate chain file for mutual authentication.
306  * By default mutual authentication is disabled.
307  * Use as_config_tls_set_certfile() to set this field.
308  * If certfile is populated, certstring is ignored.
309  */
310  char* certfile;
311 
312  /**
313  * Client's certificate chain file string for mutual authentication.
314  * By default mutual authentication is disabled.
315  * Use as_config_tls_set_certstring() to set this field.
316  * If certfile is populated, certstring is ignored.
317  */
318  char* certstring;
319 
320  /**
321  * Enable CRL checking for the certificate chain leaf certificate.
322  * An error occurs if a suitable CRL cannot be found.
323  * By default CRL checking is disabled.
324  */
325  bool crl_check;
326 
327  /**
328  * Enable CRL checking for the entire certificate chain.
329  * An error occurs if a suitable CRL cannot be found.
330  * By default CRL checking is disabled.
331  */
333 
334  /**
335  * Log session information for each connection.
336  */
338 
339  /**
340  * Use TLS connections only for login authentication.
341  * All other communication with the server will be done with non-TLS connections.
342  * Default: false (Use TLS connections for all communication with server.)
343  */
345 
346 } as_config_tls;
347 
348 /**
349  * The `as_config` contains the settings for the `aerospike` client. Including
350  * default policies, seed hosts in the cluster and other settings.
351  *
352  * ## Initialization
353  *
354  * Before using as_config, you must first initialize it. This will setup the
355  * default values.
356  *
357  * ~~~~~~~~~~{.c}
358  * as_config config;
359  * as_config_init(&config);
360  * ~~~~~~~~~~
361  *
362  * Once initialized, you can populate the values.
363  *
364  * ## Seed Hosts
365  *
366  * The client will require at least one seed host defined in the
367  * configuration. The seed host is defined in `as_config.hosts`.
368  *
369  * ~~~~~~~~~~{.c}
370  * as_config_add_host(&config, "127.0.0.1", 3000);
371  * ~~~~~~~~~~
372  *
373  * The client will iterate over the list until it connects with one of the hosts.
374  *
375  * ## Policies
376  *
377  * The configuration also defines default policies for the application. The
378  * `as_config_init()` function already presets default values for the policies.
379  *
380  * Policies define the behavior of the client, which can be global across
381  * operations, global to a single operation, or local to a single use of an
382  * operation.
383  *
384  * Each database operation accepts a policy for that operation as an a argument.
385  * This is considered a local policy, and is a single use policy. This policy
386  * supersedes any global policy defined.
387  *
388  * If a value of the policy is not defined, then the rule is to fallback to the
389  * global policy for that operation. If the global policy for that operation is
390  * undefined, then the global default value will be used.
391  *
392  * If you find that you have behavior that you want every use of an operation
393  * to utilize, then you can specify the default policy in as_config.policies.
394  *
395  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
396  * policy. If you find yourself setting the `key` policy value for every call
397  * to `aerospike_key_put()`, then you may find it beneficial to set the global
398  * `as_policy_write` in `as_policies.write`, which all write operations will use.
399  *
400  * ~~~~~~~~~~{.c}
401  * config.policies.write.key = AS_POLICY_KEY_SEND;
402  * ~~~~~~~~~~
403  *
404  * Global operation policies:
405  * - as_policies.read
406  * - as_policies.write
407  * - as_policies.operate
408  * - as_policies.remove
409  * - as_policies.query
410  * - as_policies.scan
411  * - as_policies.info
412  *
413  * ## User-Defined Function Settings
414  *
415  * If you are using user-defined functions (UDF) for processing query
416  * results (i.e aggregations), then you will find it useful to set the
417  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
418  * which allows you to define a path to where the client library will look for
419  * Lua files for processing.
420  *
421  * ~~~~~~~~~~{.c}
422  * strcpy(config.mod_lua.user_path, "/home/me/lua");
423  * ~~~~~~~~~~
424  *
425  * Never call as_config_destroy() directly because ownership of config fields
426  * is transferred to aerospike in aerospike_init() or aerospike_new().
427  *
428  * @ingroup client_objects
429  */
430 typedef struct as_config_s {
431  /**
432  * Seed hosts. Populate with one or more hosts in the cluster that you intend to connect with.
433  * Do not set directly. Use as_config_add_hosts() or as_config_add_host() to add seed hosts.
434  */
436 
437  /**
438  * User authentication to cluster. Leave empty for clusters running without restricted access.
439  */
440  char user[AS_USER_SIZE];
441 
442  /**
443  * Password authentication to cluster. Leave empty for clusters running without restricted access.
444  */
445  char password[AS_PASSWORD_SIZE];
446 
447  /**
448  * Expected cluster name. If populated, the cluster_name must match the cluster-name field
449  * in the service section in each server configuration. This ensures that the specified
450  * seed nodes belong to the expected cluster on startup. If not, the client will refuse
451  * to add the node to the client's view of the cluster.
452  *
453  * Default: NULL
454  */
456 
457  /**
458  * Cluster event function that will be called when nodes are added/removed from the cluster.
459  *
460  * Default: NULL (no callback will be made)
461  */
463 
464  /**
465  * Cluster event user data that will be passed back to event_callback.
466  *
467  * Default: NULL
468  */
470 
471  /**
472  * A IP translation table is used in cases where different clients use different server
473  * IP addresses. This may be necessary when using clients from both inside and outside
474  * a local area network. Default is no translation.
475  *
476  * The key is the IP address returned from friend info requests to other servers. The
477  * value is the real IP address used to connect to the server.
478  *
479  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
480  * responsible for memory deallocation of the original data structure.
481  */
483 
484  /**
485  * Length of ip_map array.
486  * Default: 0
487  */
488  uint32_t ip_map_size;
489 
490  /**
491  * Minimum number of synchronous connections allowed per server node. Preallocate min
492  * connections on client node creation. The client will periodically allocate new connections
493  * if count falls below min connections.
494  *
495  * Server proto-fd-idle-ms and client max_socket_idle should be set to zero (no reap) if
496  * min_conns_per_node is greater than zero. Reaping connections can defeat the purpose
497  * of keeping connections in reserve for a future burst of activity.
498  *
499  * Default: 0
500  */
502 
503  /**
504  * Maximum number of synchronous connections allowed per server node. Synchronous transactions
505  * will go through retry logic and potentially fail with error code
506  * "AEROSPIKE_ERR_NO_MORE_CONNECTIONS" if the maximum number of connections would be exceeded.
507  *
508  * The number of connections used per node depends on how many concurrent threads issue
509  * database commands plus sub-threads used for parallel multi-node commands (batch, scan,
510  * and query). One connection will be used for each thread.
511  *
512  * Default: 100
513  */
515 
516  /**
517  * Minimum number of asynchronous connections allowed per server node. Preallocate min
518  * connections on client node creation. The client will periodically allocate new connections
519  * if count falls below min connections.
520  *
521  * Server proto-fd-idle-ms and client max_socket_idle should be set to zero (no reap) if
522  * async_min_conns_per_node is greater than zero. Reaping connections can defeat the purpose
523  * of keeping connections in reserve for a future burst of activity.
524  *
525  * Default: 0
526  */
528 
529  /**
530  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
531  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
532  * loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
533  * will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
534  * This variable is ignored if asynchronous event loops are not created.
535  *
536  * Default: 100
537  */
539 
540  /**
541  * Maximum number of pipeline connections allowed for each node.
542  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
543  * loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
544  * Async transactions will be rejected if the limit would be exceeded.
545  * This variable is ignored if asynchronous event loops are not created.
546  *
547  * Default: 64
548  */
550 
551  /**
552  * Number of synchronous connection pools used for each node. Machines with 8 cpu cores or
553  * less usually need just one connection pool per node. Machines with a large number of cpu
554  * cores may have their synchronous performance limited by contention for pooled connections.
555  * Contention for pooled connections can be reduced by creating multiple mini connection pools
556  * per node.
557  *
558  * Default: 1
559  */
561 
562  /**
563  * Initial host connection timeout in milliseconds. The timeout when opening a connection
564  * to the server host for the first time.
565  * Default: 1000
566  */
567  uint32_t conn_timeout_ms;
568 
569  /**
570  * Node login timeout in milliseconds.
571  * Default: 5000
572  */
574 
575  /**
576  * Maximum socket idle in seconds. Connection pools will discard sockets that have been
577  * idle longer than the maximum.
578  *
579  * Connection pools are now implemented by a LIFO stack. Connections at the tail of the
580  * stack will always be the least used. These connections are checked for max_socket_idle
581  * once every 30 tend iterations (usually 30 seconds).
582  *
583  * If server's proto-fd-idle-ms is greater than zero, then max_socket_idle should be
584  * at least a few seconds less than the server's proto-fd-idle-ms, so the client does not
585  * attempt to use a socket that has already been reaped by the server.
586  *
587  * If server's proto-fd-idle-ms is zero (no reap), then max_socket_idle should also be zero.
588  * Connections retrieved from a pool in transactions will not be checked for max_socket_idle
589  * when max_socket_idle is zero. Idle connections will still be trimmed down from peak
590  * connections to min connections (min_conns_per_node and async_min_conns_per_node) using a
591  * hard-coded 55 second limit in the cluster tend thread.
592  *
593  * Default: 0 seconds
594  */
595  uint32_t max_socket_idle;
596 
597  /**
598  * Maximum number of errors allowed per node per error_rate_window before backoff
599  * algorithm returns AEROSPIKE_MAX_ERROR_RATE for database commands to that node.
600  * If max_error_rate is zero, there is no error limit.
601  *
602  * The counted error types are any error that causes the connection to close (socket errors
603  * and client timeouts), server device overload and server timeouts.
604  *
605  * The application should backoff or reduce the transaction load until AEROSPIKE_MAX_ERROR_RATE
606  * stops being returned.
607  *
608  * Default: 100
609  */
610  uint32_t max_error_rate;
611 
612  /**
613  * The number of cluster tend iterations that defines the window for max_error_rate.
614  * One tend iteration is defined as tender_interval plus the time to tend all nodes.
615  * At the end of the window, the error count is reset to zero and backoff state is removed
616  * on all nodes.
617  *
618  * Default: 1
619  */
621 
622  /**
623  * Polling interval in milliseconds for cluster tender
624  * Default: 1000
625  */
626  uint32_t tender_interval;
627 
628  /**
629  * Number of threads stored in underlying thread pool used by synchronous batch/scan/query commands.
630  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
631  * improves performance because threads do not have to be created/destroyed for each command.
632  * Calculate your value using the following formula:
633  *
634  * thread_pool_size = (concurrent synchronous batch/scan/query commands) * (server nodes)
635  *
636  * If your application only uses async commands, this field can be set to zero.
637  * Default: 16
638  */
640 
641  /**
642  * Assign tend thread to this specific CPU ID.
643  * Default: -1 (Any CPU).
644  */
646 
647  /**
648  * Client policies
649  */
651 
652  /**
653  * lua config. This is a global config even though it's located here in cluster config.
654  * This config has been left here to avoid breaking the API.
655  *
656  * The global lua config will only be changed once on first cluster initialization.
657  * A better method for initializing lua configuration is to leave this field alone and
658  * instead call aerospike_init_lua():
659  *
660  * ~~~~~~~~~~{.c}
661  * // Get default global lua configuration.
662  * as_config_lua lua;
663  * as_config_lua_init(&lua);
664  *
665  * // Optionally modify lua defaults.
666  * lua.cache_enabled = <enable lua cache>;
667  * strcpy(lua.user_path, <lua user directory>);
668  *
669  * // Initialize global lua configuration.
670  * aerospike_init_lua(&lua);
671  * ~~~~~~~~~~
672  */
674 
675  /**
676  * TLS configuration parameters.
677  */
679 
680  /**
681  * Authentication mode.
682  * Default: AS_AUTH_INTERNAL
683  */
685 
686  /**
687  * Should cluster instantiation fail if the client fails to connect to a seed or
688  * all the seed's peers.
689  *
690  * If true, return an error if all seed connections fail or a seed is valid,
691  * but all peers from that seed are not reachable.
692  *
693  * If false, a partial cluster will be created and the client will automatically connect
694  * to the remaining nodes when they become available.
695  */
697 
698  /**
699  * Flag to signify if "services-alternate" should be used instead of "services"
700  * Default: false
701  */
703 
704  /**
705  * Track server rack data. This field is useful when directing read commands to
706  * the server node that contains the key and exists on the same rack as the client.
707  * This serves to lower cloud provider costs when nodes are distributed across different
708  * racks/data centers.
709  *
710  * rack_id or rack_ids, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must
711  * also be set to enable this functionality.
712  *
713  * Default: false
714  */
716 
717  /**
718  * Rack where this client instance resides. If rack_ids is set, rack_id is ignored.
719  *
720  * rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be
721  * set to enable this functionality.
722  *
723  * Default: 0
724  */
725  int rack_id;
726 
727  /**
728  * List of preferred racks in order of preference. If rack_ids is set, rack_id is ignored.
729  * Do not set directly. Use multiple as_config_add_rack_id() calls to add rack ids.
730  *
731  * rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be
732  * set to enable this functionality.
733  *
734  * Default: NULL
735  */
737 
738  /**
739  * Indicates if shared memory should be used for cluster tending. Shared memory
740  * is useful when operating in single threaded mode with multiple client processes.
741  * This model is used by wrapper languages such as PHP and Python. When enabled,
742  * the data partition maps are maintained by only one process and all other processes
743  * use these shared memory maps.
744  *
745  * Shared memory should not be enabled for multi-threaded programs.
746  * Default: false
747  */
748  bool use_shm;
749 
750  /**
751  * Identifier for the shared memory segment associated with the target Aerospike cluster.
752  * Each shared memory segment contains state for one Aerospike cluster. If there are
753  * multiple Aerospike clusters, a different shm_key must be defined for each cluster.
754  *
755  * Default: 0xA9000000
756  */
757  int shm_key;
758 
759  /**
760  * Shared memory maximum number of server nodes allowed. This value is used to size
761  * the fixed shared memory segment. Leave a cushion between actual server node
762  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
763  * Default: 16
764  */
765  uint32_t shm_max_nodes;
766 
767  /**
768  * Shared memory maximum number of namespaces allowed. This value is used to size
769  * the fixed shared memory segment. Leave a cushion between actual namespaces
770  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
771  * Default: 8
772  */
774 
775  /**
776  * Take over shared memory cluster tending if the cluster hasn't been tended by this
777  * threshold in seconds.
778  * Default: 30
779  */
781 } as_config;
782 
783 /******************************************************************************
784  * FUNCTIONS
785  *****************************************************************************/
786 
787 /**
788  * Initialize the configuration to default values.
789  *
790  * You should do this to ensure the configuration has valid values, before
791  * populating it with custom options.
792  *
793  * ~~~~~~~~~~{.c}
794  * as_config config;
795  * as_config_init(&config);
796  * as_config_add_host(&config, "127.0.0.1", 3000);
797  * ~~~~~~~~~~
798  *
799  * @relates as_config
800  */
802 as_config_init(as_config* config);
803 
804 /**
805  * Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],...
806  * Hostname may also be an IP address in the following formats.
807  *
808  * ~~~~~~~~~~{.c}
809  * IPv4: xxx.xxx.xxx.xxx
810  * IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
811  * IPv6: [xxxx::xxxx]
812  * ~~~~~~~~~~
813  *
814  * The host addresses will be copied.
815  * The caller is responsible for the original string.
816  *
817  * ~~~~~~~~~~{.c}
818  * as_config config;
819  * as_config_init(&config);
820  * as_config_add_hosts(&config, "host1,host2:3010,192.168.20.1:3020,[2001::1000]:3030", 3000);
821  * ~~~~~~~~~~
822  *
823  * @relates as_config
824  */
825 AS_EXTERN bool
826 as_config_add_hosts(as_config* config, const char* string, uint16_t default_port);
827 
828 /**
829  * Add host to seed the cluster.
830  * The host address will be copied.
831  * The caller is responsible for the original address string.
832  *
833  * ~~~~~~~~~~{.c}
834  * as_config config;
835  * as_config_init(&config);
836  * as_config_add_host(&config, "127.0.0.1", 3000);
837  * ~~~~~~~~~~
838  *
839  * @relates as_config
840  */
841 AS_EXTERN void
842 as_config_add_host(as_config* config, const char* address, uint16_t port);
843 
844 /**
845  * Remove all hosts.
846  *
847  * @relates as_config
848  */
849 AS_EXTERN void
851 
852 /**
853  * User authentication for servers with restricted access. The password will be stored by the
854  * client and sent to server in hashed format.
855  *
856  * ~~~~~~~~~~{.c}
857  * as_config config;
858  * as_config_init(&config);
859  * as_config_set_user(&config, "charlie", "mypassword");
860  * ~~~~~~~~~~
861  *
862  * @relates as_config
863  */
864 AS_EXTERN bool
865 as_config_set_user(as_config* config, const char* user, const char* password);
866 
867 /**
868  * Free existing string if not null and copy value to string.
869  */
870 AS_EXTERN void
871 as_config_set_string(char** str, const char* value);
872 
873 /**
874  * Set expected cluster name.
875  *
876  * @relates as_config
877  */
878 static inline void
879 as_config_set_cluster_name(as_config* config, const char* cluster_name)
880 {
881  as_config_set_string(&config->cluster_name, cluster_name);
882 }
883 
884 /**
885  * Set cluster event callback and user data.
886  *
887  * @relates as_config
888  */
889 static inline void
891 {
892  config->event_callback = callback;
893  config->event_callback_udata = udata;
894 }
895 
896 /**
897  * Initialize global lua configuration to defaults.
898  *
899  * @relates as_config
900  */
901 static inline void
903 {
904  lua->cache_enabled = false;
905  strcpy(lua->user_path, AS_CONFIG_LUA_USER_PATH);
906 }
907 
908 /**
909  * Set TLS path to a trusted CA certificate file.
910  *
911  * @relates as_config
912  */
913 static inline void
914 as_config_tls_set_cafile(as_config* config, const char* cafile)
915 {
916  as_config_set_string(&config->tls.cafile, cafile);
917 }
918 
919 /**
920  * Set string containing trusted CA certificate(s).
921  *
922  * @relates as_config
923  */
924 static inline void
925 as_config_tls_set_castring(as_config* config, const char* castring)
926 {
927  as_config_set_string(&config->tls.castring, castring);
928 }
929 
930 /**
931  * Set TLS path to a directory of trusted certificates.
932  *
933  * @relates as_config
934  */
935 static inline void
936 as_config_tls_set_capath(as_config* config, const char* capath)
937 {
938  as_config_set_string(&config->tls.capath, capath);
939 }
940 
941 /**
942  * Set TLS enabled protocols.
943  *
944  * @relates as_config
945  */
946 static inline void
947 as_config_tls_set_protocols(as_config* config, const char* protocols)
948 {
949  as_config_set_string(&config->tls.protocols, protocols);
950 }
951 
952 /**
953  * Set TLS enabled cipher suites.
954  *
955  * @relates as_config
956  */
957 static inline void
958 as_config_tls_set_cipher_suite(as_config* config, const char* cipher_suite)
959 {
960  as_config_set_string(&config->tls.cipher_suite, cipher_suite);
961 }
962 
963 /**
964  * Set TLS path to a certificate blacklist file.
965  *
966  * @relates as_config
967  */
968 static inline void
969 as_config_tls_set_cert_blacklist(as_config* config, const char* cert_blacklist)
970 {
971  as_config_set_string(&config->tls.cert_blacklist, cert_blacklist);
972 }
973 
974 /**
975  * Set TLS path to the client's key for mutual authentication.
976  *
977  * @relates as_config
978  */
979 static inline void
980 as_config_tls_set_keyfile(as_config* config, const char* keyfile)
981 {
982  as_config_set_string(&config->tls.keyfile, keyfile);
983 }
984 
985 /**
986  * Set decryption password for the client's key.
987  *
988  * @relates as_config
989  */
990 static inline void
991 as_config_tls_set_keyfile_pw(as_config* config, const char* pw)
992 {
993  as_config_set_string(&config->tls.keyfile_pw, pw);
994 }
995 
996 /**
997  * Set client's key string for mutual authentication.
998  *
999  * @relates as_config
1000  */
1001 static inline void
1002 as_config_tls_set_keystring(as_config* config, const char* keystring)
1003 {
1004  as_config_set_string(&config->tls.keystring, keystring);
1005 }
1006 
1007 /**
1008  * Set TLS path to the client's certificate chain file for mutual authentication.
1009  *
1010  * @relates as_config
1011  */
1012 static inline void
1013 as_config_tls_set_certfile(as_config* config, const char* certfile)
1014 {
1015  as_config_set_string(&config->tls.certfile, certfile);
1016 }
1017 
1018 /**
1019  * Set client's certificate chain file string for mutual authentication.
1020  *
1021  * @relates as_config
1022  */
1023 static inline void
1024 as_config_tls_set_certstring(as_config* config, const char* certstring)
1025 {
1026  as_config_set_string(&config->tls.certstring, certstring);
1027 }
1028 
1029 /**
1030  * Add TLS host to seed the cluster.
1031  * The host address and TLS name will be copied.
1032  * The caller is responsible for the original address string.
1033  *
1034  * ~~~~~~~~~~{.c}
1035  * as_config config;
1036  * as_config_init(&config);
1037  * as_config_tls_add_host(&config, "127.0.0.1", "node1.test.org", 3000);
1038  * ~~~~~~~~~~
1039  *
1040  * @relates as_config
1041  */
1042 AS_EXTERN void
1043 as_config_tls_add_host(as_config* config, const char* address, const char* tls_name, uint16_t port);
1044 
1045 /**
1046  * Add rack id to list of server racks in order of preference. Only add racks that
1047  * are close to the client rack. Do not add racks that are far away from the client.
1048  * The client will still direct commands to far away racks if nodes on closer racks are not
1049  * available.
1050  *
1051  * rack_aware, AS_POLICY_REPLICA_PREFER_RACK and server rack configuration must also be
1052  * set to enable this functionality.
1053  *
1054  * ~~~~~~~~~~{.c}
1055  * as_config config;
1056  * as_config_init(&config);
1057  * // Rack 4 is where the client machine is located.
1058  * as_config_add_rack_id(&config, 4);
1059  * // Rack 2 is located in same datacenter complex (maybe in a close by building).
1060  * as_config_add_rack_id(&config, 2);
1061  * // All other racks are far enough away that they are equally not preferred, so do not include
1062  * // them here.
1063  * ~~~~~~~~~~
1064  *
1065  * @relates as_config
1066  */
1067 AS_EXTERN void
1068 as_config_add_rack_id(as_config* config, int rack_id);
1069 
1070 /**
1071  * Convert string into as_auth_mode enum.
1072  */
1073 AS_EXTERN bool
1074 as_auth_mode_from_string(as_auth_mode* auth, const char* str);
1075 
1076 #ifdef __cplusplus
1077 } // end extern "C"
1078 #endif
uint32_t tender_interval
Definition: as_config.h:626
bool use_services_alternate
Definition: as_config.h:702
uint32_t conn_timeout_ms
Definition: as_config.h:567
uint32_t shm_takeover_threshold_sec
Definition: as_config.h:780
#define AS_USER_SIZE
Definition: as_password.h:29
static void as_config_set_cluster_name(as_config *config, const char *cluster_name)
Definition: as_config.h:879
char * keyfile
Definition: as_config.h:286
char * keyfile_pw
Definition: as_config.h:294
as_addr_map * ip_map
Definition: as_config.h:482
bool use_shm
Definition: as_config.h:748
void * event_callback_udata
Definition: as_config.h:469
bool fail_if_not_connected
Definition: as_config.h:696
char * cipher_suite
Definition: as_config.h:264
char * certstring
Definition: as_config.h:318
AS_EXTERN void as_config_tls_add_host(as_config *config, const char *address, const char *tls_name, uint16_t port)
uint32_t max_error_rate
Definition: as_config.h:610
int tend_thread_cpu
Definition: as_config.h:645
AS_EXTERN void as_config_add_host(as_config *config, const char *address, uint16_t port)
as_auth_mode auth_mode
Definition: as_config.h:684
static void as_config_tls_set_protocols(as_config *config, const char *protocols)
Definition: as_config.h:947
int shm_key
Definition: as_config.h:757
AS_EXTERN void as_config_clear_hosts(as_config *config)
as_config_lua lua
Definition: as_config.h:673
uint32_t shm_max_nodes
Definition: as_config.h:765
uint32_t thread_pool_size
Definition: as_config.h:639
uint32_t shm_max_namespaces
Definition: as_config.h:773
const char * node_address
Definition: as_config.h:156
uint32_t conn_pools_per_node
Definition: as_config.h:560
uint32_t login_timeout_ms
Definition: as_config.h:573
bool log_session_info
Definition: as_config.h:337
#define AS_EXTERN
Definition: as_std.h:25
bool rack_aware
Definition: as_config.h:715
as_cluster_event_callback event_callback
Definition: as_config.h:462
char * keystring
Definition: as_config.h:302
uint32_t ip_map_size
Definition: as_config.h:488
static void as_config_tls_set_certfile(as_config *config, const char *certfile)
Definition: as_config.h:1013
AS_EXTERN bool as_auth_mode_from_string(as_auth_mode *auth, const char *str)
AS_EXTERN bool as_config_set_user(as_config *config, const char *user, const char *password)
static void as_config_tls_set_cert_blacklist(as_config *config, const char *cert_blacklist)
Definition: as_config.h:969
const char * node_name
Definition: as_config.h:151
as_auth_mode
Definition: as_config.h:91
char * capath
Definition: as_config.h:233
AS_EXTERN bool as_config_add_hosts(as_config *config, const char *string, uint16_t default_port)
char * cafile
Definition: as_config.h:218
uint32_t max_socket_idle
Definition: as_config.h:595
char * protocols
Definition: as_config.h:248
char * cert_blacklist
Definition: as_config.h:278
as_cluster_event_type type
Definition: as_config.h:166
static void as_config_tls_set_certstring(as_config *config, const char *certstring)
Definition: as_config.h:1024
#define AS_PASSWORD_SIZE
Definition: as_config.h:61
uint32_t pipe_max_conns_per_node
Definition: as_config.h:549
as_vector * rack_ids
Definition: as_config.h:736
as_vector * hosts
Definition: as_config.h:435
as_policies policies
Definition: as_config.h:650
void(* as_cluster_event_callback)(as_cluster_event *event)
Definition: as_config.h:176
uint32_t max_conns_per_node
Definition: as_config.h:514
AS_EXTERN void as_config_add_rack_id(as_config *config, int rack_id)
#define AS_CONFIG_PATH_MAX_SIZE
Definition: as_config.h:51
static void as_config_tls_set_cafile(as_config *config, const char *cafile)
Definition: as_config.h:914
as_cluster_event_type
Definition: as_config.h:125
char * castring
Definition: as_config.h:225
as_config_tls tls
Definition: as_config.h:678
bool crl_check
Definition: as_config.h:325
bool for_login_only
Definition: as_config.h:344
static void as_config_tls_set_keystring(as_config *config, const char *keystring)
Definition: as_config.h:1002
uint32_t async_min_conns_per_node
Definition: as_config.h:527
static void as_config_tls_set_capath(as_config *config, const char *capath)
Definition: as_config.h:936
bool cache_enabled
Definition: as_config.h:189
AS_EXTERN void as_config_set_string(char **str, const char *value)
static void as_config_tls_set_castring(as_config *config, const char *castring)
Definition: as_config.h:925
AS_EXTERN as_config * as_config_init(as_config *config)
static void as_config_tls_set_cipher_suite(as_config *config, const char *cipher_suite)
Definition: as_config.h:958
static void as_config_set_cluster_event_callback(as_config *config, as_cluster_event_callback callback, void *udata)
Definition: as_config.h:890
static void as_config_tls_set_keyfile(as_config *config, const char *keyfile)
Definition: as_config.h:980
uint32_t async_max_conns_per_node
Definition: as_config.h:538
char * certfile
Definition: as_config.h:310
bool crl_check_all
Definition: as_config.h:332
uint32_t min_conns_per_node
Definition: as_config.h:501
uint32_t error_rate_window
Definition: as_config.h:620
static void as_config_lua_init(as_config_lua *lua)
Definition: as_config.h:902
static void as_config_tls_set_keyfile_pw(as_config *config, const char *pw)
Definition: as_config.h:991
char user_path[AS_CONFIG_PATH_MAX_SIZE]
Definition: as_config.h:195
int rack_id
Definition: as_config.h:725
char * cluster_name
Definition: as_config.h:455
char * alt
Definition: as_config.h:82
char * orig
Definition: as_config.h:77