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-2016 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 system UDF files.
36  */
37 #define AS_CONFIG_LUA_SYSTEM_PATH "/opt/aerospike/client/sys/udf/lua"
38 
39 /**
40  * Default path to the user UDF files.
41  */
42 #define AS_CONFIG_LUA_USER_PATH "/opt/aerospike/client/usr/udf/lua"
43 #endif
44 
45 #ifdef __APPLE__
46 /**
47  * Default path to the system UDF files.
48  */
49 #define AS_CONFIG_LUA_SYSTEM_PATH "/usr/local/aerospike/client/sys/udf/lua"
50 
51 /**
52  * Default path to the user UDF files.
53  */
54 #define AS_CONFIG_LUA_USER_PATH "/usr/local/aerospike/client/usr/udf/lua"
55 #endif
56 
57 /**
58  * The size of path strings
59  */
60 #define AS_CONFIG_PATH_MAX_SIZE 256
61 
62 /**
63  * The maximum string length of path strings
64  */
65 #define AS_CONFIG_PATH_MAX_LEN (AS_CONFIG_PATH_MAX_SIZE - 1)
66 
67 /******************************************************************************
68  * TYPES
69  *****************************************************************************/
70 
71 /**
72  * IP translation table.
73  *
74  * @ingroup as_config_object
75  */
76 typedef struct as_addr_map_s {
77 
78  /**
79  * Original hostname or IP address in string format.
80  */
81  char* orig;
82 
83  /**
84  * Use this IP address instead.
85  */
86  char* alt;
87 
88 } as_addr_map;
89 
90 /**
91  * lua module config
92  *
93  * @ingroup as_config_object
94  */
95 typedef struct as_config_lua_s {
96 
97  /**
98  * Enable caching of UDF files in the client
99  * application.
100  */
102 
103  /**
104  * The path to the system UDF files. These UDF files
105  * are installed with the aerospike client library.
106  * Default location defined in: AS_CONFIG_LUA_SYSTEM_PATH
107  */
108  char system_path[AS_CONFIG_PATH_MAX_SIZE];
109 
110  /**
111  * The path to user's UDF files.
112  * Default location defined in: AS_CONFIG_LUA_USER_PATH
113  */
114  char user_path[AS_CONFIG_PATH_MAX_SIZE];
115 
116 } as_config_lua;
117 
118 /**
119  * TLS module config
120  *
121  * @ingroup as_config_object
122  */
123 typedef struct as_config_tls_s {
124 
125  /**
126  * Enable TLS on connections.
127  * By default TLS is disabled.
128  */
129  bool enable;
130 
131  /**
132  * Only encrypt connections; do not verify certificates.
133  * By default TLS will verify certificates.
134  */
136 
137  /**
138  * Path to a trusted CA certificate file.
139  * By default TLS will use system standard trusted CA certificates.
140  * Use as_config_tls_set_cafile() to set this field.
141  */
142  char* cafile;
143 
144  /**
145  * Path to a directory of trusted certificates.
146  * See the OpenSSL SSL_CTX_load_verify_locations manual page for
147  * more information about the format of the directory.
148  * Use as_config_tls_set_capath() to set this field.
149  */
150  char* capath;
151 
152  /**
153  * Specifies enabled protocols.
154  *
155  * This format is the same as Apache's SSLProtocol documented
156  * at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol
157  *
158  * If not specified (NULL) the client will use "-all +TLSv1.2".
159  *
160  * If you are not sure what protocols to select this option is
161  * best left unspecified (NULL).
162  *
163  * Use as_config_tls_set_protocol() to set this field.
164  */
165  char* protocol;
166 
167  /**
168  * Specifies enabled cipher suites.
169  *
170  * The format is the same as OpenSSL's Cipher List Format documented
171  * at https://www.openssl.org/docs/manmaster/apps/ciphers.html
172  *
173  * If not specified the OpenSSL default cipher suite described in
174  * the ciphers documentation will be used.
175  *
176  * If you are not sure what cipher suite to select this option
177  * is best left unspecified (NULL).
178  *
179  * Use as_config_tls_set_cipher_suite() to set this field.
180  */
182 
183  /**
184  * Enable CRL checking for the certificate chain leaf certificate.
185  * An error occurs if a suitable CRL cannot be found.
186  * By default CRL checking is disabled.
187  */
188  bool crl_check;
189 
190  /**
191  * Enable CRL checking for the entire certificate chain.
192  * An error occurs if a suitable CRL cannot be found.
193  * By default CRL checking is disabled.
194  */
196 
197  /**
198  * Path to a certificate blacklist file.
199  * The file should contain one line for each blacklisted certificate.
200  * Each line starts with the certificate serial number expressed in hex.
201  * Each entry may optionally specify the issuer name of the
202  * certificate (serial numbers are only required to be unique per
203  * issuer). Example records:
204  * 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA
205  * E2D4B0E570F9EF8E885C065899886461
206  *
207  * Use as_config_tls_set_cert_blacklist() to set this field.
208  */
210 
211  /**
212  * Log session information for each connection.
213  */
215 
216 } as_config_tls;
217 
218 /**
219  * The `as_config` contains the settings for the `aerospike` client. Including
220  * default policies, seed hosts in the cluster and other settings.
221  *
222  * ## Initialization
223  *
224  * Before using as_config, you must first initialize it. This will setup the
225  * default values.
226  *
227  * ~~~~~~~~~~{.c}
228  * as_config config;
229  * as_config_init(&config);
230  * ~~~~~~~~~~
231  *
232  * Once initialized, you can populate the values.
233  *
234  * ## Seed Hosts
235  *
236  * The client will require at least one seed host defined in the
237  * configuration. The seed host is defined in `as_config.hosts`.
238  *
239  * ~~~~~~~~~~{.c}
240  * as_config_add_host(&config, "127.0.0.1", 3000);
241  * ~~~~~~~~~~
242  *
243  * The client will iterate over the list until it connects with one of the hosts.
244  *
245  * ## Policies
246  *
247  * The configuration also defines default policies for the application. The
248  * `as_config_init()` function already presets default values for the policies.
249  *
250  * Policies define the behavior of the client, which can be global across
251  * operations, global to a single operation, or local to a single use of an
252  * operation.
253  *
254  * Each database operation accepts a policy for that operation as an a argument.
255  * This is considered a local policy, and is a single use policy. This policy
256  * supersedes any global policy defined.
257  *
258  * If a value of the policy is not defined, then the rule is to fallback to the
259  * global policy for that operation. If the global policy for that operation is
260  * undefined, then the global default value will be used.
261  *
262  * If you find that you have behavior that you want every use of an operation
263  * to utilize, then you can specify the default policy in as_config.policies.
264  *
265  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
266  * policy. If you find yourself setting the `key` policy value for every call
267  * to `aerospike_key_put()`, then you may find it beneficial to set the global
268  * `as_policy_write` in `as_policies.write`, which all write operations will use.
269  *
270  * ~~~~~~~~~~{.c}
271  * config.policies.write.key = AS_POLICY_KEY_SEND;
272  * ~~~~~~~~~~
273  *
274  * If you find that you want to use a policy value across all operations, then
275  * you may find it beneficial to set the default policy value for that policy
276  * value.
277  *
278  * For example, if you keep setting the key policy value to
279  * `AS_POLICY_KEY_SEND`, then you may want to just set `as_policies.key`. This
280  * will set the global default value for the policy value. So, if an global
281  * operation policy or a local operation policy does not define a value, then
282  * this value will be used.
283  *
284  * ~~~~~~~~~~{.c}
285  * config.policies.key = AS_POLICY_KEY_SEND;
286  * ~~~~~~~~~~
287  *
288  * Global default policy values:
289  * - as_policies.timeout
290  * - as_policies.retry
291  * - as_policies.key
292  * - as_policies.gen
293  * - as_policies.exists
294  *
295  * Global operation policies:
296  * - as_policies.read
297  * - as_policies.write
298  * - as_policies.operate
299  * - as_policies.remove
300  * - as_policies.query
301  * - as_policies.scan
302  * - as_policies.info
303  *
304  *
305  * ## User-Defined Function Settings
306  *
307  * If you are using using user-defined functions (UDF) for processing query
308  * results (i.e aggregations), then you will find it useful to set the
309  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
310  * which allows you to define a path to where the client library will look for
311  * Lua files for processing.
312  *
313  * ~~~~~~~~~~{.c}
314  * strcpy(config.mod_lua.user_path, "/home/me/lua");
315  * ~~~~~~~~~~
316  *
317  * Never call as_config_destroy() directly because ownership of config fields
318  * is transferred to aerospike in aerospike_init() or aerospike_new().
319  *
320  * @ingroup client_objects
321  */
322 typedef struct as_config_s {
323  /**
324  * Seed hosts. Populate with one or more hosts in the cluster that you intend to connect with.
325  * Do not set directly. Use as_config_add_hosts() or as_config_add_host() to add seed hosts.
326  */
328 
329  /**
330  * User authentication to cluster. Leave empty for clusters running without restricted access.
331  */
332  char user[AS_USER_SIZE];
333 
334  /**
335  * Password authentication to cluster. The hashed value of password will be stored by the client
336  * and sent to server in same format. Leave empty for clusters running without restricted access.
337  */
338  char password[AS_PASSWORD_HASH_SIZE];
339 
340  /**
341  * Expected cluster name. If not null, server nodes must return this cluster name in order to
342  * join the client's view of the cluster. Should only be set when connecting to servers that
343  * support the "cluster-name" info command. Use as_config_set_cluster_name() to set this field.
344  * Default: NULL
345  */
347 
348  /**
349  * A IP translation table is used in cases where different clients use different server
350  * IP addresses. This may be necessary when using clients from both inside and outside
351  * a local area network. Default is no translation.
352  *
353  * The key is the IP address returned from friend info requests to other servers. The
354  * value is the real IP address used to connect to the server.
355  *
356  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
357  * responsible for memory deallocation of the original data structure.
358  */
360 
361  /**
362  * Length of ip_map array.
363  * Default: 0
364  */
365  uint32_t ip_map_size;
366 
367  /**
368  * Maximum number of synchronous connections allowed per server node. Synchronous transactions
369  * will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS"
370  * if the maximum number of connections would be exceeded.
371  *
372  * The number of connections used per node depends on how many concurrent threads issue
373  * database commands plus sub-threads used for parallel multi-node commands (batch, scan,
374  * and query). One connection will be used for each thread.
375  *
376  * Default: 300
377  */
379 
380  /**
381  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
382  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
383  * loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
384  * will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
385  * This variable is ignored if asynchronous event loops are not created.
386  * Default: 300
387  */
389 
390  /**
391  * Maximum number of pipeline connections allowed for each node.
392  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
393  * loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
394  * Async transactions will be rejected if the limit would be exceeded.
395  * This variable is ignored if asynchronous event loops are not created.
396  * Default: 64
397  */
399 
400  /**
401  * Initial host connection timeout in milliseconds. The timeout when opening a connection
402  * to the server host for the first time.
403  * Default: 1000
404  */
405  uint32_t conn_timeout_ms;
406 
407  /**
408  * Polling interval in milliseconds for cluster tender
409  * Default: 1000
410  */
411  uint32_t tender_interval;
412 
413  /**
414  * Number of threads stored in underlying thread pool used by synchronous batch/scan/query commands.
415  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
416  * improves performance because threads do not have to be created/destroyed for each command.
417  * Calculate your value using the following formula:
418  *
419  * thread_pool_size = (concurrent synchronous batch/scan/query commands) * (server nodes)
420  *
421  * If your application only uses async commands, this field can be set to zero.
422  * Default: 16
423  */
425 
426  /**
427  * Client policies
428  */
430 
431  /**
432  * lua config. This is a global config even though it's located here in cluster config.
433  * This config has been left here to avoid breaking the API.
434  *
435  * The global lua config will only be changed once on first cluster initialization.
436  * A better method for initializing lua configuration is to leave this field alone and
437  * instead call aerospike_init_lua():
438  *
439  * ~~~~~~~~~~{.c}
440  * // Get default global lua configuration.
441  * as_config_lua lua;
442  * as_config_lua_init(&lua);
443  *
444  * // Optionally modify lua defaults.
445  * lua.cache_enabled = <enable lua cache>;
446  * strcpy(lua.system_path, <lua system directory>);
447  * strcpy(lua.user_path, <lua user directory>);
448  *
449  * // Initialize global lua configuration.
450  * aerospike_init_lua(&lua);
451  * ~~~~~~~~~~
452  */
454 
455  /*
456  * TLS configuration parameters.
457  */
459 
460  /**
461  * Action to perform if client fails to connect to seed hosts.
462  *
463  * If fail_if_not_connected is true (default), the cluster creation will fail
464  * when all seed hosts are not reachable.
465  *
466  * If fail_if_not_connected is false, an empty cluster will be created and the
467  * client will automatically connect when Aerospike server becomes available.
468  */
470 
471  /**
472  * Flag to signify if "services-alternate" should be used instead of "services"
473  * Default : false
474  */
476 
477  /**
478  * Indicates if shared memory should be used for cluster tending. Shared memory
479  * is useful when operating in single threaded mode with multiple client processes.
480  * This model is used by wrapper languages such as PHP and Python. When enabled,
481  * the data partition maps are maintained by only one process and all other processes
482  * use these shared memory maps.
483  *
484  * Shared memory should not be enabled for multi-threaded programs.
485  * Default: false
486  */
487  bool use_shm;
488 
489  /**
490  * Shared memory identifier. This identifier should be the same for all applications
491  * that use the Aerospike C client.
492  * Default: 0xA6000000
493  */
494  int shm_key;
495 
496  /**
497  * Shared memory maximum number of server nodes allowed. This value is used to size
498  * the fixed shared memory segment. Leave a cushion between actual server node
499  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
500  * Default: 16
501  */
502  uint32_t shm_max_nodes;
503 
504  /**
505  * Shared memory maximum number of namespaces allowed. This value is used to size
506  * the fixed shared memory segment. Leave a cushion between actual namespaces
507  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
508  * Default: 8
509  */
511 
512  /**
513  * Take over shared memory cluster tending if the cluster hasn't been tended by this
514  * threshold in seconds.
515  * Default: 30
516  */
518 } as_config;
519 
520 /******************************************************************************
521  * FUNCTIONS
522  *****************************************************************************/
523 
524 /**
525  * Initialize the configuration to default values.
526  *
527  * You should do this to ensure the configuration has valid values, before
528  * populating it with custom options.
529  *
530  * ~~~~~~~~~~{.c}
531  * as_config config;
532  * as_config_init(&config);
533  * as_config_add_host(&config, "127.0.0.1", 3000);
534  * ~~~~~~~~~~
535  *
536  * @relates as_config
537  */
538 as_config*
539 as_config_init(as_config* config);
540 
541 /**
542  * Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],...
543  * Hostname may also be an IP address in the following formats.
544  *
545  * ~~~~~~~~~~{.c}
546  * IPv4: xxx.xxx.xxx.xxx
547  * IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
548  * IPv6: [xxxx::xxxx]
549  * ~~~~~~~~~~
550  *
551  * The host addresses will be copied.
552  * The caller is responsible for the original string.
553  *
554  * ~~~~~~~~~~{.c}
555  * as_config config;
556  * as_config_init(&config);
557  * as_config_add_hosts(&config, "host1,host2:3010,192.168.20.1:3020,[2001::1000]:3030", 3000);
558  * ~~~~~~~~~~
559  *
560  * @relates as_config
561  */
562 bool
563 as_config_add_hosts(as_config* config, const char* string, uint16_t default_port);
564 
565 /**
566  * Add host to seed the cluster.
567  * The host address will be copied.
568  * The caller is responsible for the original address string.
569  *
570  * ~~~~~~~~~~{.c}
571  * as_config config;
572  * as_config_init(&config);
573  * as_config_add_host(&config, "127.0.0.1", 3000);
574  * ~~~~~~~~~~
575  *
576  * @relates as_config
577  */
578 void
579 as_config_add_host(as_config* config, const char* address, uint16_t port);
580 
581 /**
582  * Remove all hosts.
583  *
584  * @relates as_config
585  */
586 void
588 
589 /**
590  * User authentication for servers with restricted access. The password will be stored by the
591  * client and sent to server in hashed format.
592  *
593  * ~~~~~~~~~~{.c}
594  * as_config config;
595  * as_config_init(&config);
596  * as_config_set_user(&config, "charlie", "mypassword");
597  * ~~~~~~~~~~
598  *
599  * @relates as_config
600  */
601 bool
602 as_config_set_user(as_config* config, const char* user, const char* password);
603 
604 /**
605  * Free existing string if not null and copy value to string.
606  */
607 void
608 as_config_set_string(char** str, const char* value);
609 
610 /**
611  * Set expected cluster name.
612  *
613  * @relates as_config
614  */
615 static inline void
616 as_config_set_cluster_name(as_config* config, const char* cluster_name)
617 {
618  as_config_set_string(&config->cluster_name, cluster_name);
619 }
620 
621 /**
622  * Initialize global lua configuration to defaults.
623  *
624  * @relates as_config
625  */
626 static inline void
628 {
629  lua->cache_enabled = false;
630  strcpy(lua->system_path, AS_CONFIG_LUA_SYSTEM_PATH);
631  strcpy(lua->user_path, AS_CONFIG_LUA_USER_PATH);
632 }
633 
634 /**
635  * Set TLS path to a trusted CA certificate file.
636  *
637  * @relates as_config
638  */
639 static inline void
640 as_config_tls_set_cafile(as_config* config, const char* cafile)
641 {
642  as_config_set_string(&config->tls.cafile, cafile);
643 }
644 
645 /**
646  * Set TLS path to a directory of trusted certificates.
647  *
648  * @relates as_config
649  */
650 static inline void
651 as_config_tls_set_capath(as_config* config, const char* capath)
652 {
653  as_config_set_string(&config->tls.capath, capath);
654 }
655 
656 /**
657  * Set TLS enabled protocols.
658  *
659  * @relates as_config
660  */
661 static inline void
662 as_config_tls_set_protocol(as_config* config, const char* protocol)
663 {
664  as_config_set_string(&config->tls.protocol, protocol);
665 }
666 
667 /**
668  * Set TLS enabled cipher suites.
669  *
670  * @relates as_config
671  */
672 static inline void
673 as_config_tls_set_cipher_suite(as_config* config, const char* cipher_suite)
674 {
675  as_config_set_string(&config->tls.cipher_suite, cipher_suite);
676 }
677 
678 /**
679  * Set TLS path to a certificate blacklist file.
680  *
681  * @relates as_config
682  */
683 static inline void
684 as_config_tls_set_cert_blacklist(as_config* config, const char* cert_blacklist)
685 {
686  as_config_set_string(&config->tls.cert_blacklist, cert_blacklist);
687 }
688 
689 #ifdef __cplusplus
690 } // end extern "C"
691 #endif
uint32_t tender_interval
Definition: as_config.h:411
bool use_services_alternate
Definition: as_config.h:475
uint32_t conn_timeout_ms
Definition: as_config.h:405
uint32_t shm_takeover_threshold_sec
Definition: as_config.h:517
#define AS_USER_SIZE
Definition: as_password.h:28
static void as_config_set_cluster_name(as_config *config, const char *cluster_name)
Definition: as_config.h:616
bool as_config_set_user(as_config *config, const char *user, const char *password)
as_addr_map * ip_map
Definition: as_config.h:359
bool use_shm
Definition: as_config.h:487
bool fail_if_not_connected
Definition: as_config.h:469
char * cipher_suite
Definition: as_config.h:181
int shm_key
Definition: as_config.h:494
as_config_lua lua
Definition: as_config.h:453
uint32_t shm_max_nodes
Definition: as_config.h:502
uint32_t thread_pool_size
Definition: as_config.h:424
uint32_t shm_max_namespaces
Definition: as_config.h:510
bool as_config_add_hosts(as_config *config, const char *string, uint16_t default_port)
bool log_session_info
Definition: as_config.h:214
uint32_t ip_map_size
Definition: as_config.h:365
static void as_config_tls_set_cert_blacklist(as_config *config, const char *cert_blacklist)
Definition: as_config.h:684
char * capath
Definition: as_config.h:150
char * cafile
Definition: as_config.h:142
char * cert_blacklist
Definition: as_config.h:209
as_config * as_config_init(as_config *config)
static void as_config_tls_set_protocol(as_config *config, const char *protocol)
Definition: as_config.h:662
uint32_t pipe_max_conns_per_node
Definition: as_config.h:398
as_vector * hosts
Definition: as_config.h:327
as_policies policies
Definition: as_config.h:429
void as_config_add_host(as_config *config, const char *address, uint16_t port)
uint32_t max_conns_per_node
Definition: as_config.h:378
#define AS_CONFIG_PATH_MAX_SIZE
Definition: as_config.h:60
static void as_config_tls_set_cafile(as_config *config, const char *cafile)
Definition: as_config.h:640
as_config_tls tls
Definition: as_config.h:458
void as_config_set_string(char **str, const char *value)
bool crl_check
Definition: as_config.h:188
char * protocol
Definition: as_config.h:165
static void as_config_tls_set_capath(as_config *config, const char *capath)
Definition: as_config.h:651
bool cache_enabled
Definition: as_config.h:101
static void as_config_tls_set_cipher_suite(as_config *config, const char *cipher_suite)
Definition: as_config.h:673
uint32_t async_max_conns_per_node
Definition: as_config.h:388
char system_path[AS_CONFIG_PATH_MAX_SIZE]
Definition: as_config.h:108
bool crl_check_all
Definition: as_config.h:195
static void as_config_lua_init(as_config_lua *lua)
Definition: as_config.h:627
bool encrypt_only
Definition: as_config.h:135
char user_path[AS_CONFIG_PATH_MAX_SIZE]
Definition: as_config.h:114
char * cluster_name
Definition: as_config.h:346
char * alt
Definition: as_config.h:86
#define AS_PASSWORD_HASH_SIZE
Definition: as_password.h:33
char * orig
Definition: as_config.h:81
void as_config_clear_hosts(as_config *config)