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  */
141  char* cafile;
142 
143  /**
144  * Path to a directory of trusted certificates.
145  * See the OpenSSL SSL_CTX_load_verify_locations manual page for
146  * more information about the format of the directory.
147  */
148  char* capath;
149 
150  /**
151  * Specifies enabled protocols.
152  *
153  * This format is the same as Apache's SSLProtocol documented
154  * at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol
155  *
156  * If not specified (NULL) the client will use "-all +TLSv1.2".
157  *
158  * If you are not sure what protocols to select this option is
159  * best left unspecified (NULL).
160  */
161  char* protocol;
162 
163  /**
164  * Specifies enabled cipher suites.
165  *
166  * The format is the same as OpenSSL's Cipher List Format documented
167  * at https://www.openssl.org/docs/manmaster/apps/ciphers.html
168  *
169  * If not specified the OpenSSL default cipher suite described in
170  * the ciphers documentation will be used.
171  *
172  * If you are not sure what cipher suite to select this option
173  * is best left unspecified (NULL).
174  */
176 
177  /**
178  * Enable CRL checking for the certificate chain leaf certificate.
179  * An error occurs if a suitable CRL cannot be found.
180  * By default CRL checking is disabled.
181  */
182  bool crl_check;
183 
184  /**
185  * Enable CRL checking for the entire certificate chain.
186  * An error occurs if a suitable CRL cannot be found.
187  * By default CRL checking is disabled.
188  */
190 
191  /**
192  * Path to a certificate blacklist file.
193  * The file should contain one line for each blacklisted certificate.
194  * Each line starts with the certificate serial number expressed in hex.
195  * Each entry may optionally specify the issuer name of the
196  * certificate (serial numbers are only required to be unique per
197  * issuer). Example records:
198  * 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA
199  * E2D4B0E570F9EF8E885C065899886461
200  */
202 
203  /**
204  * Log session information for each connection.
205  */
207 
208 } as_config_tls;
209 
210 /**
211  * The `as_config` contains the settings for the `aerospike` client. Including
212  * default policies, seed hosts in the cluster and other settings.
213  *
214  * ## Initialization
215  *
216  * Before using as_config, you must first initialize it. This will setup the
217  * default values.
218  *
219  * ~~~~~~~~~~{.c}
220  * as_config config;
221  * as_config_init(&config);
222  * ~~~~~~~~~~
223  *
224  * Once initialized, you can populate the values.
225  *
226  * ## Seed Hosts
227  *
228  * The client will require at least one seed host defined in the
229  * configuration. The seed host is defined in `as_config.hosts`.
230  *
231  * ~~~~~~~~~~{.c}
232  * as_config_add_host(&config, "127.0.0.1", 3000);
233  * ~~~~~~~~~~
234  *
235  * The client will iterate over the list until it connects with one of the hosts.
236  *
237  * ## Policies
238  *
239  * The configuration also defines default policies for the application. The
240  * `as_config_init()` function already presets default values for the policies.
241  *
242  * Policies define the behavior of the client, which can be global across
243  * operations, global to a single operation, or local to a single use of an
244  * operation.
245  *
246  * Each database operation accepts a policy for that operation as an a argument.
247  * This is considered a local policy, and is a single use policy. This policy
248  * supersedes any global policy defined.
249  *
250  * If a value of the policy is not defined, then the rule is to fallback to the
251  * global policy for that operation. If the global policy for that operation is
252  * undefined, then the global default value will be used.
253  *
254  * If you find that you have behavior that you want every use of an operation
255  * to utilize, then you can specify the default policy in as_config.policies.
256  *
257  * For example, the `aerospike_key_put()` operation takes an `as_policy_write`
258  * policy. If you find yourself setting the `key` policy value for every call
259  * to `aerospike_key_put()`, then you may find it beneficial to set the global
260  * `as_policy_write` in `as_policies.write`, which all write operations will use.
261  *
262  * ~~~~~~~~~~{.c}
263  * config.policies.write.key = AS_POLICY_KEY_SEND;
264  * ~~~~~~~~~~
265  *
266  * If you find that you want to use a policy value across all operations, then
267  * you may find it beneficial to set the default policy value for that policy
268  * value.
269  *
270  * For example, if you keep setting the key policy value to
271  * `AS_POLICY_KEY_SEND`, then you may want to just set `as_policies.key`. This
272  * will set the global default value for the policy value. So, if an global
273  * operation policy or a local operation policy does not define a value, then
274  * this value will be used.
275  *
276  * ~~~~~~~~~~{.c}
277  * config.policies.key = AS_POLICY_KEY_SEND;
278  * ~~~~~~~~~~
279  *
280  * Global default policy values:
281  * - as_policies.timeout
282  * - as_policies.retry
283  * - as_policies.key
284  * - as_policies.gen
285  * - as_policies.exists
286  *
287  * Global operation policies:
288  * - as_policies.read
289  * - as_policies.write
290  * - as_policies.operate
291  * - as_policies.remove
292  * - as_policies.query
293  * - as_policies.scan
294  * - as_policies.info
295  *
296  *
297  * ## User-Defined Function Settings
298  *
299  * If you are using using user-defined functions (UDF) for processing query
300  * results (i.e aggregations), then you will find it useful to set the
301  * `mod_lua` settings. Of particular importance is the `mod_lua.user_path`,
302  * which allows you to define a path to where the client library will look for
303  * Lua files for processing.
304  *
305  * ~~~~~~~~~~{.c}
306  * strcpy(config.mod_lua.user_path, "/home/me/lua");
307  * ~~~~~~~~~~
308  *
309  * @ingroup client_objects
310  */
311 typedef struct as_config_s {
312  /**
313  * Seed hosts. Populate with one or more hosts in the cluster that you intend to connect with.
314  * Do not set directly. Use as_config_add_hosts() or as_config_add_host() to add seed hosts.
315  */
317 
318  /**
319  * User authentication to cluster. Leave empty for clusters running without restricted access.
320  */
321  char user[AS_USER_SIZE];
322 
323  /**
324  * Password authentication to cluster. The hashed value of password will be stored by the client
325  * and sent to server in same format. Leave empty for clusters running without restricted access.
326  */
327  char password[AS_PASSWORD_HASH_SIZE];
328 
329  /**
330  * Expected cluster ID. If not null, server nodes must return this cluster ID in order to
331  * join the client's view of the cluster. Should only be set when connecting to servers that
332  * support the "cluster-id" info command. Use as_config_set_cluster_id() to set this field.
333  * Default: NULL
334  */
335  char* cluster_id;
336 
337  /**
338  * A IP translation table is used in cases where different clients use different server
339  * IP addresses. This may be necessary when using clients from both inside and outside
340  * a local area network. Default is no translation.
341  *
342  * The key is the IP address returned from friend info requests to other servers. The
343  * value is the real IP address used to connect to the server.
344  *
345  * A deep copy of ip_map is performed in aerospike_connect(). The caller is
346  * responsible for memory deallocation of the original data structure.
347  */
349 
350  /**
351  * Length of ip_map array.
352  * Default: 0
353  */
354  uint32_t ip_map_size;
355 
356  /**
357  * Maximum number of synchronous connections allowed per server node. Synchronous transactions
358  * will go through retry logic and potentially fail with error code "AEROSPIKE_ERR_NO_MORE_CONNECTIONS"
359  * if the maximum number of connections would be exceeded.
360  *
361  * The number of connections used per node depends on how many concurrent threads issue
362  * database commands plus sub-threads used for parallel multi-node commands (batch, scan,
363  * and query). One connection will be used for each thread.
364  *
365  * Default: 300
366  */
368 
369  /**
370  * Maximum number of asynchronous (non-pipeline) connections allowed for each node.
371  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
372  * loops are created, then each node/event loop asynchronous (non-pipeline) connection pool
373  * will have a limit of 50. Async transactions will be rejected if the limit would be exceeded.
374  * This variable is ignored if asynchronous event loops are not created.
375  * Default: 300
376  */
378 
379  /**
380  * Maximum number of pipeline connections allowed for each node.
381  * This limit will be enforced at the node/event loop level. If the value is 100 and 2 event
382  * loops are created, then each node/event loop pipeline connection pool will have a limit of 50.
383  * Async transactions will be rejected if the limit would be exceeded.
384  * This variable is ignored if asynchronous event loops are not created.
385  * Default: 64
386  */
388 
389  /**
390  * Initial host connection timeout in milliseconds. The timeout when opening a connection
391  * to the server host for the first time.
392  * Default: 1000
393  */
394  uint32_t conn_timeout_ms;
395 
396  /**
397  * Polling interval in milliseconds for cluster tender
398  * Default: 1000
399  */
400  uint32_t tender_interval;
401 
402  /**
403  * Number of threads stored in underlying thread pool used by synchronous batch/scan/query commands.
404  * These commands are often sent to multiple server nodes in parallel threads. A thread pool
405  * improves performance because threads do not have to be created/destroyed for each command.
406  * Calculate your value using the following formula:
407  *
408  * thread_pool_size = (concurrent synchronous batch/scan/query commands) * (server nodes)
409  *
410  * If your application only uses async commands, this field can be set to zero.
411  * Default: 16
412  */
414 
415  /**
416  * Client policies
417  */
419 
420  /**
421  * lua config. This is a global config even though it's located here in cluster config.
422  * This config has been left here to avoid breaking the API.
423  *
424  * The global lua config will only be changed once on first cluster initialization.
425  * A better method for initializing lua configuration is to leave this field alone and
426  * instead call aerospike_init_lua():
427  *
428  * ~~~~~~~~~~{.c}
429  * // Get default global lua configuration.
430  * as_config_lua lua;
431  * as_config_lua_init(&lua);
432  *
433  * // Optionally modify lua defaults.
434  * lua.cache_enabled = <enable lua cache>;
435  * strcpy(lua.system_path, <lua system directory>);
436  * strcpy(lua.user_path, <lua user directory>);
437  *
438  * // Initialize global lua configuration.
439  * aerospike_init_lua(&lua);
440  * ~~~~~~~~~~
441  */
443 
444  /*
445  * TLS configuration parameters.
446  */
448 
449  /**
450  * Action to perform if client fails to connect to seed hosts.
451  *
452  * If fail_if_not_connected is true (default), the cluster creation will fail
453  * when all seed hosts are not reachable.
454  *
455  * If fail_if_not_connected is false, an empty cluster will be created and the
456  * client will automatically connect when Aerospike server becomes available.
457  */
459 
460  /**
461  * Flag to signify if "services-alternate" should be used instead of "services"
462  * Default : false
463  */
465 
466  /**
467  * Indicates if shared memory should be used for cluster tending. Shared memory
468  * is useful when operating in single threaded mode with multiple client processes.
469  * This model is used by wrapper languages such as PHP and Python. When enabled,
470  * the data partition maps are maintained by only one process and all other processes
471  * use these shared memory maps.
472  *
473  * Shared memory should not be enabled for multi-threaded programs.
474  * Default: false
475  */
476  bool use_shm;
477 
478  /**
479  * Shared memory identifier. This identifier should be the same for all applications
480  * that use the Aerospike C client.
481  * Default: 0xA6000000
482  */
483  int shm_key;
484 
485  /**
486  * Shared memory maximum number of server nodes allowed. This value is used to size
487  * the fixed shared memory segment. Leave a cushion between actual server node
488  * count and shm_max_nodes so new nodes can be added without having to reboot the client.
489  * Default: 16
490  */
491  uint32_t shm_max_nodes;
492 
493  /**
494  * Shared memory maximum number of namespaces allowed. This value is used to size
495  * the fixed shared memory segment. Leave a cushion between actual namespaces
496  * and shm_max_namespaces so new namespaces can be added without having to reboot the client.
497  * Default: 8
498  */
500 
501  /**
502  * Take over shared memory cluster tending if the cluster hasn't been tended by this
503  * threshold in seconds.
504  * Default: 30
505  */
507 } as_config;
508 
509 /******************************************************************************
510  * FUNCTIONS
511  *****************************************************************************/
512 
513 /**
514  * Initialize the configuration to default values.
515  *
516  * You should do this to ensure the configuration has valid values, before
517  * populating it with custom options.
518  *
519  * ~~~~~~~~~~{.c}
520  * as_config config;
521  * as_config_init(&config);
522  * as_config_add_host(&config, "127.0.0.1", 3000);
523  * ~~~~~~~~~~
524  *
525  * @relates as_config
526  */
527 as_config*
528 as_config_init(as_config* config);
529 
530 /**
531  * Release memory associated with config.
532  *
533  * This function should only be called on a cluster initialize error.
534  * If a cluster is initialized, the config data will be transferred to as_cluster
535  * which has it's own destructor.
536  */
537 void
539 
540 /**
541  * Add seed host(s) from a string with format: hostname1[:tlsname1][:port1],...
542  * Hostname may also be an IP address in the following formats.
543  *
544  * ~~~~~~~~~~{.c}
545  * IPv4: xxx.xxx.xxx.xxx
546  * IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
547  * IPv6: [xxxx::xxxx]
548  * ~~~~~~~~~~
549  *
550  * The host addresses will be copied.
551  * The caller is responsible for the original string.
552  *
553  * ~~~~~~~~~~{.c}
554  * as_config config;
555  * as_config_init(&config);
556  * as_config_add_hosts(&config, "host1,host2:3010,192.168.20.1:3020,[2001::1000]:3030", 3000);
557  * ~~~~~~~~~~
558  *
559  * @relates as_config
560  */
561 bool
562 as_config_add_hosts(as_config* config, const char* string, uint16_t default_port);
563 
564 /**
565  * Add host to seed the cluster.
566  * The host address will be copied.
567  * The caller is responsible for the original address string.
568  *
569  * ~~~~~~~~~~{.c}
570  * as_config config;
571  * as_config_init(&config);
572  * as_config_add_host(&config, "127.0.0.1", 3000);
573  * ~~~~~~~~~~
574  *
575  * @relates as_config
576  */
577 void
578 as_config_add_host(as_config* config, const char* address, uint16_t port);
579 
580 /**
581  * User authentication for servers with restricted access. The password will be stored by the
582  * client and sent to server in hashed format.
583  *
584  * ~~~~~~~~~~{.c}
585  * as_config config;
586  * as_config_init(&config);
587  * as_config_set_user(&config, "charlie", "mypassword");
588  * ~~~~~~~~~~
589  *
590  * @relates as_config
591  */
592 bool
593 as_config_set_user(as_config* config, const char* user, const char* password);
594 
595 /**
596  * Set expected cluster ID.
597  */
598 void
599 as_config_set_cluster_id(as_config* config, const char* cluster_id);
600 
601 /**
602  * Initialize global lua configuration to defaults.
603  */
604 static inline void
606 {
607  lua->cache_enabled = false;
608  strcpy(lua->system_path, AS_CONFIG_LUA_SYSTEM_PATH);
609  strcpy(lua->user_path, AS_CONFIG_LUA_USER_PATH);
610 }
611 
612 #ifdef __cplusplus
613 } // end extern "C"
614 #endif