| --- |
| title: Setup and Configuration |
| --- |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| The <%=vars.product_name_long%> Developer REST interface runs as an embedded HTTP or HTTPS service (Jetty server) within one |
| or more <%=vars.product_name%> servers. |
| |
| # REST API Libraries |
| |
| All <%=vars.product_name%> REST interface classes and required JAR files are distributed as a WAR file with the <%=vars.product_name%> product distribution. You can find the file in the following location: |
| |
| <code> |
| <i>install-dir</i>/tools/Extensions/geode-web-api-<i>n.n.n.</i>war |
| </code> |
| |
| where _install-dir_ is the server installation directory and _n.n.n_ is a version number. |
| |
| Setting a `GEODE_HOME` environment variable with a path to the |
| <%=vars.product_name%> installation directory allows a server launcher |
| to find the WAR file without any changes to the CLASSPATH. |
| |
| # <a id="setup_config_enabling_rest" class="no-quick-link"></a>Enabling the REST API |
| |
| The REST API service for application development runs only on servers; you cannot run the service on a locator. |
| |
| To enable the Developer REST API service on a given server, use the `gfsh start server` command with the `--start-rest-api` option, |
| or set the `start-dev-rest-api` property to `true` for the server via the ServerLauncher API. |
| This starts an embedded Jetty server and deploys the Developer REST API WAR file on that server. |
| |
| ## Enabling the REST API on Multiple Servers |
| |
| You can configure multiple REST-enabled servers in a single cluster. Each server should |
| have a separate host name and unique end point. To ensure that the server is reachable on a |
| machine with multiple NIC addresses, use `http-service-bind-address` to bind an address to |
| the REST API service (as well as the other embedded web services, such as Pulse). |
| |
| You can configure the Developer REST API service to run over HTTPS by enabling SSL for the `http` |
| component in `gemfire.properties` or `gfsecurity.properties`, or on server startup. See |
| [SSL](../managing/security/ssl_overview.html) for details on configuring SSL parameters. These SSL |
| parameters apply to all HTTP services hosted on the configured server, which can include the |
| following: |
| |
| - Developer REST API service |
| - Management REST API service (for remote cluster management) |
| - Pulse monitoring tool |
| |
| # <a id="setup_config_starting_rest" class="no-quick-link"></a> Starting the REST API Service |
| |
| To start a REST API service-enabled <%=vars.product_name%> deployment, configure PDX serialization for your |
| cluster, then start the service on one or more server nodes. |
| |
| ## Configure PDX for your cluster |
| |
| You must configure PDX if either or both of the following conditions apply: |
| |
| - Application peer member caches will access REST-accessible regions (resources) with `Region.get(key)`. |
| - Your deployment has persistent regions that must be available as resources to the REST API. |
| |
| To configure PDX in your cluster, perform the following steps: |
| |
| 1. Start a locator running the [cluster configuration service](../configuring/cluster_config/gfsh_persist.html) (enabled by default). For example: |
| |
| ``` pre |
| gfsh>start locator --name=locator1 |
| ``` |
| |
| 2. If your deployment has application peer member caches (for example, Java clients) that must also access REST-accessible Regions (resources), use the following gfsh command: |
| |
| ``` pre |
| gfsh>configure pdx --read-serialized=true |
| ``` |
| |
| **Note:** |
| You do not need to configure `--read-serialized=true` if no application peer member caches are accessing the REST-accessible regions (resources) in your deployment. |
| |
| 3. If your deployment contains **persistent regions** that must be REST-accessible, use the following gfsh command: |
| |
| ``` pre |
| gfsh>configure pdx --disk-store |
| ``` |
| This command sets `pdx` `persistent` equal to true and sets the disk-store-name to DEFAULT. If desired, specify an existing disk store name as the value for `--disk-store`. |
| |
| 4. If both of the above cases apply to your deployment, then configure PDX with the following single command: |
| |
| ``` pre |
| gfsh>configure pdx --read-serialized=true --disk-store |
| ``` |
| |
| After you have configured PDX for your caches, then proceed with starting your REST-enabled servers and other servers. |
| |
| ## Start the REST API Service on One or More Servers |
| |
| As described above, you can start the REST API service on a server by using `gfsh start server --start-rest-api`, |
| or by setting the <%=vars.product_name%> property `start-dev-rest-api` to `true`. |
| If you wish to start the service on multiple servers, use `http-service-bind-address` and `http-service-port` to |
| identify the cache server and specific port that will host REST services. If you do not specify |
| the `http-service-port`, the default port is 7070, which may collide with other locators and servers. |
| If you do not specify `http-service-bind-address`, the HTTP service will bind to all local addresses by default. |
| |
| **Note:** If your application will be running in a VM (as when running in the cloud, for example), |
| it is good practice to specify `http-service-bind-address` and `http-service-port` so they will be |
| publicly visible. The default values may not be visible outside the VM in which the application is |
| running. |
| |
| For example: |
| |
| ``` |
| gfsh>start server --name=server1 --start-rest-api=true \ |
| --http-service-port=8080 --http-service-bind-address=localhost |
| ``` |
| |
| Any server that hosts data, even a server acting as a JMX manager, can start the Developer REST API service. For example, to start the service on a server that is also a JMX manager, you would run: |
| |
| ``` |
| gfsh>start server --name=server1 --start-rest-api=true \ |
| --http-service-port=8080 --http-service-bind-address=localhost \ |
| --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true |
| ``` |
| |
| Note that when started as a JMX Manager, the server will also host the Pulse web application in the same HTTP service. |
| |
| You may need to specify a CLASSPATH to load any functions that need to be made available to your REST services. For example: |
| |
| ``` |
| gfsh>start server --name=server1 --start-rest-api=true \ |
| --http-service-port=8080 --http-service-bind-address=localhost \ |
| --classpath=/myapps/testfunctions.jar |
| ``` |
| |
| You can specify these properties either upon server startup or in the server’s gemfire.properties configuration file. For example: |
| |
| ``` |
| gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml \ |
| --properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar |
| ``` |
| |
| where gemfire.properties contains: |
| |
| ``` |
| http-service-port=8080 |
| http-service-bind-address=localhost |
| start-dev-rest-api=true |
| ``` |
| |
| ## Verify That The Service is Running |
| |
| Verify that the <%=vars.product_name%> REST API service is up and running. To validate this, you can perform the following checks: |
| |
| 1. Test the list resources endpoint (this step assumes that you have regions defined on your cluster): |
| |
| ``` pre |
| curl -i http://localhost:8080/geode/v1 |
| ``` |
| |
| 2. Examine the server logs for the following messages: |
| |
| ``` pre |
| [info 2017/06/13 13:48:14.090 PDT gfsec-server1 <main> tid=0x1] Initializing Spring FrameworkServlet 'geode-mgmt' |
| [info 2017/06/13 13:48:14.091 PDT gfsec-server1 <main> tid=0x1] FrameworkServlet 'geode-mgmt': initialization started |
| ``` |
| |
| 3. Open a browser and enter the following URL to browse the Swagger-enabled REST APIs: |
| |
| ``` pre |
| http://<http-service-bind-address>:<http-service-port>/geode/docs/index.html |
| ``` |
| |
| where *http-service-bind-address* is the address and *http-service-port* is the port number that you specified when starting the Development REST API service on the server. For example, based on the server started in an earlier example, you would enter: |
| |
| ``` pre |
| http://localhost:8080/geode/docs/index.html |
| ``` |
| |
| If you did not specify these properties upon server startup or in `gemfire.properties`, then use the |
| default of localhost and port 7070. See [Using the Swagger UI to Browse REST |
| APIs](using_swagger.html#concept_rlr_y3c_54) for more information. |
| |
| # <a id="setup_config_implementing_auth" class="no-quick-link"></a>Implementing Authentication |
| |
| To turn on integrated security, start your servers and locators with the security-manager property |
| set in your gemfire.properties file or on the gfsh command-line. |
| The following example uses the sample implementation that is included in the <%=vars.product_name%> source, |
| `org.apache.geode.examples.security.ExampleSecurityManager`. |
| |
| This implementation requires a JSON security configuration file which defines the allowed users and their corresponding |
| permissions. (See the javadocs for `ExampleSecurityManager` for details on how to compose the JSON file.) |
| Place a copy of the JSON security configuration file in the execution directory of each security-enabled member, then |
| specify `--classpath=.` in the start command for each of those members. |
| |
| To start a server using a username and password that are defined in that server's security configuration, include the |
| `--user=username` and `--password=password` options in the server's start command: |
| |
| For example, suppose the JSON config file defines user "super-user" with password "1234567": |
| |
| ``` |
| gfsh>start server --name=server1 --start-rest-api=true \ |
| --http-service-port=8080 --http-service-bind-address=localhost \ |
| --J=-Dgemfire.security-manager=org.apache.geode.examples.security.ExampleSecurityManager \ |
| --classpath=. --user=super-user --password=1234567 |
| ``` |
| |
| To contact the server through the REST interface, you must provide the username and password. Various REST GUI interfaces |
| provide different ways of accomplishing this. The `curl` command offers the `--user` (or `-u`) option for this purpose, |
| where username and password are specified as a colon-separated pair: |
| |
| ``` |
| curl -i --user super-user:1234567 http://localhost:8080/geode/v1 |
| ``` |
| |
| In a simple URL, such as in a browser address bar, the credentials can be given as a prefix to the host name |
| in the form `username:password@`: |
| |
| ``` |
| http://super-user:1234567@localhost:8080/geode/v1 |
| ``` |
| |
| |
| # <a id="setup_config_implementing_auth" class="no-quick-link"></a>Programmatic Startup |
| |
| You can also start and configure <%=vars.product_name%> REST services programmatically. For example: |
| |
| ``` pre |
| import org.apache.geode.distributed.ServerLauncher; |
| |
| public class MyEmbeddedRestServer { |
| |
| public static void main(String[] args){ |
| ServerLauncher serverLauncher = new ServerLauncher.Builder() |
| .set("start-dev-rest-api", "true") |
| .set("http-service-port", "8080") |
| .set("http-service-bind-address", "localhost") |
| .setPdxReadSerialized(true) |
| .build(); |
| |
| serverLauncher.start(); |
| |
| System.out.println("REST server successfully started"); |
| } |
| } |
| ``` |
| You can then verify that the Developer REST API service has been started programmatically by visiting the following URL: |
| |
| ``` pre |
| http://localhost:8080/geode/docs/index.html |
| ``` |
| |
| |