[
https://issues.apache.org/jira/browse/GEODE-2854?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16051115#comment-16051115
]
ASF GitHub Bot commented on GEODE-2854:
---------------------------------------
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"
> GEODE REST API Docs Missing Authentication
> ------------------------------------------
>
> Key: GEODE-2854
> URL: https://issues.apache.org/jira/browse/GEODE-2854
> Project: Geode
> Issue Type: Task
> Components: docs
> Reporter: Michael Martell
> Assignee: Dave Barnes
>
> The REST API docs don't document how to do authentication. Looks like HEAD
> params "security-username" and "security-password" are supported but
> undocumented in the REST API.
> There is a comment about REST auth in this link:
> https://geode.apache.org/docs/guide/11/managing/security/implementing_authentication.html
> Also, the docs seem to imply that you pass usr/passwd in the http headers
> such as 'security-username' and 'security-password'. However, it only works
> using HTTP Basic Authentication, which Spring must be translating on the
> server side into the 'security-username' and 'security-password' params.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
