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-2017 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  * Cluster event notification type.
92  *
93  * @ingroup as_config_object
94  */
95 typedef enum as_cluster_event_type_e {
96  /**
97  * Node was added to cluster.
98  */
100 
101  /**
102  * Node was removed fron cluster.
103  */
105 
106  /**
107  * There are no active nodes in the cluster.
108  */
111 
112 /**
113  * Cluster event notification data.
114  *
115  * @ingroup as_config_object
116  */
117 typedef struct as_cluster_event_s {
118  /**
119  * Node name.
120  */
121  const char* node_name;
122 
123  /**
124  * Node IP address in string format.
125  */
126  const char* node_address;
127 
128  /**
129  * User defined data.
130  */
131  void* udata;
132 
133  /**
134  * Cluster event notification type.
135  */
138 
139 /**
140  * Cluster event notification callback function.
141  * as_cluster_event is placed on the stack before calling.
142  * Do not free node_name or node_address.
143  *
144  * @ingroup as_config_object
145  */
147 
148 /**
149  * lua module config
150  *
151  * @ingroup as_config_object
152  */
153 typedef struct as_config_lua_s {
154 
155  /**
156  * Enable caching of UDF files in the client
157  * application.
158  */
160 
161  /**
162  * The path to the system UDF files. These UDF files
163  * are installed with the aerospike client library.
164  * Default location defined in: AS_CONFIG_LUA_SYSTEM_PATH
165  */
166  char system_path[AS_CONFIG_PATH_MAX_SIZE];
167 
168  /**
169  * The path to user's UDF files.
170  * Default location defined in: AS_CONFIG_LUA_USER_PATH
171  */
172  char user_path[AS_CONFIG_PATH_MAX_SIZE];
173 
174 } as_config_lua;
175 
176 /**
177  * TLS module config
178  *
179  * @ingroup as_config_object
180  */
181 typedef struct as_config_tls_s {
182 
183  /**
184  * Enable TLS on connections.
185  * By default TLS is disabled.
186  */
187  bool enable;
188 
189  /**
190  * Only encrypt connections; do not verify certificates.
191  * By default TLS will verify certificates.
192  */
194 
195  /**
196  * Path to a trusted CA certificate file.
197  * By default TLS will use system standard trusted CA certificates.
198  * Use as_config_tls_set_cafile() to set this field.
199  */
200  char* cafile;
201 
202  /**
203  * Path to a directory of trusted certificates.
204  * See the OpenSSL SSL_CTX_load_verify_locations manual page for
205  * more information about the format of the directory.
206  * Use as_config_tls_set_capath() to set this field.
207  */
208  char* capath;
209 
210  /**
211  * Specifies enabled protocols.
212  *
213  * This format is the same as Apache's SSLProtocol documented
214  * at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol
215  *
216  * If not specified (NULL) the client will use "-all +TLSv1.2".
217  *
218  * If you are not sure what protocols to select this option is
219  * best left unspecified (NULL).
220  *
221  * Use as_config_tls_set_protocols() to set this field.
222  */
223  char* protocols;
224 
225  /**
226  * Specifies enabled cipher suites.
227  *
228  * The format is the same as OpenSSL's Cipher List Format documented
229  * at https://www.openssl.org/docs/manmaster/apps/ciphers.html
230  *
231  * If not specified the OpenSSL default cipher suite described in
232  * the ciphers documentation will be used.
233  *
234  * If you are not sure what cipher suite to select this option
235  * is best left unspecified (NULL).
236  *
237  * Use as_config_tls_set_cipher_suite() to set this field.
238  */
240 
241  /**
242  * Enable CRL checking for the certificate chain leaf certificate.
243  * An error occurs if a suitable CRL cannot be found.
244  * By default CRL checking is disabled.
245  */
246  bool crl_check;
247 
248  /**
249  * Enable CRL checking for the entire certificate chain.
250  * An error occurs if a suitable CRL cannot be found.
251  * By default CRL checking is disabled.
252  */
254 
255  /**
256  * Path to a certificate blacklist file.
257  * The file should contain one line for each blacklisted certificate.
258  * Each line starts with the certificate serial number expressed in hex.
259  * Each entry may optionally specify the issuer name of the
260  * certificate (serial numbers are only required to be unique per
261  * issuer). Example records:
262  * 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA
263  * E2D4B0E570F9EF8E885C065899886461
264  *
265  * Use as_config_tls_set_cert_blacklist() to set this field.
266  */
268 
269  /**
270  * Log session information for each connection.
271  */
273 
274  /**
275  * Path to the client's key for mutual authentication.
276  * By default mutual authentication is disabled.
277  *
278  * Use as_config_tls_set_keyfile() to set this field.
279  */
280  char* keyfile;
281 
282  /**
283  * Path to the client's certificate chain file for mutual authentication.
284  * By default mutual authentication is disabled.
285  *
286  * Use as_config_tls_set_certfile() to set this field.
287  */
288  char* certfile;
289 
290 } as_config_tls;
291 
292 /**
293  * The `as_config` contains the settings for the `aerospike` client. Including
294  * default policies, seed hosts in the cluster and other settings.
295  *
296  * ## Initialization
297  *
298  * Before using as_config, you must first initialize it. This will setup the
299  * default values.
300  *
301  * ~~~~~~~~~~{.c}
302  * as_config config;
303  * as_config_init(&config);
304  * ~~~~~~~~~~
305  *
306  * Once initialized, you can populate the values.
307  *
308  * ## Seed Hosts
309  *
310  * The client will require at least one seed host defined in the
311  * configuration. The seed host is defined in `as_config.hosts`.
312  *
313  * ~~~~~~~~~~{.c}
314  * as_config_add_host(&config, "127.0.0.1", 3000);
315  * ~~~~~~~~~~
316  *
317  * The client will iterate over the list until it connects with one of the hosts.
318  *
319  * ## Policies
320  *
321  * The configuration also defines default policies for the application. The
322  * `as_config_init()` function already presets default values for the policies.
323  *
324  * Policies define the behavior of the client, which can be global across
325  * operations, global to a single operation, or local to a single use of an
326  * operation.
327  *
328  * Each database operation accepts a policy for that operation as an a argument.
329  * This is considered a local policy, and is a single use policy. This policy
330  * supersedes any global policy defined.
331  *
332  * If a value of the policy is not defined, then the rule is to fallback to the
333  * global policy for that operation. If the global policy for that operation is
334  * undefined, then the global default value will be used.
335  *
336  * If you find that you have behavior that you want every use of an operation
337  * to utilize, then you can specify the default policy in as_config.policies.
338  *
339  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
340  * policy. If you find yourself setting the `key` policy value for every call
341  * to `aerospike_key_put()`, then you may find it beneficial to set the global
342  * `as_policy_write` in `as_policies.write`, which all write operations will use.
343  *
344  * ~~~~~~~~~~{.c}
345  * config.policies.write.key = AS_POLICY_KEY_SEND;
346  * ~~~~~~~~~~
347  *
348  * Global operation policies:
349  * - as_policies.read
350  * - as_policies.write
351  * - as_policies.operate
352  * - as_policies.remove
353  * - as_policies.query
354  * - as_policies.scan
355  * - as_policies.info
356  *
357  *
358  * ## User-Defined Function Settings
359  *
360  * If you are using user-defined functions (UDF) for processing query
361  * results (i.e aggregations), then you will find it useful to set the
362  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
363  * which allows you to define a path to where the client library will look for
364  * Lua files for processing.
365  *
366  * ~~~~~~~~~~{.c}
367  * strcpy(config.mod_lua.user_path, "/home/me/lua");
368  * ~~~~~~~~~~
369  *
370  * Never call as_config_destroy() directly because ownership of config fields
371  * is transferred to aerospike in aerospike_init() or aerospike_new().
372  *
373  * @ingroup client_objects
374  */
375 typedef struct as_config_s {
376  /**
377  * Seed hosts. Populate with one or more hosts in the cluster that you intend to connect with.
378  * Do not set directly. Use as_config_add_hosts() or as_config_add_host() to add seed hosts.
379  */
381 
382  /**
383  * User authentication to cluster. Leave empty for clusters running without restricted access.
384  */
385  char user[AS_USER_SIZE];
386 
387  /**
388  * Password authentication to cluster. The hashed value of password will be stored by the client
389  * and sent to server in same format. Leave empty for clusters running without restricted access.
390  */
391  char password[AS_PASSWORD_HASH_SIZE];
392 
393  /**
394  * Expected cluster name. If not null, server nodes must return this cluster name in order to
395  * join the client's view of the cluster. Should only be set when connecting to servers that
396  * support the "cluster-name" info command. Use as_config_set_cluster_name() to set this field.
397  * Default: NULL
398  */
400 
401  /**
402  * Cluster event function that will be called when nodes are added/removed from the cluster.
403  *
404  * Default: NULL (no callback will be made)
405  */
407 
408  /**
409  * Cluster event user data that will be passed back to event_callback.
410  *
411  * Default: NULL
412  */
414 
415  /**
416  * A IP translation table is used in cases where different clients use different server
417  * IP addresses. This may be necessary when using clients from both inside and outside
418  * a local area network. Default is no translation.
419  *
420  * The key is the IP address returned from friend info requests to other servers. The
421  * value is the real IP address used to connect to the server.
422  *
423  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
424  * responsible for memory deallocation of the original data structure.
425  */
427 
428  /**
429  * Length of ip_map array.
430  * Default: 0
431  */
432  uint32_t ip_map_size;
433 
434  /**
435  * Maximum number of synchronous connections allowed per server node. Synchronous transactions
436  * will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS"
437  * if the maximum number of connections would be exceeded.
438  *
439  * The number of connections used per node depends on how many concurrent threads issue
440  * database commands plus sub-threads used for parallel multi-node commands (batch, scan,
441  * and query). One connection will be used for each thread.
442  *
443  * Default: 300
444  */
446 
447  /**
448  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
449  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
450  * loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
451  * will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
452  * This variable is ignored if asynchronous event loops are not created.
453  * Default: 300
454  */
456 
457  /**
458  * Maximum number of pipeline connections allowed for each node.
459  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
460  * loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
461  * Async transactions will be rejected if the limit would be exceeded.
462  * This variable is ignored if asynchronous event loops are not created.
463  * Default: 64
464  */
466 
467  /**
468  * Number of synchronous connection pools used for each node. Machines with 8 cpu cores or
469  * less usually need just one connection pool per node. Machines with a large number of cpu
470  * cores may have their synchronous performance limited by contention for pooled connections.
471  * Contention for pooled connections can be reduced by creating multiple mini connection pools
472  * per node.
473  *
474  * Default: 1
475  */
477 
478  /**
479  * Initial host connection timeout in milliseconds. The timeout when opening a connection
480  * to the server host for the first time.
481  * Default: 1000
482  */
483  uint32_t conn_timeout_ms;
484 
485  /**
486  * Maximum socket idle time in seconds. Connection pools will discard sockets that have
487  * been idle longer than the maximum. The value is limited to 24 hours (86400).
488  *
489  * It's important to set this value to a few seconds less than the server's proto-fd-idle-ms
490  * (default 60000 milliseconds or 1 minute), so the client does not attempt to use a socket
491  * that has already been reaped by the server.
492  *
493  * Default: 0 seconds (disabled) for non-TLS connections, 55 seconds for TLS connections.
494  */
495  uint32_t max_socket_idle;
496 
497  /**
498  * Polling interval in milliseconds for cluster tender
499  * Default: 1000
500  */
501  uint32_t tender_interval;
502 
503  /**
504  * Number of threads stored in underlying thread pool used by synchronous batch/scan/query commands.
505  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
506  * improves performance because threads do not have to be created/destroyed for each command.
507  * Calculate your value using the following formula:
508  *
509  * thread_pool_size = (concurrent synchronous batch/scan/query commands) * (server nodes)
510  *
511  * If your application only uses async commands, this field can be set to zero.
512  * Default: 16
513  */
515 
516  /**
517  * Client policies
518  */
520 
521  /**
522  * lua config. This is a global config even though it's located here in cluster config.
523  * This config has been left here to avoid breaking the API.
524  *
525  * The global lua config will only be changed once on first cluster initialization.
526  * A better method for initializing lua configuration is to leave this field alone and
527  * instead call aerospike_init_lua():
528  *
529  * ~~~~~~~~~~{.c}
530  * // Get default global lua configuration.
531  * as_config_lua lua;
532  * as_config_lua_init(&lua);
533  *
534  * // Optionally modify lua defaults.
535  * lua.cache_enabled = <enable lua cache>;
536  * strcpy(lua.system_path, <lua system directory>);
537  * strcpy(lua.user_path, <lua user directory>);
538  *
539  * // Initialize global lua configuration.
540  * aerospike_init_lua(&lua);
541  * ~~~~~~~~~~
542  */
544 
545  /*
546  * TLS configuration parameters.
547  */
549 
550  /**
551  * Action to perform if client fails to connect to seed hosts.
552  *
553  * If fail_if_not_connected is true (default), the cluster creation will fail
554  * when all seed hosts are not reachable.
555  *
556  * If fail_if_not_connected is false, an empty cluster will be created and the
557  * client will automatically connect when Aerospike server becomes available.
558  */
560 
561  /**
562  * Flag to signify if "services-alternate" should be used instead of "services"
563  * Default : false
564  */
566 
567  /**
568  * Indicates if shared memory should be used for cluster tending. Shared memory
569  * is useful when operating in single threaded mode with multiple client processes.
570  * This model is used by wrapper languages such as PHP and Python. When enabled,
571  * the data partition maps are maintained by only one process and all other processes
572  * use these shared memory maps.
573  *
574  * Shared memory should not be enabled for multi-threaded programs.
575  * Default: false
576  */
577  bool use_shm;
578 
579  /**
580  * Identifier for the shared memory segment associated with the target Aerospike cluster.
581  * Each shared memory segment contains state for one Aerospike cluster. If there are
582  * multiple Aerospike clusters, a different shm_key must be defined for each cluster.
583  *
584  * Default: 0xA7000000
585  */
586  int shm_key;
587 
588  /**
589  * Shared memory maximum number of server nodes allowed. This value is used to size
590  * the fixed shared memory segment. Leave a cushion between actual server node
591  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
592  * Default: 16
593  */
594  uint32_t shm_max_nodes;
595 
596  /**
597  * Shared memory maximum number of namespaces allowed. This value is used to size
598  * the fixed shared memory segment. Leave a cushion between actual namespaces
599  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
600  * Default: 8
601  */
603 
604  /**
605  * Take over shared memory cluster tending if the cluster hasn't been tended by this
606  * threshold in seconds.
607  * Default: 30
608  */
610 } as_config;
611 
612 /******************************************************************************
613  * FUNCTIONS
614  *****************************************************************************/
615 
616 /**
617  * Initialize the configuration to default values.
618  *
619  * You should do this to ensure the configuration has valid values, before
620  * populating it with custom options.
621  *
622  * ~~~~~~~~~~{.c}
623  * as_config config;
624  * as_config_init(&config);
625  * as_config_add_host(&config, "127.0.0.1", 3000);
626  * ~~~~~~~~~~
627  *
628  * @relates as_config
629  */
630 as_config*
631 as_config_init(as_config* config);
632 
633 /**
634  * Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],...
635  * Hostname may also be an IP address in the following formats.
636  *
637  * ~~~~~~~~~~{.c}
638  * IPv4: xxx.xxx.xxx.xxx
639  * IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
640  * IPv6: [xxxx::xxxx]
641  * ~~~~~~~~~~
642  *
643  * The host addresses will be copied.
644  * The caller is responsible for the original string.
645  *
646  * ~~~~~~~~~~{.c}
647  * as_config config;
648  * as_config_init(&config);
649  * as_config_add_hosts(&config, "host1,host2:3010,192.168.20.1:3020,[2001::1000]:3030", 3000);
650  * ~~~~~~~~~~
651  *
652  * @relates as_config
653  */
654 bool
655 as_config_add_hosts(as_config* config, const char* string, uint16_t default_port);
656 
657 /**
658  * Add host to seed the cluster.
659  * The host address will be copied.
660  * The caller is responsible for the original address string.
661  *
662  * ~~~~~~~~~~{.c}
663  * as_config config;
664  * as_config_init(&config);
665  * as_config_add_host(&config, "127.0.0.1", 3000);
666  * ~~~~~~~~~~
667  *
668  * @relates as_config
669  */
670 void
671 as_config_add_host(as_config* config, const char* address, uint16_t port);
672 
673 /**
674  * Remove all hosts.
675  *
676  * @relates as_config
677  */
678 void
680 
681 /**
682  * User authentication for servers with restricted access. The password will be stored by the
683  * client and sent to server in hashed format.
684  *
685  * ~~~~~~~~~~{.c}
686  * as_config config;
687  * as_config_init(&config);
688  * as_config_set_user(&config, "charlie", "mypassword");
689  * ~~~~~~~~~~
690  *
691  * @relates as_config
692  */
693 bool
694 as_config_set_user(as_config* config, const char* user, const char* password);
695 
696 /**
697  * Free existing string if not null and copy value to string.
698  */
699 void
700 as_config_set_string(char** str, const char* value);
701 
702 /**
703  * Set expected cluster name.
704  *
705  * @relates as_config
706  */
707 static inline void
708 as_config_set_cluster_name(as_config* config, const char* cluster_name)
709 {
710  as_config_set_string(&config->cluster_name, cluster_name);
711 }
712 
713 /**
714  * Set cluster event callback and user data.
715  *
716  * @relates as_config
717  */
718 static inline void
720 {
721  config->event_callback = callback;
722  config->event_callback_udata = udata;
723 }
724 
725 /**
726  * Initialize global lua configuration to defaults.
727  *
728  * @relates as_config
729  */
730 static inline void
732 {
733  lua->cache_enabled = false;
734  strcpy(lua->system_path, AS_CONFIG_LUA_SYSTEM_PATH);
735  strcpy(lua->user_path, AS_CONFIG_LUA_USER_PATH);
736 }
737 
738 /**
739  * Set TLS path to a trusted CA certificate file.
740  *
741  * @relates as_config
742  */
743 static inline void
744 as_config_tls_set_cafile(as_config* config, const char* cafile)
745 {
746  as_config_set_string(&config->tls.cafile, cafile);
747 }
748 
749 /**
750  * Set TLS path to a directory of trusted certificates.
751  *
752  * @relates as_config
753  */
754 static inline void
755 as_config_tls_set_capath(as_config* config, const char* capath)
756 {
757  as_config_set_string(&config->tls.capath, capath);
758 }
759 
760 /**
761  * Set TLS enabled protocols.
762  *
763  * @relates as_config
764  */
765 static inline void
766 as_config_tls_set_protocols(as_config* config, const char* protocols)
767 {
768  as_config_set_string(&config->tls.protocols, protocols);
769 }
770 
771 /**
772  * Set TLS enabled cipher suites.
773  *
774  * @relates as_config
775  */
776 static inline void
777 as_config_tls_set_cipher_suite(as_config* config, const char* cipher_suite)
778 {
779  as_config_set_string(&config->tls.cipher_suite, cipher_suite);
780 }
781 
782 /**
783  * Set TLS path to a certificate blacklist file.
784  *
785  * @relates as_config
786  */
787 static inline void
788 as_config_tls_set_cert_blacklist(as_config* config, const char* cert_blacklist)
789 {
790  as_config_set_string(&config->tls.cert_blacklist, cert_blacklist);
791 }
792 
793 /**
794  * Set TLS path to the client's key for mutual authentication.
795  *
796  * @relates as_config
797  */
798 static inline void
799 as_config_tls_set_keyfile(as_config* config, const char* keyfile)
800 {
801  as_config_set_string(&config->tls.keyfile, keyfile);
802 }
803 
804 /**
805  * Set TLS path to the client's certificate chain file for mutual authentication.
806  *
807  * @relates as_config
808  */
809 static inline void
810 as_config_tls_set_certfile(as_config* config, const char* certfile)
811 {
812  as_config_set_string(&config->tls.certfile, certfile);
813 }
814 
815 /**
816  * Add TLS host to seed the cluster.
817  * The host address and TLS name will be copied.
818  * The caller is responsible for the original address string.
819  *
820  * ~~~~~~~~~~{.c}
821  * as_config config;
822  * as_config_init(&config);
823  * as_config_tls_add_host(&config, "127.0.0.1", "node1.test.org", 3000);
824  * ~~~~~~~~~~
825  *
826  * @relates as_config
827  */
828 void
829 as_config_tls_add_host(as_config* config, const char* address, const char* tls_name, uint16_t port);
830 
831 #ifdef __cplusplus
832 } // end extern "C"
833 #endif