http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/93-querystrings/8c-type-conversions.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/93-querystrings/8c-type-conversions.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/93-querystrings/8c-type-conversions.html.md.erb new file mode 100644 index 0000000..8b2a060 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/93-querystrings/8c-type-conversions.html.md.erb @@ -0,0 +1,31 @@ +--- +title: Type Conversions +--- + +Java rules within a query string require the query processor to perform implicit conversions and promotions under certain cases in order to evaluate expressions that contain different types. + +The query processor performs binary numeric promotion, method invocation conversion, and temporal type conversion. + +## <a id="security__section_A445225717A646478C656DA8AB8334CD" class="no-quick-link"></a>Binary numeric promotion + +Binary numeric promotion widens all operands in a numeric expression to the widest representation used by any of the operands. In each expression, the query processor applies the following rules in order: + +- If either operand is of type double, the other is converted to double. +- If either operand is of type float, the other is converted to float. +- If either operand is of type long, the other is converted to long. +- Both operands are converted to type int. + +The query processor performs binary numeric promotion on the operands of the following operators: + +- comparison operators <, <=, >, and >= +- equality operators = and <> + +This is essentially the same behavior as in Java, except that chars are not considered to be numeric in the native client query language. + +## <a id="security__section_ED0CF17A3119452D8A6FCB95FEEBF3B3" class="no-quick-link"></a>Method invocation conversion + +Method invocation conversion in the query language follows the same rules as Java method invocation conversion, except that the query language uses runtime types instead of compile time types, and handles null arguments differently than in Java. One aspect of using runtime types is that an argument with a null value has no typing information, and so can be matched with any type parameter. When a null argument is used, if the query processor cannot determine the proper method to invoke based on the non-null arguments, it throws an `AmbiguousNameException`. For more information on method invocation in query strings, see [Method Invocation](8a-method-invocation.html#security). + +## <a id="security__section_940BA11A53204B3985B955102CB52681" class="no-quick-link"></a>Temporal type conversion + +The temporal types that the query language supports on the cache server include the Java types `java.util.Date` and `java.sql.Date`, which are treated the same and can be freely compared and used in indexes. When compared with each other, these types are all treated as nanosecond quantities.
http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/94-indexes/indexes-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/94-indexes/indexes-overview.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/94-indexes/indexes-overview.html.md.erb new file mode 100644 index 0000000..a354405 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/94-indexes/indexes-overview.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Creating Indexes +--- + +An index can provide significant performance gains for query execution. You create and maintain indexes on the cache server. + +A query run without an index iterates through every object in the collection on the cache server. If an index is available that matches part or all of the query specification, the query iterates only over the indexed set, and query processing time can be reduced. + +When you create your indexes on the cache server, remember that indexes incur maintenance costs as they must be updated when the indexed data changes. An index that requires many updates and is not used very often may require more system resources than no index at all. Indexes also consume memory. For information on the amount of memory used for indexes, see the system configuration information. + +You can create an index for remote querying declaratively on the cache server in a `cache.xml` file, as shown in this example. + +**Creating an Index on a Cache Server Using a Server XML File** + +``` pre +<region name="portfolios"> + <region-attributes . . . > + <value-constraint>cacheRunner.Portfolio</value-constraint> + </region-attributes> + <index name="myFuncIndex"> + <functional from-clause="/portfolios" expression="status"/> + </index> + <index name="myPrimIndex"> + <primary-key field="id"/> + </index> + <entry> . . . +``` + +For detailed information about working with indexes configured on a cache server, see the section [Working with Indexes](geodeman/developing/query_index/query_index.html). http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/1-remote-query-api-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/1-remote-query-api-overview.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/1-remote-query-api-overview.html.md.erb new file mode 100644 index 0000000..1781d16 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/1-remote-query-api-overview.html.md.erb @@ -0,0 +1,23 @@ +--- +title: Remote Query API +--- + +You use the native client querying API to access all the querying functionality discussed in the previous sections. + +This section gives a general overview of the interfaces and classes that are provided by the Query package API, and the shortcut methods provided in the Region interface. For complete, current information on the classes and interfaces discussed here, see the native client API documentation. + +- **[Creating and Managing Queries](2-create-manage-queries.html)** + + You create queries on the cache server by obtaining a `QueryService` method and manage them through the resulting `Query` object. The `Region` interface has several shortcut query methods. + +- **[Query Result Sets](3-query-result-sets.html)** + +- **[Query Code Samples Returning ResultSet](../96-progexamples/2-query-code-examples-resultset.html)** + + API examples demonstrate methods for returning `ResultSet` for both built-in and user-fined data types. + +- **[Query Code Samples Returning StructSet](../96-progexamples/3-query-code-examples-structset.html)** + + These examples return a `StructSet` for built-in and user-defined data types, `Struct` objects, and collections. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/2-create-manage-queries.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/2-create-manage-queries.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/2-create-manage-queries.html.md.erb new file mode 100644 index 0000000..e685182 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/2-create-manage-queries.html.md.erb @@ -0,0 +1,46 @@ +--- +title: Creating and Managing Queries +--- + +You create queries on the cache server by obtaining a `QueryService` method and manage them through the resulting `Query` object. The `Region` interface has several shortcut query methods. + +The `newQuery` method for the `Query` interface binds a query string. By invoking the `execute` method, the query is submitted to the cache server and returns` SelectResults`, which is either a `ResultSet` or a `StructSet`. + +The `QueryService` method is the entry point to the query package. It is retrieved from the Cache instance through `Cache::getQueryService`. If you are using the Pool API you must obtain the `QueryService` from the pools and not from the cache. + +## <a id="running-native-client-xact__section_41564A36A1DE4EEDA8F3E00992F8D02B" class="no-quick-link"></a>Query + +A `Query` is obtained from a `QueryService` method, which is obtained from the cache. The `Query` interface provides methods for managing the compilation and execution of queries, and for retrieving an existing query string. + +You must obtain a `Query` object for each new query. The following example demonstrates the method used to obtain a new instance of `Query`: + +``` pre +QueryPtr newQuery(const char * querystr); +``` + +## <a id="running-native-client-xact__section_0F92AD1BDB29426BB24CD41F5A0FAB78" class="no-quick-link"></a>Region Shortcut Query Methods + +The `Region` interface has several shortcut query methods. All take a `query` predicate which is used in the `WHERE` clause of a standard query. See [WHERE Clause](../93-querystrings/4-where-clause.html#security) for more information. Each of the following examples also set the query response timeout to 10 seconds to allow sufficient time for the operation to succeed. + +- The `query` method retrieves a collection of values satisfying the query predicate. This call retrieves active portfolios, which in the sample data are the portfolios with keys `111`, `222`, and `333`: + + ``` pre + SelectResultsPtr + results = regionPtr->query("status 'active' "); + ``` + +- The `selectValue` method retrieves one value object. In this call, you request the portfolio with `ID ABC-1` : + + ``` pre + SerializablePtr + port = region->selectValue("ID='ABC-1'"); + ``` + +- The `existsValue` method returns a boolean indicating if any entry exists that satisfies the predicate. This call returns false because there is no entry with the indicated type: + + ``` pre + bool entryExists + = region->existsValue("'type' = 'QQQ' "); + ``` + +For more information about these shortcut query methods, see the Region class description in the native client API documentation. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/3-query-result-sets.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/3-query-result-sets.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/3-query-result-sets.html.md.erb new file mode 100644 index 0000000..379837c --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/95-remotequeryapi/3-query-result-sets.html.md.erb @@ -0,0 +1,10 @@ +--- +title: Query Result Sets +--- + +- **SelectResults**. Executes the query on the cache server and returns the results as either a `ResultSet` or a StructSet. +- **SelectResultsIterator**. Iterates over the items available in a `ResultSet` or `StructSet`. +- **ResultSet**. Obtained after executing a `Query`, which is obtained from a `QueryService` that is obtained from a Cache class. +- **StructSet**. Used when a `SELECT` statement returns more than one set of results. This is accompanied by a `Struct`, which provides the `StructSet` definition and contains its field values. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/2-query-code-examples-resultset.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/2-query-code-examples-resultset.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/2-query-code-examples-resultset.html.md.erb new file mode 100644 index 0000000..e0aeb63 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/2-query-code-examples-resultset.html.md.erb @@ -0,0 +1,68 @@ +--- +title: Query Code Samples Returning ResultSet +--- + +API examples demonstrate methods for returning `ResultSet` for both built-in and user-fined data types. + +**Query Returns a ResultSet for a Built-In Data Type** + +``` pre +QueryServicePtr qrySvcPtr = cachePtr->getQueryService("examplePool"); +QueryPtr query = qrySvcPtr->newQuery("select distinct pkid from /portfolios"); +//specify 10 seconds for the query timeout period +SelectResultsPtr results = query->execute(10); +if (results == NULLPTR) +{ + printf( "\nNo results returned from the server"); +} + +//obtaining a handle to resultset +ResultSetPtr rs(dynamic_cast<ResultSet*> (results.ptr())); +if (rs == NULLPTR) +{ + printf ("\nResultSet is not obtained \n"); return; +} +//iterating through the resultset using row index. +for (int32_t row=0; row < rs->size(); row++) +{ + SerializablePtr ser((*rs)[row]); + CacheableStringPtr str(dynamic_cast<CacheableString*> (ser.ptr())); + if (str != NULLPTR) + { + printf("\n string column contains - %s \n", str->asChar() ); + } +} +``` + +**Query Returns a ResultSet for a User-Defined Data Type** + +``` pre +QueryServicePtr qrySvcPtr = cachePtr->getQueryService("examplePool"); +const char * querystring = "select distinct * from /portfolios"; +QueryPtr query = qrySvcPtr->newQuery(querystring); +//specify 10 seconds for the query timeout period +SelectResultsPtr results = query->execute(10); +if (results == NULLPTR) +{ + printf( "\nNo results returned from the server"); +} +//obtaining a handle to resultset +ResultSetPtr rs(dynamic_cast<ResultSet*> (results.ptr())); +if (rs == NULLPTR) +{ + printf ("\nResultSet is not obtained \n"); return; +} +//iterating through the resultset using iterators. +SelectResultsIterator iter = rs->getIterator(); +while (iter.hasNext()) +{ + SerializablePtr ser = iter.next(); + PortfolioPtr port(dynamic_cast<Portfolio*> (ser.ptr())); + if (port != NULLPTR) + { + printf("\nPortfolio object is - %s \n", port->toString()->asChar() ); + } +} // end of rows +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/3-query-code-examples-structset.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/3-query-code-examples-structset.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/3-query-code-examples-structset.html.md.erb new file mode 100644 index 0000000..d4c2ba3 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/96-progexamples/3-query-code-examples-structset.html.md.erb @@ -0,0 +1,192 @@ +--- +title: Query Code Samples Returning StructSet +--- + +These examples return a `StructSet` for built-in and user-defined data types, `Struct` objects, and collections. + +## Query Returning a StructSet for a Built-In Data Type + +``` pre +QueryServicePtr qrySvcPtr = cachePtr->getQueryService("examplePool"); +const char * querystring = + "SELECT DISTINCT ID, pkid, status, getType FROM /portfolios"; +QueryPtr query = qrySvcPtr->newQuery(querystring); +//specify 10 seconds for the query timeout period +SelectResultsPtr results = query->execute(10); +if (results == NULLPTR) +{ + printf( "\nNo results returned from the server"); +} +//obtaining a handle to resultset +StructSetPtr ss(dynamic_cast<StructSet*> (results.ptr())); +if (ss == NULLPTR) +{ + printf ("\nStructSet is not obtained \n"); + return; +} +//iterating through the resultset using indexes. +for ( int32_t row=0; row < ss->size(); row++) +{ + Struct * siptr = (Struct*) dynamic_cast<Struct*> ( ((*ss)[row]).ptr() ); + if (siptr == NULL) + { + printf("\nstruct is empty \n"); + continue; + + } + //iterate through fields now + for( int32_t field=0; field < siptr->length(); field++) + { + SerializablePtr fieldptr((*siptr)[field]); + if(fieldptr == NULLPTR ) + { + printf("\nnull data received\n"); + } + CacheableStringPtr + str(dynamic_cast<CacheableString*>(fieldptr.ptr())); + if (str == NULLPTR) + { + printf("\n field is of some other type \n"); + } + else + { + printf("\n Data for %s is %s ", siptr->getFieldName(field), str->asChar() ); + } + } //end of columns + } // end of rows +``` + +## Returning Struct Objects + +``` pre +QueryServicePtr qrySvcPtr = cachePtr->getQueryService("examplePool"); +const char * querystring = + "SELECT DISTINCT derivedProjAttrbts, key: p.key FROM " + "/Portfolios.entries p, (SELECT DISTINCT x.ID, myPos.secId FROM " + "/Portfolios x, x.positions.values AS myPos) derivedProjAttrbts WHERE " + "p.value.ID = derivedProjAttrbts.ID AND derivedProjAttrbts.secId = 'IBM'"; +QueryPtr query = qrySvcPtr->newQuery(querystring); +//specify 10 seconds for the query timeout period +SelectResultsPtr results = query->execute(10); +if (results == NULLPTR) +{ + printf( "\nNo results returned from the server"); +} +//obtaining a handle to resultset +StructSetPtr ss(dynamic_cast<StructSet*> (results.ptr())); +if (ss == NULLPTR) +{ + printf ("\nStructSet is not obtained \n"); + return; +} +//iterating through the resultset using indexes. +for (int32_t row=0; row < ss->size(); row++) +{ + Struct * siptr = (Struct*) dynamic_cast<Struct*> ( ((*ss)[row]).ptr() ); + if (siptr == NULL) { printf("\nstruct is empty \n"); } + //iterate through fields now + for (int32_t field=0; field < siptr->length(); field++) { + SerializablePtr fieldptr((*siptr)[field]); + if (fieldptr == NULLPTR ) + { + printf("\nnull data received\n"); + } + CacheableStringPtr + str(dynamic_cast<CacheableString*>(fieldptr.ptr())); + if (str != NULLPTR) { + printf("\n Data for %s is %s ", siptr->getFieldName(field), + str->asChar() ); + } + else + { + StructPtr simpl(dynamic_cast<Struct*> (fieldptr.ptr())); + if (simpl == NULLPTR) + { + printf("\n field is of some other type \n"); continue; + } + printf( "\n struct received %s \n", siptr->getFieldName(field) ); + for (int32_t inner_field=0; inner_field < simpl->length(); inner_field++) + { + SerializablePtr innerfieldptr((*simpl)[inner_field]); + if (innerfieldptr == NULLPTR) + { + printf("\nfield of struct is NULL\n"); + } + CacheableStringPtr str(dynamic_cast<CacheableString*> + (innerfieldptr.ptr())); + if (str != NULLPTR) + { + printf("\n Data for %s is %s ", + simpl->getFieldName(inner_field),str->asChar() ); + } + else + { + printf("\n some other object type inside struct\n"); + } + } + } + } //end of columns + }//end of rows +``` + +## Returning Collections + +``` pre +QueryServicePtr qrySvcPtr = cachePtr->getQueryService("examplePool"); +const char * querystring = "select distinct ID, names from /portfolios"; +QueryPtr query = qrySvcPtr->newQuery(querystring); +SelectResultsPtr results = query->execute(10); +if (results == NULLPTR) { + printf( "\nNo results returned from the server"); +} +//obtain a handle to resultset +StructSetPtr ss(dynamic_cast<StructSet*> (results.ptr())); +if (ss == NULLPTR) { + printf ("\nStructSet is not obtained \n"); + return; +} +//iterate through the resultset using indexes. +for (int32_t row=0; row < ss->size(); row++) +{ + Struct * siptr = dynamic_cast<Struct*> ( ((*ss)[row]).ptr() ); + if (siptr == NULL) + { + printf("\nstruct is empty \n"); + continue; + } + //iterate through fields now + for (int32_t field=0; field < siptr->length(); field++) + { + SerializablePtr fieldptr((*siptr)[field]); + if (fieldptr == NULLPTR) + { + printf("\nnull data received\n"); + } + CacheableStringPtr + str(dynamic_cast<CacheableString*>(fieldptr.ptr())); + if (str != NULLPTR) + { + printf("\n Data for %s is %s ", siptr->getFieldName(field), + str->asChar() ); + } + else + { + CacheableObjectArrayPtr + coa(dynamic_cast<CacheableObjectArray*>(fieldptr.ptr())); + if (coa == NULLPTR) + { + printf("\n field is of some other type\n"); continue; + } + printf( "\n objectArray received %s \n", + siptr->getFieldName(field) ); + for (unsigned arrlen=0; arrlen < (uint32_t)coa->length(); arrlen++) + { + printf("\n Data for %s is %s ",siptr->getFieldName(field), + coa->operator[](arrlen)->toString()->asChar()); + } + } + } //end of columns + }//end of rows +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/remote-querying/remote-querying.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/remote-querying/remote-querying.html.md.erb b/geode-docs/docs/geode-native-docs/remote-querying/remote-querying.html.md.erb new file mode 100644 index 0000000..73ce3ae --- /dev/null +++ b/geode-docs/docs/geode-native-docs/remote-querying/remote-querying.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Remote Querying +--- + +*Remote Querying* documents remote querying from the native client to the Geode cache server. Using examples and procedures, it describes how to use the APIs to run queries against cached data; work with query strings in the native client; create and manage queries; and create indexes. + +- **[Remote Querying Basics](91-quickintro/1-quickintro-overview.html)** + + Use the Geode native client query API to query your cached data stored on a Geode cache server. The query is evaluated and executed on the cache server, and the results are returned to the native client. + +- **[Using Query Strings in the Native Client](93-querystrings/1-querystring-overview.html)** + + To use a query string in a native client, specify the string as a parameter in a `QueryService::newQuery` method, then execute the query using `Query::execute`, passing in the required parameters. + +- **[Accessing Cached Data](92-querylanguage/2-accessingdata.html)** + + Accessing your cached data through the querying service is similar to accessing database contents through SQL queries. How you specify your regions and region contents is particular to the native client. + +- **[Query Language Elements](93-querystrings/8-query-language-elements.html)** + + This section discusses various aspects and tools of the native client query engine. + +- **[Remote Query API](95-remotequeryapi/1-remote-query-api-overview.html)** + + You use the native client querying API to access all the querying functionality discussed in the previous sections. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/LDAPserverauth.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/LDAPserverauth.html.md.erb b/geode-docs/docs/geode-native-docs/security/LDAPserverauth.html.md.erb new file mode 100644 index 0000000..3587c92 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/LDAPserverauth.html.md.erb @@ -0,0 +1,27 @@ +--- +title: Using an LDAP Server for Client Authentication +--- + +An LDAP server can be used by a Geode cache server using the sample LDAP implementation provided in Geode server product. + +See the [Security](../../managing/security/chapter_overview.html#security) to verify authentication credentials for native clients attempting to connect to the Geode servers and sending user name and passwords using the sample UserPassword scheme. + +**Note:** +The user name and password with this sample implementation is sent out in plaintext. For better security, either turn on credential encryption using Diffie-Hellman key exchange, or use a scheme like PKCS. + +When a client initiates a connection to a cache server, the client submits its credentials to the server and the server submits those credentials to the LDAP server. To be authenticated, the credentials for the client need to match one of the valid entries in the LDAP server. The credentials can consist of the entry name and the corresponding password. If the submitted credentials result in a connection to the LDAP server because the credentials match the appropriate LDAP entries, then the client is authenticated and granted a connection to the server. If the server fails to connect to the LDAP server with the supplied credentials then an `AuthenticationFailedException` is sent to the client and its connection with the cache server is closed. + +**Configuration Settings** + +In the `gfcpp.properties` file for the client, specify the `UserPasswordAuthInit` callback, the user name, and the password, like this: + +``` pre +security-client-auth-library=securityImpl +security-client-auth-factory=createUserPasswordAuthInitInstance +security-username=<username> +security-password=<password> +``` + +For server side settings and LDAP server configuration, see [Security](../../managing/security/chapter_overview.html#security). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/PKCS.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/PKCS.html.md.erb b/geode-docs/docs/geode-native-docs/security/PKCS.html.md.erb new file mode 100644 index 0000000..970ca54 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/PKCS.html.md.erb @@ -0,0 +1,28 @@ +--- +title: Using PKCS for Encrypted Authentication +--- + +This section discusses the concepts and configurations for the sample UserPassword and PKCS implementations. Descriptions of their interfaces, classes, and methods are available in the API. + +**Note:** +Native client samples are provided in source form only in the "templates" directory within the product directory. + +With PKCS, clients send encrypted authentication credentials in the form of standard PKCS signatures to a Geode cache server when they connect to the server. The credentials consist of the alias name and digital signature created using the private key that is retrieved from the provided keystore. The server uses a corresponding public key to decrypt the credentials. If decryption is successful then the client is authenticated and it connects to the cache server. For unsuccessful decryption, the server sends an `AuthenticationFailedException` to the client, and the client connection to the cache server is closed. + +When clients require authentication to connect to a cache server, they use the `PKCSAuthInit` class implementing the `AuthInitialize` interface to obtain their credentials. For the PKCS sample provided by Geode, the credentials consist of an alias and an encrypted byte array. The private key is obtained from the PKCS\#12 keystore file. To accomplish this,` PKCSAuthInit` gets the alias retrieved from the `security-alias `property, and the keystore path from the `security-keystorepath` property. `PKCSAuthInit` also gets the password for the password-protected keystore file from the `security-keystorepass` property so the keystore can be opened. + +**Building the securityImpl Library** + +To use the PKCS sample implementation, you need to build OpenSSL and then build the securityImpl library. In the `gfcpp.properties `file for the client, specify the `PKCSAuthInit` callback, the keystore path, the security alias, and the keystore password, like this: + +``` pre +security-client-auth-library=securityImpl +security-client-auth-factory=createPKCSAuthInitInstance +security-keystorepath=<PKCS#12 keystore path> +security-alias=<alias> +security-keystorepass=<keystore password> +``` + +For server side settings, see the description of PKCS sample in [Security](../../managing/security/chapter_overview.html#security). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/authentication-levels.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/authentication-levels.html.md.erb b/geode-docs/docs/geode-native-docs/security/authentication-levels.html.md.erb new file mode 100644 index 0000000..0e37060 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/authentication-levels.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Process and Multiuser Authentication +--- + +Client connections can be authenticated at two levels, process and multiuser. + +- **Process**. Each pool creates a configured minimum number of connections across the server group. The pool accesses the least-loaded server for each cache operation. + + Process-level connections represent the overall client process and are the standard way a client accesses the server cache. + +- **Multi-user**. Each user/pool pair creates a connection to one server and then sticks with it for operations. If the server is unable to respond to a request, the pool selects a new one for the user. + + Typically, application servers or web servers that act as clients to Geode servers make multi-user connections. Multi-user allows a single application or web server process to service a large number of users with varied access permissions. + +By default, server pools use process-level authentication. Enable multi-user authentication by setting a pool's `multi-user-secure-mode-enabled` attribute to `true`. + +<img src="../common/images/security-client-connections.gif" id="security__image_85B98E185AD84C59AC22974A63080559" class="image" /> + +Credentials can be sent in encrypted form using the Diffie-Hellman key exchange algorithm. See [Encrypt Credentials with Diffe-Hellman](overviewencryptcred.html#security) for more information. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/authforcacheserver.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/authforcacheserver.html.md.erb b/geode-docs/docs/geode-native-docs/security/authforcacheserver.html.md.erb new file mode 100644 index 0000000..f878b55 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/authforcacheserver.html.md.erb @@ -0,0 +1,23 @@ +--- +title: Configuring Authentication by the Cache Server +--- + +When the cache server receives client credentials during the handshake operation, the server authenticates the client with the callback configured in the `security-client-authenticator` system property. The handshake succeeds or fails depending on the results of the authentication process. + +Here is an example of how you could configure `security-client-authenticator` in the `gfcpp.properties` file: + +``` pre +security-client-authenticator=templates.security.PKCSAuthenticator.create +``` + +In the preceding configuration sample, `PKCSAuthenticator` is the callback class implementing the `Authenticator` interface and `create` is its factory method. + +The following example shows an implementation of the static `create` method: + +``` pre +public static Authenticator create() { + return new PKCSAuthenticator(); +} +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/caveatregionservice.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/caveatregionservice.html.md.erb b/geode-docs/docs/geode-native-docs/security/caveatregionservice.html.md.erb new file mode 100644 index 0000000..719209f --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/caveatregionservice.html.md.erb @@ -0,0 +1,26 @@ +--- +title: Requirements and Caveats for RegionService +--- + +For each region, you can perform operations through the `Cache` instance or the `RegionService` instances, but not both. + +**Note:** +Through the `Cache` you can create a region that uses a pool configured for multi-user authentication, then access and do work on the region using your `RegionService` instances. + +To use `RegionService`: + +- Configure regions as EMPTY. Depending on your data access requirements, this configuration might affect performance, because the client goes to the server for every `get`. +- If you are running durable CQs through the region services, stop and start the offline event storage for the client as a whole. The server manages one queue for the entire client process, so you need to request the stop and start of durable client queue (CQ) event messaging for the cache as a whole, through the ClientCache instance. If you closed the `RegionService` instances, event processing would stop, but the events from the server would continue, and would be lost. + + Stop with: + + ``` pre + cachePtr->close(true); + ``` + + Start up again in this order: + 1. Create the cache. + 2. Create all region service instances. Initialize CQ listeners. + 3. Call the cache `readyForEvents` method. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/config-clientauthorization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/config-clientauthorization.html.md.erb b/geode-docs/docs/geode-native-docs/security/config-clientauthorization.html.md.erb new file mode 100644 index 0000000..b8811e2 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/config-clientauthorization.html.md.erb @@ -0,0 +1,13 @@ +--- +title: Configuring Client Authorization +--- + +You can configure authorization on a per-client basis for various cache operations such as create, get, put, query invalidations, interest registration, and region destroys. On the server side, the `securityclient-accessor` system property in the serverâs `gemfire.properties` file specifies the authorization callback. + +For example: + +`security-client-accessor=templates.security.XmlAuthorization.create` + +In this system property setting, `XmlAuthorization` is the callback class that implements the `AccessControl` interface. The `XmlAuthorization` sample implementation provided with Geode expects an XML file that defines authorization privileges for the clients. For details of this sample implementation and the `AccessControl` interface, see the [Authorization Example](../../managing/security/authorization_example.html#authorization_example). + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/createsecureconnregionservice.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/createsecureconnregionservice.html.md.erb b/geode-docs/docs/geode-native-docs/security/createsecureconnregionservice.html.md.erb new file mode 100644 index 0000000..38965a6 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/createsecureconnregionservice.html.md.erb @@ -0,0 +1,43 @@ +--- +title: Creating Multiple Secure User Connections +--- + +To create multiple, secure connections to your servers from a single client, so the client can service different user types, you create an authenticated `RegionService` for each user. + +Typically, a Geode client embedded in an application server supports data requests from many users. Each user can be authorized to access a subset of data on the servers. For example, customer users are allowed only to see and update their own orders and shipments. + +The authenticated users all access the same Cache through instances of the `RegionService` interface. See [RegionService](../client-cache/caching-apis.html#caching-apis__section_8F81996678B64BBE94EF352527F7F006). + +To implement multiple user connections in your client cache, create your Cache as usual, with these additions: + +1. Configure your clientâs server pool for multiple secure user authentication. Example: + + ``` pre + <pool name="serverPool" multiuser-authentication="true"> + <locator host="host1" port="44444"/> + </pool> + ``` + + This enables access through the pool for the `RegionService` instances and disables it for the Cache instance. + +2. After you create your cache, for each user, call your Cache instance `createAuthenticatedView` method, providing the userâs particular credentials. These are create method calls for two users: + + ``` pre + PropertiesPtr credentials1 = Properties::create(); + credentials1->insert("security-username", "root1"); + credentials1->insert("security-password", "root1"); + RegionServicePtr userCache1 = cachePtr->createAuthenticatedView(credentials1); + + PropertiesPtr credentials2 = Properties::create(); + credentials2->insert("security-username", "root2"); + credentials2->insert("security-password", "root2"); + RegionServicePtr userCache2 = cachePtr->createAuthenticatedView(credentials2); + ``` + + For each user, do all of your caching and region work through the assigned region service pointer. Use the region service to get your regions, and the query service, if you need that, and then do your work with them. Access to the server cache will be governed by the serverâs configured authorization rules for each individual user. + +3. To close your cache, close the Cache instance. + +- **[Requirements and Caveats for RegionService](caveatregionservice.html)** + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/encrypted-auth.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/encrypted-auth.html.md.erb b/geode-docs/docs/geode-native-docs/security/encrypted-auth.html.md.erb new file mode 100644 index 0000000..c4b9bbb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/encrypted-auth.html.md.erb @@ -0,0 +1,15 @@ +--- +title: Encrypted Authentication +--- + +You can set up encrypted authentication using Diffe-Hellman or the sample PKCS implementation. + +- **[Encrypt Credentials with Diffe-Hellman](overviewencryptcred.html)** + + For secure transmission of sensitive credentials like passwords, encrypt credentials using the Diffie-Hellman key exchange algorithm. With Diffie-Hellman enabled, you can have your client authenticate its servers. + +- **[Using PKCS for Encrypted Authentication](PKCS.html)** + + This section discusses the concepts and configurations for the sample UserPassword and PKCS implementations. Descriptions of their interfaces, classes, and methods are available in the API. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/handling-serv-auth-errors.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/handling-serv-auth-errors.html.md.erb b/geode-docs/docs/geode-native-docs/security/handling-serv-auth-errors.html.md.erb new file mode 100644 index 0000000..244c35a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/handling-serv-auth-errors.html.md.erb @@ -0,0 +1,7 @@ +--- +title: Server Authentication Errors +--- + +An `AuthenticationRequiredException` is thrown when the server is configured with security and the client does not present its credentials while attempting to connect. This can occur if the `securityclient-auth-factory` and `security-client-auth-library` properties are not configured on the client. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/limitations.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/limitations.html.md.erb b/geode-docs/docs/geode-native-docs/security/limitations.html.md.erb new file mode 100644 index 0000000..ee64cf6 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/limitations.html.md.erb @@ -0,0 +1,9 @@ +--- +title: Limitations +--- + +Currently the native client only supports the NULL cipher with mutual authentication for SSL socket communications. + +The keys and keystores need to be in the JKS (Java KeyStore) format for the Geode server and in the clear PEM format for the native client. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/overviewauthentication.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/overviewauthentication.html.md.erb b/geode-docs/docs/geode-native-docs/security/overviewauthentication.html.md.erb new file mode 100644 index 0000000..3fe8421 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/overviewauthentication.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Authentication +--- + +A client is authenticated when it connects, with valid credentials, to a Geode cache server that is configured with the client `Authenticator` callback. + +Once the client is authenticated, the server assigns the client a unique ID and principal, used to authorize operations. The client must trust all cache servers in the server system as it may connect to any one of them. For information on configuring client/server , see [Client/Server Configuration](geodeman/topologies_and_comm/cs_configuration/chapter_overview.html). + +- **[Process and Multiuser Authentication](authentication-levels.html)** + + Client connections can be authenticated at two levels, process and multiuser. + +- **[Configuring Credentials for Authentication](systempropsforauth.html)** + + The native client uses system properties to acquire valid credentials for authentication by the server. You define these properties in the `gfcpp.properties` file, which the native client accesses during startup. + +- **[Configuring Authentication by the Cache Server](authforcacheserver.html)** + + When the cache server receives client credentials during the handshake operation, the server authenticates the client with the callback configured in the `security-client-authenticator` system property. The handshake succeeds or fails depending on the results of the authentication process. + +- **[Server Authentication Errors](handling-serv-auth-errors.html)** + +- **[Creating Multiple Secure User Connections](createsecureconnregionservice.html)** + + To create multiple, secure connections to your servers from a single client, so the client can service different user types, you create an authenticated `RegionService` for each user. + +- **[Using an LDAP Server for Client Authentication](LDAPserverauth.html)** + + An LDAP server can be used by a Geode cache server using the sample LDAP implementation provided in Geode server product. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/overviewclientauthorization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/overviewclientauthorization.html.md.erb b/geode-docs/docs/geode-native-docs/security/overviewclientauthorization.html.md.erb new file mode 100644 index 0000000..a7fbc7a --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/overviewclientauthorization.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Client Authorization +--- + +Using a provided callback that implements the `AccessControl` interface, you can configure each server to authorize some or all cache operations. + +The callback can also modify or even disallow the data being provided by the client in the operation, such as a put or a `putAll` operation. The callback can also register itself as a post-processing filter that is passed operation results like `get`, `getAll`, and `query`. + +- **[Configuring Client Authorization](config-clientauthorization.html)** + + You can configure authorization on a per-client basis for various cache operations such as create, get, put, query invalidations, interest registration, and region destroys. On the server side, the `securityclient-accessor` system property in the serverâs `gemfire.properties` file specifies the authorization callback. + +- **[Post-Operative Authorization](postopauthorization.html)** + + Authorization in the post-operation phase occurs on the server after the operation is complete and before the results are sent to the client. + +- **[Determining Pre- or Post-Operation Authorization](usingoperationcontext.html)** + + The `OperationContext` object that is passed to the `authorizeOperation` method of the callback as the second argument provides an `isPostOperation` method that returns true when the callback is invoked in the post-operation phase. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/overviewencryptcred.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/overviewencryptcred.html.md.erb b/geode-docs/docs/geode-native-docs/security/overviewencryptcred.html.md.erb new file mode 100644 index 0000000..bf41b50 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/overviewencryptcred.html.md.erb @@ -0,0 +1,42 @@ +--- +title: Encrypt Credentials with Diffe-Hellman +--- + +For secure transmission of sensitive credentials like passwords, encrypt credentials using the Diffie-Hellman key exchange algorithm. With Diffie-Hellman enabled, you can have your client authenticate its servers. + +## <a id="security__section_1BB8F13C7ACB44668FF337F59A3BA5AE" class="no-quick-link"></a>Enabling Diffe-Hellman + +Set the `security-client-dhalgo` system property in the `gfcpp.properties` file to the password for the public key file store on the client (the name of a valid symmetric key cipher supported by the JDK). + +Valid `security-client-dhalgo` property values are `DESede`, `AES`, and `Blowfish`, which enable the Diffie-Hellman algorithm with the specified cipher to encrypt the credentials. + +For the `AES` and `Blowfish` algorithms, optionally specify the key size for the `security-client-dhalgo` property. Valid key size settings for the `AES` algorithm are `AES:128`, `AES:192`, and `AES:256`. The colon separates the algorithm name and the key size. For the `Blowfish` algorithm, key sizes from 128 to 448 bits are supported. For example: + +``` pre +security-client-dhalgo=Blowfish:128 +``` + +For `AES` algorithms, you may need Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from Sun or equivalent for your JDK. + +Adding settings for Diffie-Hellman on clients also enables challenge response from server to client in addition to encryption of credentials using the exchanged key to avoid replay attacks from clients to servers. Clients can also enable authentication of servers, with challenge-response from client to server to avoid server-side replay attacks. + +## <a id="security__section_F881653044EC4AB5BE88F673890F2A40" class="no-quick-link"></a>Client Authentication of Server + +With Diffie-Hellman enabled, you can have your client authenticate its servers. + +1. Generate a `.pem` file for each pkcs12 keystore: + + 1. Enter this command from a pkcs12 file or a pkcs keystore: <a id="security__fig_3CAFDE3CB29348A19AF3BE3591AFA2F7"></a> + + ``` pre + user@host: ~> openssl pkcs12 -nokeys -in <keystore/pkcs12 file> -out <outputfilename.pem > + ``` + + 2. Concatenate the generated .pem files into a single .pem file. You will use this file name in the next step. + +2. In the `gfcpp.properties` file: + + 1. Set `security-client-kspath` to the file name of the `.pem` file password for the public key file store on the client. + 2. Set `security-client-kspasswd` to the password for the public key file store on the client. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/overviewsecurity.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/overviewsecurity.html.md.erb b/geode-docs/docs/geode-native-docs/security/overviewsecurity.html.md.erb new file mode 100644 index 0000000..e59d3b5 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/overviewsecurity.html.md.erb @@ -0,0 +1,29 @@ +--- +title: Security +--- + +*Security* describes how to implement the security framework for the Geode native client, including authentication, authorization, ecryption, and SSL client/server communication. + +The security framework authenticates clients that attempt to connect to a Geode cache server, and authorizes client cache operations. You can also configure it for client authentication of servers, and you can plug in your own implementations for authentication and authorization. + +- **[Authentication](overviewauthentication.html)** + + A client is authenticated when it connects, with valid credentials, to a Geode cache server that is configured with the client `Authenticator` callback. + +- **[Encrypted Authentication](encrypted-auth.html)** + + You can set up encrypted authentication using Diffe-Hellman or the sample PKCS implementation. + +- **[Client Authorization](overviewclientauthorization.html)** + + Using a provided callback that implements the `AccessControl` interface, you can configure each server to authorize some or all cache operations. + +- **[Security-Related System Properties (gfcpp.properties)](security-systemprops.html)** + + The table describes the security-related system properties in the `gfcpp.properties` file for native client authentication and authorization. + +- **[SSL Client/Server Communication](overviewsslclientserver.html)** + + This section describes how to configure OpenSSL; implement SSL-based communication between your clients and servers; and run clients and servers with SSL enabled. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/overviewsslclientserver.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/overviewsslclientserver.html.md.erb b/geode-docs/docs/geode-native-docs/security/overviewsslclientserver.html.md.erb new file mode 100644 index 0000000..7af55cb --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/overviewsslclientserver.html.md.erb @@ -0,0 +1,13 @@ +--- +title: SSL Client/Server Communication +--- + +This section describes how to configure OpenSSL, implement SSL-based communication between your clients and servers, and run clients and servers with SSL enabled. + +- **[Set Up OpenSSL](ssl-setup.html)** + +- **[Limitations](limitations.html)** + + Currently the native client only supports the NULL cipher with mutual authentication for SSL socket communications. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/postopauthorization.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/postopauthorization.html.md.erb b/geode-docs/docs/geode-native-docs/security/postopauthorization.html.md.erb new file mode 100644 index 0000000..37d2bc8 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/postopauthorization.html.md.erb @@ -0,0 +1,15 @@ +--- +title: Post-Operative Authorization +--- + +Authorization in the post-operation phase occurs on the server after the operation is complete and before the results are sent to the client. + +The callback can modify the results of certain operations, such as `query`, `get` and `keySet`, or even completely disallow the operation. For example, a post-operation callback for a query operation can filter out sensitive data or data that the client should not receive, or even completely fail the operation. + +The `security-client-accessor-pp` system property in the serverâs `gemfire.properties` file specifies the callback to invoke in the post-operation phase. For example: + +``` pre +security-client-accessor-pp=templates.security.XmlAuthorization.create +``` + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/security-systemprops.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/security-systemprops.html.md.erb b/geode-docs/docs/geode-native-docs/security/security-systemprops.html.md.erb new file mode 100644 index 0000000..115919e --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/security-systemprops.html.md.erb @@ -0,0 +1,68 @@ +--- +title: Security-Related System Properties (gfcpp.properties) +--- + +The table describes the security-related system properties in the `gfcpp.properties` file for native client authentication and authorization. + +<a id="security__section_6DC4C72A2EEB432AA40DE97D438FD1E7"></a><a id="security__table_92A6A66523764199A19BCD66BA189921"></a> + +<table> +<caption><span class="tablecap">Table 1. System Properties for Client Authentication and Authorization</span></caption> +<colgroup> +<col width="50%" /> +<col width="50%" /> +</colgroup> +<tbody> +<tr class="odd"> +<td><code class="ph codeph">security-client-auth-factory</code></td> +<td>Sets the key for the <code class="ph codeph">AuthInitialize</code> factory function.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">security-client-auth-library</code></td> +<td>Registers the path to the <code class="ph codeph">securityImpl.dll</code> library.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">security-client-dhalgo</code></td> +<td>Returns the Diffie-Hellman secret key cipher algorithm.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">security-client-kspath</code></td> +<td>Path to a .pem file, which contains the public certificates for all Geode cache servers to which the client can connect through specified endpoints.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">security-client-kspasswd</code></td> +<td>Password for the public key file store on the client.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">security-keystorepath</code></td> +<td>Path to the public keystore.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">security-alias</code></td> +<td>Alias name for the key in the keystore.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">security-keystorepass</code></td> +<td>Sets the password for the password-protected keystore.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">ssl-enabled</code></td> +<td>Enables SSL-based client/server communication when set to true. When true, the other ssl-* settings are required. The default is false, which causes communication to use plain socket connections.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">ssl-keystore</code></td> +<td>Name of the .PEM keystore file, containing the clientâs private key. Not set by default. Required if <code class="ph codeph">ssl-enabled</code> is true.</td> +</tr> +<tr class="odd"> +<td><code class="ph codeph">ssl-keystore-password</code></td> +<td>Sets the password for the private key PEM file for SSL.</td> +</tr> +<tr class="even"> +<td><code class="ph codeph">ssl-truststore</code></td> +<td><p>Name of the .PEM truststore file, containing the serversâ public certificate. Not set by default. Required if <code class="ph codeph">ssl-enabled</code> is true.</p></td> +</tr> +</tbody> +</table> + + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/ssl-setup.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/ssl-setup.html.md.erb b/geode-docs/docs/geode-native-docs/security/ssl-setup.html.md.erb new file mode 100644 index 0000000..f686a57 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/ssl-setup.html.md.erb @@ -0,0 +1,119 @@ +--- +title: Set Up OpenSSL +--- + +The open-source OpenSSL toolkit provides a full-strength general purpose cryptography library to operate along with the PKCS sample implementation for encrypted authentication of native client credentials. + +Follow these instructions to download and install OpenSSL for your specific operating system. + +The native client requires OpenSSL 1.0.1t or later. For Windows platforms, you can use either the regular or the OpenSSL 1.0.1t "Light" version. + +**Note:** +If you use Cygwin, it is recommended that you do not use the OpenSSL library that comes with Cygwin because it is built with `cygwin.dll` as a dependency. + +## Step 1. Download and install OpenSSL + +### <a id="security__section_5C95C2E4D9244B27BF8FD178E402D993" class="no-quick-link"></a>Linux + +Download the OpenSSL tarball archive from the OpenSSL web site at [http://www.openssl.org/source/](http://www.openssl.org/source/). Copy the downloaded tarball file into `NativeClient_xxxx/templates/security/openssl/Linux` and run `buildit.sh`. + +### <a id="security__section_93651F296C1A4EA5A3FA045EC15FB506" class="no-quick-link"></a>Solaris + +Download the OpenSSL tarball archive from the OpenSSL web site at [http://www.openssl.org/source/](http://www.openssl.org/source/). Copy the downloaded tarball file into `NativeClient_xxxx/templates/security/openssl/SunOS` and run `buildit.sh`. + +### <a id="security__section_68961A8829D44BFB8F542F3317464E5E" class="no-quick-link"></a>Windows + +Download the installer for OpenSSL from [http://www.openssl.org/related/binaries.html](http://www.openssl.org/related/binaries.html). You can also use the OpenSSL "Light" version. + +Use the downloaded OpenSSL installer to install it on Windows. You can usually accept the default installation path (`C:\OpenSSL`). + + +## Step 2. Create keystores + +The Geode server requires keys and keystores in the Java Key Store (JKS) format while the native client requires them in the clear PEM format. Thus you need to be able to generate private/public keypairs in either format and convert between the two using the `keytool` utility and the `openssl` command. + +There are public third party free tools and source code available to download such as the "KeyTool IUI" tool. + + +## Step 3. Configure environment variables + +Configure your system environment to build and run OpenSSL. Follow the environment setup that applies to your operating system. + +### <a id="security__section_6C173D0D8C8343EA92961C954032E2CA" class="no-quick-link"></a>Bourne and Korn shells (sh, ksh, bash) + +<code> +% OPENSSL=_parent-folder-for-openssl-binaries_; export OPENSSL<br /> +% GFCPP=_product-dir_; export GFCPP<br /> +% LD\_LIBRARY\_PATH=$LD\_LIBRARY\_PATH:$GFCPP/lib:$GFCPP/ssl\_libs:$OPENSSL/lib<br /> +% export LD\_LIBRARY\_PATH<br /> +% CLASSPATH=$GEMFIRE/lib/gfSecurityImpl.jar:$CLASSPATH +</code> + +### <a id="security__section_76CF86EDC2234BA6BF7DA6E253C71F61" class="no-quick-link"></a>Windows + +<code> +\> set GFCPP=_product-dir_<br /> +\> set OPENSSL=_path-to-installed-openssl_<br /> +\> set PATH=_path-to-jdk-or-jre_\bin;%GFCPP%\bin;%GFCPP%\ssl\_libs;%OPENSSL%\bin;%PATH%<br /> +\> set CLASSPATH=_path-to-gemfire-installation_\lib\gfSecurityImpl.jar;%CLASSPATH% +</code> + +where <code>_path-to-installed-openssl_</code> is typically `C:\OpenSSL>`. + +## Step 4. Configure SSL properties in gfcpp.properties and gemfire.properties + +Configure SSL properties. + +1. In `gfcpp.properties`, set `ssl-enabled` to true and set `ssl-keystore` and `ssl-truststore` to point to your keystore files. See [Security-Related System Properties (gfcpp.properties)](security-systemprops.html#security) for a description of these properties. +2. On each locator, enable SSL and set the following SSL properties in the locatorâs `gemfire.properties` file: + + ``` pre + ssl-enabled-components=server,locator + ssl-protocols=any + ssl-ciphers=SSL_RSA_WITH_NULL_SHA + ``` + + +## Step 5. Start and stop the client and server + +Before you start and stop the client and server, make sure you configure the native client with the SSL properties as described and with the servers or locators specified as usual. + +Specifically, ensure that: + +- OpenSSL and ACE\_SSL `DLL`s locations are in the right environment variables for your system: `PATH` for Windows, and `LD_LIBRARY_PATH` for Unix. +- You have generated the keys and keystores. +- You have set the system properties. + +For details on stopping and starting locators and cache servers with SSL, see [Starting Up and Shutting Down Your System](geodeman/configuring/running/starting_up_shutting_down.html). + +**Example locator start command** + +Ensure that all required SSL properties are configured in your server's `gfsecurity.properties` file. Then start your locator as follows: + +``` pre +gfsh>start locator --name=my_locator --port=12345 --dir=. \ +--security-properties-file=/path/to/your/gfsecurity.properties +``` + +**Example locator stop command** + +``` pre +gfsh>stop locator --port=12345 \ +--security-properties-file=/path/to/your/gfsecurity.properties +``` + +**Example server start command** + +Again, ensure that all required SSL properties are configured in `gfsecurity.properties`. Then start the server with: + +``` pre +gfsh>start server --name=my_server --locators=hostname[12345] \ +--cache-xml-file=server.xml --log-level=fine \ +--security-properties-file=/path/to/your/gfsecurity.properties +``` + +**Example server stop command** + +``` pre +gfsh>stop server --name=my_server +``` http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/systempropsforauth.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/systempropsforauth.html.md.erb b/geode-docs/docs/geode-native-docs/security/systempropsforauth.html.md.erb new file mode 100644 index 0000000..bbfae31 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/systempropsforauth.html.md.erb @@ -0,0 +1,68 @@ +--- +title: Configuring Credentials for Authentication +--- + +The native client uses system properties to acquire valid credentials for authentication by the server. You define these properties in the `gfcpp.properties` file, which the native client accesses during startup. + +## <a id="security__section_E1835A3B22D44D47A4C9DB54A3590B71" class="no-quick-link"></a>security-client-auth-factory + +System property for the factory function of the class implementing the `AuthInitialize` interface (`IAuthInitialize` in .NET). The .NET clients can load both C++ and .NET implementations. For .NET implementations, this property is the fully qualified name of the static factory function (including the namespace and class). + +## <a id="security__section_15C6689C363B469B947B177E1DE73208" class="no-quick-link"></a>security-client-auth-library + +System property for the library where the factory methods reside. The library is loaded explicitly and the factory functions are invoked dynamically, returning an object of the class implementing the `AuthInitialize` interface. + +Other implementations of the `AuthInitialize` interface may be required to build credentials using properties that are also passed as system properties. These properties also start with the security- prefix. For example, the PKCS implementation requires an alias name and the corresponding keystore path, which are specified as `security-alias` and `security-keystorepath`, respectively. Similarly, `UserPasswordAuthInit `requires a username specified in `security-username`, and the corresponding password is specified in the `security-password` system property. + +The `getCredentials` function for the `AuthInitialize` interface is called to obtain the credentials. All system properties starting with security- are passed to this callback as the first argument to the `getCredentials` function, using this prototype: + +`PropertiesPtr getCredentials(PropertiesPtr& securityprops, const char *server);` + +## <a id="security__section_869DD42F1B23450D9425712EBBD5CB1C" class="no-quick-link"></a>Implementing the Factory Method for Authentication (C++ and .NET) + +The following examples show how to implement the factory method in both C++ and .NET. **C++ Implementation** + +``` pre +LIBEXP AuthInitialize* createPKCSAuthInitInstance() +{ + return new PKCSAuthInit( ); +} +``` + +**.NET Implementation** + +``` pre +public static IAuthInitialize Create() +{ + return new UserPasswordAuthInit(); +} +``` + +Implementations of the factory method are user-provided. Credentials in the form of properties returned by this function are sent by the client to the server for authentication during the clientâs handshake process with the server. + +The Geode native client installation provides sample security implementations in its `templates/security` folder. + +## <a id="security__section_9DEC6B55C76D446FB0821AF3B3922BD6" class="no-quick-link"></a>Acquiring Credentials Programmatically (C++ and .NET) + +This example shows a C++ client connecting with credentials. + +``` pre +PropertiesPtr secProp = Properties::create(); +secProp->insert("security-client-auth-factory", "createPKCSAuthInitInstance"); +secProp->insert("security-client-auth-library", "securityImpl"); +secProp->insert("security-keystorepath", "keystore/gemfire6.keystore"); +secProp->insert("security-alias", "gemfire6"); +secProp->insert("security-zkeystorepass", "gemfire"); +CacheFactoryPtr cacheFactoryPtr = CacheFactory::createCacheFactory(secProp); +``` + +This example shows a .NET client. + +``` pre +Properties secProp = Properties.Create(); +secProp.Insert("security-client-auth-factory", + "GemStone.GemFire.Templates.Cache.Security.UserPasswordAuthInit.Create"); +secProp.Insert("security-client-auth-library", "securityImpl"); +secProp.Insert("security-username"," gemfire6"); +secProp.Insert("security-password"," gemfire6Pass); +``` http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/security/usingoperationcontext.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/security/usingoperationcontext.html.md.erb b/geode-docs/docs/geode-native-docs/security/usingoperationcontext.html.md.erb new file mode 100644 index 0000000..4aa7d8e --- /dev/null +++ b/geode-docs/docs/geode-native-docs/security/usingoperationcontext.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Determining Pre- or Post-Operation Authorization +--- + +The `OperationContext` object that is passed to the `authorizeOperation` method of the callback as the second argument provides an `isPostOperation` method that returns true when the callback is invoked in the post-operation phase. + +For example: + +``` pre +bool authorizeOperation(Region region, OperationContext context) { + if (context.isPostOperation()) { + //it's a post-operation + } else { + //it's a pre-operation + } +} +``` + +If an authorization failure occurs in a pre-operation or post-operation callback on the server, the operation throws a `NotAuthorizedException` on the client. + +For more information, see [Authorization](geodeman/managing/security/authorization_overview.html). http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/setting-properties/attribute-def-priority.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/setting-properties/attribute-def-priority.html.md.erb b/geode-docs/docs/geode-native-docs/setting-properties/attribute-def-priority.html.md.erb new file mode 100644 index 0000000..86fc435 --- /dev/null +++ b/geode-docs/docs/geode-native-docs/setting-properties/attribute-def-priority.html.md.erb @@ -0,0 +1,21 @@ +--- +title: Attribute Definition Priority +--- + +You can specify attributes in different ways, which can cause conflicting definitions. Applications can be configured programmatically, and that has priority over other settings. + +Check your application documentation to see whether this applies in your case. + +- Programmatic configuration +- Properties set at the command line +- <code>_current-working-directory_/gfcpp.properties</code> file +- <code>_product-dir_/defaultSystem/gfcpp.properties</code> file +- Geode defaults + +In case an attribute is defined in more than one place, the first source in this list is used: + +The `gfcpp.properties` files and programmatic configuration are optional. If they are not present, no warnings or errors occur. For details on programmatic configuration through the `Properties` object, see [Defining Properties Programmatically](define-programmatically.html#define-programmatically). + +For information on the cache server configuration, see the *User's Guide*. + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/setting-properties/attributes-gfcpp.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/setting-properties/attributes-gfcpp.html.md.erb b/geode-docs/docs/geode-native-docs/setting-properties/attributes-gfcpp.html.md.erb new file mode 100644 index 0000000..6d464ef --- /dev/null +++ b/geode-docs/docs/geode-native-docs/setting-properties/attributes-gfcpp.html.md.erb @@ -0,0 +1,264 @@ +--- +title: Attributes in gfcpp.properties +--- + +A variety of `gfcpp.properties` settings can be used when a native client connects to a distributed system. + +The following settings can be configured: + +- **[General Properties](attributes-gfcpp.html#attributes-gfcpp__table_21004C9E93294F03BE3469C13EA33262)** Basic information for the process, such as cache creation parameters. +- **[Logging Properties](attributes-gfcpp.html#attributes-gfcpp__table_D42627049FD6432494BDE5170AF1BCCF)** How and where to log system messages. +- **[Statistics Archiving Properties](attributes-gfcpp.html#attributes-gfcpp__table_E1A0EDBA67CD41319E1E5FD0A0BB2723)** How to collect and archive statistics information. +- **[Durable Client Properties](attributes-gfcpp.html#attributes-gfcpp__table_BA6DAF27947B4A9488787E6BDCFC15B9)** Information about the durable clients connected to the system. +- **[Security Properties](attributes-gfcpp.html#attributes-gfcpp__table_B3A8E9EB44A94557A97BB700E2BA1EF1)** Information about various security parameters. + +## <a id="attributes-gfcpp__section_655789BCC46642789F91CDA8AE03CD9B" class="no-quick-link"></a>Attribute Definitions + +The following tables list Geode configuration attributes that can be stored in the `gfcpp.properties` file to be read by a native client. + +For the system properties that relate to high availability, see [Sending Periodic Acknowledgement](../preserving-data/sending-periodic-ack.html#concept_868B8082463846DE9F35BBEA56105C82). For a list of security-related system properties and their descriptions, see the table [System Properties for Client Authentication and Authorization](../security/security-systemprops.html#security__table_92A6A66523764199A19BCD66BA189921). + +<a id="attributes-gfcpp__table_21004C9E93294F03BE3469C13EA33262"></a> + +<table> +<caption><span class="tablecap">Table 1. Attributes in gfcpp.propertiesâGeneral Properties</span></caption> +<colgroup> +<col width="33%" /> +<col width="33%" /> +<col width="34%" /> +</colgroup> +<thead> +<tr class="header"> +<th>gfcpp.properties Attribute</th> +<th>Description</th> +<th>Default</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>appdomain-enabled</td> +<td>If <code class="ph codeph">true</code>, allows native client to work when multiple .NET appdomains are in use.</td> +<td>false</td> +</tr> +<tr class="even"> +<td>cache-xml-file</td> +<td>Name and path of the file whose contents are used by default to initialize a cache if one is created. If not specified, the native client starts with an empty cache, which is populated at runtime. +<p>See <a href="../cache-init-file/chapter-overview.html#chapter-overview">Cache Initialization File</a> for more information on the cache initialization file.</p></td> +<td>no default</td> +</tr> +<tr class="odd"> +<td>heap-lru-delta</td> +<td>When heap LRU is triggered, this is the amount that gets added to the percentage that is above the <code class="ph codeph">heap-lru-limit</code> amount. LRU continues until the memory usage is below <code class="ph codeph">heap-lru-limit</code> minus this percentage. This property is only used if <code class="ph codeph">heap-lru-limit</code> is greater than 0 .</td> +<td>10</td> +</tr> +<tr class="even"> +<td>heap-lru-limit</td> +<td>Maximum amount of memory, in megabytes, used by the cache for all regions. If this limit is exceeded by <code class="ph codeph">heap-lru-delta</code> percent, LRU reduces the memory footprint as necessary. If not specified, or set to 0, memory usage is governed by each region's LRU entries limit, if any.</td> +<td>0</td> +</tr> +<tr class="odd"> +<td>conflate-events</td> +<td>Client side conflation setting, which is sent to the server.</td> +<td>server</td> +</tr> +<tr class="even"> +<td>connect-timeout</td> +<td>Amount of time (in seconds) to wait for a response after a socket connection attempt.</td> +<td>59</td> +</tr> +<tr class="odd"> +<td>connection-pool-size</td> +<td>Number of connections per endpoint</td> +<td>5</td> +</tr> +<tr class="even"> +<td>crash-dump-enabled</td> +<td>Whether crash dump generation for unhandled fatal errors is enabled. True is enabled, false otherwise.</td> +<td>true</td> +</tr> +<tr class="odd"> +<td>disable-chunk-handler-thread</td> +<td>When set to false, each application thread processes its own response. If set to true, the chunk-handler-thread processes the response for each application thread.</td> +<td>false</td> +</tr> +<tr class="even"> +<td>disable-shuffling-of-endpoints</td> +<td>If true, prevents server endpoints that are configured in pools from being shuffled before use.</td> +<td>false</td> +</tr> +<tr class="odd"> +<td>grid-client</td> +<td>If true, the client does not start various internal threads, so that startup and shutdown time is reduced.</td> +<td>false</td> +</tr> +<tr class="even"> +<td>max-fe-threads</td> +<td>Thread pool size for parallel function execution. An example of this is the GetAll operations.</td> +<td>2 * number of CPU cores</td> +</tr> +<tr class="odd"> +<td>max-socket-buffer-size</td> +<td>Maximum size of the socket buffers, in bytes, that the native client will try to set for client-server connections.</td> +<td>65 * 1024</td> +</tr> +<tr class="even"> +<td>notify-ack-interval</td> +<td>Interval, in seconds, in which client sends acknowledgments for subscription notifications.</td> +<td>1</td> +</tr> +<tr class="odd"> +<td>notify-dupcheck-life</td> +<td>Amount of time, in seconds, the client tracks subscription notifications before dropping the duplicates.</td> +<td>300</td> +</tr> +<tr class="even"> +<td>ping-interval</td> +<td>Interval, in seconds, between communication attempts with the server to show the client is alive. Pings are only sent when the <code class="ph codeph">ping-interval</code> elapses between normal client messages. This must be set lower than the server's <code class="ph codeph">maximum-time-between-pings</code>.</td> +<td>10</td> +</tr> +<tr class="odd"> +<td>redundancy-monitor-interval</td> +<td>Interval, in seconds, at which the subscription HA maintenance thread checks for the configured redundancy of subscription servers.</td> +<td>10</td> +</tr> +<tr class="even"> +<td>stacktrace-enabled</td> +<td>If <code class="ph codeph">true</code>, the exception classes capture a stack trace that can be printed with their <code class="ph codeph">printStackTrace</code> function. If false, the function prints a message that the trace is unavailable.</td> +<td>false</td> +</tr> +<tr class="odd"> +<td>tombstone-timeout</td> +<td>Time in milliseconds used to timeout tombstone entries when region consistency checking is enabled. +<div class="note note"> +**Note:** +<p>Do not modify this property unless instructed by technical support.</p> +</div></td> +<td>480000</td> +</tr> +</tbody> +</table> + + +<a id="attributes-gfcpp__table_D42627049FD6432494BDE5170AF1BCCF"></a> + +<table> +<caption><span class="tablecap">Table 2. Attributes in gfcpp.propertiesâLogging Properties</span></caption> +<colgroup> +<col width="34%" /> +<col width="33%" /> +<col width="33%" /> +</colgroup> +<thead> +<tr class="header"> +<th>gfcpp.properties Attribute</th> +<th>Description</th> +<th>Default</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>log-disk-space-limit</td> +<td>Maximum amount of disk space, in megabytes, allowed for all log files, current, and rolled. If set to 0, the space is unlimited.</td> +<td>0</td> +</tr> +<tr class="even"> +<td>log-file</td> +<td>Name and full path of the file where a running client writes log messages. If not specified, logging goes to <code class="ph codeph">stdout</code>.</td> +<td>no default file</td> +</tr> +<tr class="odd"> +<td>log-file-size-limit</td> +<td>Maximum size, in megabytes, of a single log file. Once this limit is exceeded, a new log file is created and the current log file becomes inactive. If set to 0, the file size is unlimited.</td> +<td>0</td> +</tr> +<tr class="even"> +<td>log-level</td> +<td>Controls the types of messages that are written to the application's log. These are the levels, in descending order of severity and the types of message they provide: +<ul> +<li><strong>Error</strong> (highest severity) is a serious failure that will probably prevent program execution.</li> +<li><strong>Warning</strong> is a potential problem in the system.</li> +<li><strong>Info</strong> is an informational message of interest to the end user and system administrator.</li> +<li><strong>Config</strong> is a static configuration message, often used to debug problems with particular configurations.</li> +<li><strong>Fine, Finer, Finest, and Debug</strong> provide tracing information. Only use these with guidance from technical support.</li> +</ul> +<p>Enabling logging at any level enables logging for all higher levels.</p></td> +<td>config</td> +</tr> +</tbody> +</table> + + +<a id="attributes-gfcpp__table_E1A0EDBA67CD41319E1E5FD0A0BB2723"></a> + +<table> +<caption><span class="tablecap">Table 3. Attributes in gfcpp.propertiesâStatistics Archiving Properties</span></caption> +<colgroup> +<col width="33%" /> +<col width="33%" /> +<col width="34%" /> +</colgroup> +<thead> +<tr class="header"> +<th>gfcpp.properties Attribute</th> +<th>Description</th> +<th>Default</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>statistic-sampling-enabled</td> +<td>Controls whether the process creates a statistic archive file.</td> +<td>true</td> +</tr> +<tr class="even"> +<td>statistic-archive-file</td> +<td>Name and full path of the file where a running system member writes archives statistics. If <code class="ph codeph">archive-disk-space-limit</code> is not set, the native client appends the process ID to the configured file name, like <code class="ph codeph">statArchive-PID.gfs</code>. If the space limit is set, the process ID is not appended but each rolled file name is renamed to statArchive-ID.gfs, where ID is the rolled number of the file.</td> +<td>./statArchive.gfs</td> +</tr> +<tr class="odd"> +<td>archive-disk-space-limit</td> +<td>Maximum amount of disk space, in megabytes, allowed for all archive files, current, and rolled. If set to 0, the space is unlimited.</td> +<td>0</td> +</tr> +<tr class="even"> +<td>archive-file-size-limit</td> +<td>Maximum size, in bytes, of a single statistic archive file. Once this limit is exceeded, a new statistic archive file is created and the current archive file becomes inactive. If set to 0, the file size is unlimited.</td> +<td>0</td> +</tr> +<tr class="odd"> +<td>statistic-sample-rate</td> +<td>Rate, in seconds, that statistics are sampled. Operating system statistics are updated only when a sample is taken. If statistic archival is enabled, then these samples are written to the archive. +<p>Lowering the sample rate for statistics reduces system resource use while still providing some statistics for system tuning and failure analysis.</p> +<p>You can view archived statistics with the optional VSD utility.</p></td> +<td>1</td> +</tr> +<tr class="even"> +<td>enable-time-statistics</td> +<td>Enables time-based statistics for the distributed system and caching. For performance reasons, time-based statistics are disabled by default. See <a href="../system-statistics/chapter_overview.html#concept_3BE5237AF2D34371883453E6A9474A79">System Statistics</a>. </td> +<td>false</td> +</tr> +</tbody> +</table> + + +### <a id="attributes-gfcpp__table_BA6DAF27947B4A9488787E6BDCFC15B9" class="no-quick-link"></a>Table 4. Attributes in gfcpp.propertiesâDurable Client Properties + +| gfcpp.properties Attribute | Description | Default | +|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| +| auto-ready-for-events | Whether client subscriptions automatically receive events when declaratively configured via XML. If set to `false`, event startup is not automatic and you need to call the `Cache.ReadyForEvents()` method API after subscriptions for the server to start delivering events. | true | +| durable-client-id | Identifier to specify if you want the client to be durable. | empty | +| durable-timeout | Time, in seconds, a durable client's subscription is maintained when it is not connected to the server before being dropped. | 300 | + + +### <a id="attributes-gfcpp__table_B3A8E9EB44A94557A97BB700E2BA1EF1" class="no-quick-link"></a>Table 5. Attributes in gfcpp.propertiesâSecurity Properties + +| gfcpp.properties Attribute | Description | Default | +|------------------------------|----------------------------------------------------------------------|---------| +| security-client-dhalgo | Diffie-Hellman secret key algorithm. | null | +| security-client-kspath | keystore (.pem file ) path. | null | +| security-client-auth-factory | Factory method for the security `AuthInitialize` module. | empty | +| security-client-auth-library | Path to the client security library for the `AuthInitialize` module. | empty | +| ssl-keystore-password | Keystore password. | null | + + + http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/setting-properties/cache-server-config.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/setting-properties/cache-server-config.html.md.erb b/geode-docs/docs/geode-native-docs/setting-properties/cache-server-config.html.md.erb new file mode 100644 index 0000000..de5de3b --- /dev/null +++ b/geode-docs/docs/geode-native-docs/setting-properties/cache-server-config.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Cache Server Configuration +--- + +You configure the cache server in two files: `gemfire.properties` for server system-level configuration and `cache.xml` for cache-level configuration. + +The configuration of the caches is part of the application development process. See [Cache Initialization File](../cache-init-file/chapter-overview.html#chapter-overview). (The cache-level configuration file is generally referred to as `cache.xml`, but you can use any name.) + +## <a id="cache-server-config__section_FED30097F6C246DE843EBD8B5292D86C" class="no-quick-link"></a>Configuration File Locations + +For the GemFire cache server, the `gemfire.properties` file is usually stored in the current working directory. For more information, see the *User's Guide*. + +For the `cache.xml` cache configuration file, a native client looks for the path specified by the `cache-xml-file` attribute in `gfcpp.properties` (see [Attributes in gfcpp.properties](attributes-gfcpp.html#attributes-gfcpp)). If the `cache.xml` is not found, the process starts with an unconfigured cache. + +## <a id="cache-server-config__section_F47DE4D858B04244956B91360AD8967E" class="no-quick-link"></a>Modifying Attributes Outside the gemfire.properties File + +In addition to the `gemfire.properties file`, you can pass attributes to the cache server on the gfsh command line. These override any settings found in the `gemfire.properties` file when starting the cache server. + +For more information, see *Configuring a Cluster* in the *User's Guide*. http://git-wip-us.apache.org/repos/asf/geode/blob/de0559be/geode-docs/docs/geode-native-docs/setting-properties/chapter-overview.html.md.erb ---------------------------------------------------------------------- diff --git a/geode-docs/docs/geode-native-docs/setting-properties/chapter-overview.html.md.erb b/geode-docs/docs/geode-native-docs/setting-properties/chapter-overview.html.md.erb new file mode 100644 index 0000000..8ac0bbc --- /dev/null +++ b/geode-docs/docs/geode-native-docs/setting-properties/chapter-overview.html.md.erb @@ -0,0 +1,19 @@ +--- +title: Setting System Properties +--- + +*Setting System Properties* describes how to configure Apache Geode native clients and cache servers to participate in a distributed system. + +- **[Configuring the Native Client and Cache Server](config-overview.html)** + + You can configure clients through files and API calls. The servers are configured through command-line input and configuration files. + +- **[Attributes in gfcpp.properties](attributes-gfcpp.html)** + + A variety of `gfcpp.properties` settings can be used when a native client connects to a distributed system. + +- **[gfcpp.properties Example File](../gfcpp.properties/chapter_overview.html)** + + Use the gfcpp.properties file to configure distributed system connections for the Apache Geode native client. + +
