Github user joeymcallister commented on a diff in the pull request:
https://github.com/apache/geode/pull/583#discussion_r122320206
--- Diff: geode-docs/rest_apps/setup_config.html.md.erb ---
@@ -29,162 +31,233 @@ All Geode REST interface classes and required JAR
files are distributed as a WAR
where _install-dir_ is the server installation directory and _n.n.n_ is a
version number.
-To enable the developer REST API service in Apache Geode, set the
`start-dev-rest-api` Geode property to `true` when starting a data node using
either `gfsh` or the ServerLauncher API. Setting this property to true on a
data node will start up an embedded Jetty server and deploy the REST developer
API WAR file.
+- [Enabling the REST API](#setup_config_enabling_rest)
+- [Starting the REST API Service](#setup_config_starting_rest)
+- [Implementing Authentication for the REST
API](#setup_config_implementing_auth)
+- [Programmatic Startup](#setup_config_implementing_auth)
+
+# <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 data nodes;
you cannot run the service on a locator.
+
+To enable the Developer REST API service on a given server, set the
`start-dev-rest-api` property
+to `true` when starting the data node to start an embedded Jetty server
and deploy the Developer REST
+API WAR file on that node. Use either the `gfsh start server` command or
the ServerLauncher API to enable this property.
-**Note:**
-The REST API service for application development runs only on servers; you
cannot use locators to host the developer Geode REST API services.
+## Enabling the REST API on Multiple Nodes
-You can have multiple REST enabled data nodes in a single distributed
system. Each data node should
+You can configure multiple REST enabled data nodes in a single distributed
system. Each data node should
have a separate host name and unique end point. To ensure that the data
node is reachable on a
-machine with multiple NIC addresses, you can 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).
+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 also 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:
+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
-The following procedure starts up a REST API service-enabled Geode
deployment:
+# <a id="setup_config_starting_rest" class="no-quick-link"></a> Starting
the REST API Service
-1. 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 the `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 up a locator running the [cluster configuration
service](../configuring/cluster_config/gfsh_persist.html) (enabled by default).
For example:
+To start a REST API service-enabled Geode deployment, configure PDX
serialization for your
+cluster, then start the service on one or more server nodes.
- ``` 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:
+## Configure PDX for your cluster
- ``` 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:
+You must configure PDX if either or both of the following conditions
apply:
- ``` 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:
+- 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.
- ``` pre
- gfsh>configure pdx --read-serialized=true --disk-store
- ```
+To configure PDX in your cluster, perform the following steps:
- After you have configured PDX for your caches, then proceed with
starting up your REST-enabled servers and other data nodes.
+1. Start up a locator running the [cluster configuration
service](../configuring/cluster_config/gfsh_persist.html) (enabled by default).
For example:
-2. Start a server node with the Geode property `start-dev-rest-api` set
to `true`.
- Optionally, you can also configure a `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. 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's 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.
+ ``` pre
+ gfsh>start locator --name=locator1
+ ```
- For example:
+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>start server --name=server1 --start-rest-api=true \
- --http-service-port=8080 --http-service-bind-address=localhost
+ gfsh>configure pdx --read-serialized=true
```
- 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:
+ **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>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
+ gfsh>configure pdx --read-serialized=true --disk-store
```
- Note that when started as a JMX Manager, the server will also host the
Pulse web application in the same HTTP service.
+ After you have configured PDX for your caches, then proceed with
starting up your REST-enabled servers and other data nodes.
+
+## Start the REST API Service on One or More Servers
+
+To start the REST API service on a server, start a server node with the
Geode property `start-dev-rest-api` set to `true`.
+Optionally, you can also configure a `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. 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 also need to specify a CLASSPATH to load any functions that need
to be made available to your REST services. For example:
-3. You may also 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 also specify these properties either upon server startup or in the
serverâs gemfire.properties configuration file.
+
+```
+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 Geode 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
- gfsh>start server --name=server1 --start-rest-api=true \
- --http-service-port=8080 --http-service-bind-address=localhost \
- --classpath=/myapps/testfunctions.jar
+ curl -i http://localhost:8080/geode/v1
```
-4. You can also specify these properties either upon server startup or in
the serverâs gemfire.properties configuration file.
+2. Examine the server logs for the following messages:
``` pre
- gfsh>start server --name=serverX --server-port=40405
--cache-xml-file=cache-config.xml \
- --properties-file=gemfire.properties
--classpath=/myapps/testfunctions.jar
+ [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
```
- where gemfire.properties contains:
+3. Open a browser and enter the following URL to browse the
Swagger-enabled REST APIs:
``` pre
- http-service-port=8080
- http-service-bind-address=localhost
- start-dev-rest-api=true
+
http://<http-service-bind-address>:<http-service-port>/geode/docs/index.html
```
-5. Verify that the Geode 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):
+ 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
- curl -i http://localhost:8080/gemfire-api/v1
- ```
+ ``` 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 for the REST API
- 2. Examine the server logs for the following messages:
+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 Geode source,
+`org.apache.geode.examples.security.ExampleSecurityManager`.
- ``` pre
- [info 2014/06/12 14:56:52.431 PDT rest-test
<localhost-startStop-1> tid=0x4d]
- (tid=11 msgId=8) Initializing Spring FrameworkServlet
'gemfire-api'[info 2014/06/12
- 14:56:52.432 PDT rest-test <localhost-startStop-1> tid=0x4d]
(tid=11 msgId=9)
- FrameworkServlet 'gemfire-api': initialization started
- ```
+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.
- 3. Open a browser and enter the following URL to browse the
Swagger-enabled REST APIs:
+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:
- ``` pre
-
http://<http-service-bind-address>:<http-service-port>/gemfire-api/docs/index.html
- ```
+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
+```
- 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 step 2, you would enter:
+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:
- ``` pre
- http://localhost:8080/gemfire-api/docs/index.html
- ```
+```
+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
+```
- 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.
-## Programmatic Startup
+# <a id="setup_config_implementing_auth"
class="no-quick-link"></a>Programmatic Startup
You can also start up and configure Geode REST services programmatically.
For example:
--- End diff --
Change "start up and" to "start and"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
