Ref Guide: fix title case for all section headings

This commit is contained in:
Cassandra Targett 2019-05-30 14:09:52 -05:00
parent 61279a2e79
commit df96a0e1b8
6 changed files with 54 additions and 60 deletions

View File

@ -25,7 +25,7 @@ An audit trail (also called audit log) is a security-relevant chronological reco
== Configuration in security.json
Audit logging is configured in `security.json` under the `auditlogging` key.
The example `security.json` below configures synchronous audit logging to Solr default log file.
The example `security.json` below configures synchronous audit logging to Solr default log file.
[source,json]
----
@ -55,7 +55,7 @@ By default any AuditLogger plugin configured will log asynchronously in the back
The defaults are `async: true`, `blockAsync: false`, `queueSize: 4096`. The default for `numThreads` is 2, or if the server has more than 4 CPU-cores then we use CPU-cores/2.
[#audit-event-types]
=== Event types
=== Event Types
These are the event types triggered by the framework:
[%header,format=csv,separator=;]
@ -71,9 +71,9 @@ COMPLETED;Request completed successfully
ERROR;Request was not executed due to an error
|===
By default only the final event types `REJECTED`, `ANONYMOUS_REJECTED`, `UNAUTHORIZED`, `COMPLETED` and `ERROR` are logged. What eventTypes are logged can be configured with the `eventTypes` configuration parameter.
By default only the final event types `REJECTED`, `ANONYMOUS_REJECTED`, `UNAUTHORIZED`, `COMPLETED` and `ERROR` are logged. What eventTypes are logged can be configured with the `eventTypes` configuration parameter.
=== Muting certain events
=== Muting Certain Events
The configuration parameter `muteRules` lets you mute logging for certain events. You may specify multiple rules and combination of rules that will cause muting. You can mute by request type, username, collection name, path, request parameters or IP address. We'll explain through examples:
The below example will mute logging for all `SEARCH` requests as well as all requests made my user `johndoe` or from IP address `192.168.0.10`:
@ -95,7 +95,7 @@ An mute rule may also be a list, in which case all must be true for muting to ha
{
"auditlogging":{
"class": "solr.SolrLogAuditLoggerPlugin"
"muteRules": [
"muteRules": [
"ip:192.168.0.10", <1>
[ "path:/admin/collections", "param:action=LIST" ], <2>
[ "path:/admin/collections", "param:collection=test" ] <3>
@ -105,7 +105,7 @@ An mute rule may also be a list, in which case all must be true for muting to ha
----
<1> The first will mute all events from client IP `192.168.0.10`
<2> The second rule will mute collection admin requests with action=LIST
<2> The second rule will mute collection admin requests with `action=LIST`
<3> The third rule will mute collection admin requests for the collection named `test`
Note how you can mix single string rules with lists of rules that must all match:
@ -117,10 +117,10 @@ Note how you can mix single string rules with lists of rules that must all match
* `user:<userid>` (user by userid)
* `path:</path/to/handler>` (request path relative to `/solr` or for search/update requests relative to collection. Path is prefix matched, i.e. `/admin` will mute any sub path as well.
* `ip:<ip-address>` (IPv4-address)
* `param:<param>=<value>` (request parameter)
* `param:<param>=<value>` (request parameter)
=== Chaining multiple loggers
=== Chaining Multiple Loggers
Using the `MultiDestinationAuditLogger` you can configure multiple audit logger plugins in a chain, to log to multiple destinations, as follows:
[source,json]
@ -141,7 +141,7 @@ Using the `MultiDestinationAuditLogger` you can configure multiple audit logger
== Metrics
AuditLoggerPlugins record metrics about count and timing of log requests, as well as queue size for async loggers. The metrics keys are all recorded on the `SECURITY` category, and each metric name are prefixed with a scope of `/auditlogging` and the class name of the logger, e.g. `SolrLogAuditLoggerPlugin`. The individual metrics are:
* `count` (type: meter. Records number and rate of audit logs done)
* `count` (type: meter. Records number and rate of audit logs done)
* `errors` (type: meter. Records number and rate of errors)
* `lost` (type: meter. Records number and rate of events lost due to queue full and `blockAsync=false`)
* `requestTimes` (type: timer. Records latency and perceniles for logging performance)
@ -151,4 +151,4 @@ AuditLoggerPlugins record metrics about count and timing of log requests, as wel
* `queuedTime` (type: timer. Records the amount of time events waited in queue. Adding this with requestTimes you get total time from event to logging complete)
* `async` (type: gauge. Tells whether this logger is in async mode)
TIP: If you expect a very high request rate and have a slow audit logger plugin, you may see that the `queueSize` and `queuedTime` metrics increase, and in worst case start dropping events and see an increase in `lost` count. In this case you may want to increas the `numThreads` setting.
TIP: If you expect a very high request rate and have a slow audit logger plugin, you may see that the `queueSize` and `queuedTime` metrics increase, and in worst case start dropping events and see an increase in `lost` count. In this case you may want to increas the `numThreads` setting.

View File

@ -204,7 +204,7 @@ The attributes that can be modified are:
See the <<create,CREATE action>> section above for details on these attributes.
[[readonlymode]]
==== Read-only mode
==== Read-Only Mode
Setting the `readOnly` attribute to `true` puts the collection in read-only mode,
in which any index update requests are rejected. Other collection-level actions (eg. adding /
removing / moving replicas) are still available in this mode.
@ -225,7 +225,7 @@ Removing the `readOnly` property or setting it to false enables the
processing of updates and reloads the collection.
[[reindexcollection]]
== REINDEXCOLLECTION: Re-index a Collection
== REINDEXCOLLECTION: Re-Index a Collection
`/admin/collections?action=REINDEXCOLLECTION&name=_name_`

View File

@ -35,8 +35,9 @@ The simplest possible `security.json` for registering the plugin without configu
The plugin will NOT block anonymous traffic in this mode, since the default for `blockUnknown` is false. It is then possible to start configuring the plugin using REST API calls, which is described below.
== Configuration parameters
== Configuration Parameters
//TODO: standard is not to put parameters in tables but use labeled lists instead
[%header,format=csv,separator=;]
|===
Key ; Description ; Default
@ -51,16 +52,16 @@ iss ; Validates that the `iss` (issuer) claim equals this strin
aud ; Validates that the `aud` (audience) claim equals this string ; If `clientId` is configured, require `aud` to match it
requireSub ; Makes `sub` (subject) claim mandatory ; `true`
requireExp ; Makes `exp` (expiry time) claim mandatory ; `true`
algWhitelist ; JSON array with algorithms to accept: `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `none ; Default is to allow all algorithms
algWhitelist ; JSON array with algorithms to accept: `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `none ; Default is to allow all algorithms
jwkCacheDur ; Duration of JWK cache in seconds ; `3600` (1 hour)
principalClaim ; What claim id to pull principal from ; `sub`
claimsMatch ; JSON object of claims (key) that must match a regular expression (value). Example: `{ "foo" : "A|B" }` will require the `foo` claim to be either "A" or "B". ; (none)
adminUiScope ; Define what scope is requested when logging in from Admin UI ; If not defined, the first scope from `scope` parameter is used
authorizationEndpoint; The URL for the Id Provider's authorization endpoint ; Auto configured if `wellKnownUrl` is provided
authorizationEndpoint; The URL for the Id Provider's authorization endpoint ; Auto configured if `wellKnownUrl` is provided
redirectUris ; Valid location(s) for redirect after external authentication. Takes a string or array of strings. Must be the base URL of Solr, e.g. https://solr1.example.com:8983/solr/ and must match the list of redirect URIs registered with the Identity Provider beforehand. ; Defaults to empty list, i.e. any node is assumed to be a valid redirect target.
|===
== More configuration examples
== More Configuration Examples
=== With JWK URL
To start enforcing authentication for all users, requiring a valid JWT in the `Authorization` header, you need to configure the plugin with one or more https://tools.ietf.org/html/rfc7517[JSON Web Key]s (JWK). This is a JSON document containing the key used to sign/encrypt the JWT. It could be a symmetric or asymmetric key. The JWK can either be fetched (and cached) from an external HTTPS endpoint or specified directly in `security.json`. Below is an example of the former:
@ -75,8 +76,8 @@ To start enforcing authentication for all users, requiring a valid JWT in the `A
}
----
=== With Admin UI support
The next example shows configuring using https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect Discovery] with a well-known URI for automatic configuration of many common settings, including ability to use the Admin UI with an OpenID Connect enabled Identity Provider.
=== With Admin UI Support
The next example shows configuring using https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect Discovery] with a well-known URI for automatic configuration of many common settings, including ability to use the Admin UI with an OpenID Connect enabled Identity Provider.
[source,json]
----
@ -89,11 +90,11 @@ The next example shows configuring using https://openid.net/specs/openid-connect
"redirectUri": "https://my.solr.server:8983/solr/"
}
}
----
----
In this case, `jwkUrl`, `iss` and `authorizationEndpoint` will be automatically configured from the fetched configuration.
=== Complex example
=== Complex Example
Let's look at a more complex configuration, this time with a static embedded JWK:
[source,json]
@ -137,7 +138,7 @@ Let's comment on this config:
All properties mentioned above can be set or changed using the Config Edit API. You can thus start with a simple configuration with only `class` configured and then configure the rest using the API.
=== Set a config Property
=== Set a Configuration Property
Set properties for the authentication plugin. Each of the configuration keys in the table above can be used as parameter keys for the `set-property` command.
@ -168,7 +169,7 @@ curl http://localhost:8983/api/cluster/security/authentication -H 'Content-type:
Insert a valid JWT access token in compact serialization format (`xxx.yyy.zzz` above) to authenticate with Solr once the plugin is active.
== Using clients with JWT Auth
== Using Clients with JWT Auth
[#jwt-soljr]
=== SolrJ
@ -182,13 +183,13 @@ To authenticate with Solr when using the cURL utility, supply a valid JWT access
[source,bash]
----
curl -H "Authorization: Bearer xxxxxx.xxxxxx.xxxxxx" http://localhost:8983/solr/admin/info/system
curl -H "Authorization: Bearer xxxxxx.xxxxxx.xxxxxx" http://localhost:8983/solr/admin/info/system
----
=== Admin UI
=== Admin UI
When this plugin is enabled, users will be redirected to a login page in the Admin UI once they attempt to do a restricted action. The page has a button that users will click and be redirected to the Identity Provider's login page. Once authenticated, the user will be redirected back to Solr Admin UI to the last known location. The session will last as long as the JWT token expiry time and is valid for one Solr server only. That means you have to login again when navigating to another Solr node. There is also a logout menu in the left column where user can explicitly log out.
== Using the Solr Control Script with JWT Auth
The control script (`bin/solr`) does not currently support JWT Auth.
The control script (`bin/solr`) does not currently support JWT Auth.

View File

@ -1,5 +1,4 @@
= Solr System Requirements
:page-toc: false
// 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
@ -25,6 +24,7 @@ You can install Solr in any system where a suitable Java Runtime Environment (JR
Solr is tested on several versions of Linux, macOS and Windows.
//TODO: this with the next big section on Java fragments the Java requirements too much. Consider merging sections.
=== Java Requirements
You will need the Java Runtime Environment (JRE) version 1.8 or higher. At a command line, check your Java version like this:
@ -42,61 +42,54 @@ The exact output will vary, but you need to make sure you meet the minimum versi
Some versions of Java VM have bugs that may impact your implementation. To be sure, check the page https://wiki.apache.org/lucene-java/JavaBugs[Lucene Java Bugs].
=== Sources for Java
Java is available from a number of providers. Lucene and Solr regularly test with https://jdk.java.net/[OpenJDK]/Oracle versions of Java. Some are free, others have a cost, some provide security patches and support, others do not. We recommend you read the article https://medium.com/@javachampions/java-is-still-free-2-0-0-6b9aa8d6d244[Java is still free by Java Champions] to help you decide.
Java is available from a number of providers. Lucene and Solr regularly test with https://jdk.java.net/[OpenJDK] nad Oracle versions of Java. Some are free, others have a cost, some provide security patches and support, others do not. We recommend you read the article https://medium.com/@javachampions/java-is-still-free-2-0-0-6b9aa8d6d244[Java is still free by Java Champions] to help you decide.
The Lucene project does not endorse any particular provider of Java.
NOTE: While we reference the Java Development (JDK) on this page, any Java Runtime Environment (JRE) associated with the referenced JDKs is acceptable.
== Java and Lucene/Solr combinations
Each Lucene/Solr release has an extensively tested minimum Java version. For instance the minimum Java version for Solr 8 is Java 8. This section is intended to provide guidance when running Lucene/Solr with a more recent Java version than the minimum specified.
== Java and Lucene/Solr Combinations
=== Executive summary
* OpenJDK/Oracle distribution are tested extensively and will continue to be tested going forward.
** Distributions of Java from other source are not regularly tested by our testing infrastructure, therefore you must test Java from those sources in your environment.
** For the purposes of Lucene and Solr, Oracle's paid version and OpenJDK are are identical.
Each Lucene/Solr release has an extensively tested minimum Java version. For instance the minimum Java version for Solr 8 is Java 8. This section provides guidance when running Lucene/Solr with a more recent Java version than the minimum specified.
* OpenJDK and Oracle Java distributions are tested extensively and will continue to be tested going forward.
** Distributions of Java from other sources are not regularly tested by our testing infrastructure, therefore you must test Java from those sources in your environment.
** For the purposes of Lucene and Solr, Oracle's Java and OpenJDK are identical.
* Upgrading Java is not required with the understanding that no Java bugs will be addressed unless you are using a version of Java that provides LTS.
* Java 8 has been extensively tested both in the field and by automated tests through Solr 8. LTS for Java 8 is provided by some sources, see https://medium.com/@javachampions/java-is-still-free-2-0-0-6b9aa8d6d244[Java is still free].
* Our testing infrastructure continuously tests with the minimum and greater versions of Java for each development branch.
* Java 9 and 10 have no Long Term Support (LTS). For this reason, Java 11 is preferred over 9 or 10 when upgrading Java.
* Java 8 has been extensively tested by both automated tests and users through Solr 8. Long Term Support (LTS) for Java 8 is provided by some sources, see https://medium.com/@javachampions/java-is-still-free-2-0-0-6b9aa8d6d244[Java is still free].
* The project's testing infrastructure continuously tests with the minimum and greater versions of Java for each development branch.
* Java 9 and 10 have no LTS. For this reason, Java 11 is preferred over 9 or 10 when upgrading Java.
* For specific questions the http://lucene.apache.org/solr/community.html#mailing-lists-irc[Solr User's List] is a great resource.
The rest of this page summarizes the Lucene/Solr community's testing experience for Lucene/Solr releases.
=== How we test Solr/Lucene
=== Project Testing of Java-Solr Combinations
Solr and Lucene run a continuous integration model, running automated unit and integration tests using several versions of Java. In addition, some organizations also maintain their own test infrastructure and feed their results back to the community.
Our continuous testing is against the two code lines under active development, Solr 8x and the future Solr 9.0:
* Lucene/Solr 8.x is the current stable branch and will have "point releases", i.e. 8.1, 8.2... until Lucene/Solr 9.0 is released.
** This version is currently tested against Java 8, 9, 10, 11, 12 and (pre-release) 13
* There is also development and testing with the future Lucene/Solr 9.0. There is no planned release date although the cadence has been between 1 and 2 years for major releases.
** This version will require Java 11, so it is currently tested against Java 11, 12 and (pre-release) 13
* Lucene/Solr 7x and earlier are not tested on a continuous basis.
* Lucene/Solr 8.x is the current stable release line and will have "point releases", i.e., 8.1, 8.2, etc. until Lucene/Solr 9.0 is released.
** Solr 8.x is currently tested against Java 8, 9, 10, 11, 12 and (pre-release) 13.
* There is also development and testing with the future Lucene/Solr 9.x release line, which will require Java 11 as a minimum version. This line is currently tested against Java 11, 12 and (pre-release) 13.
* Lucene/Solr 7.x and earlier release lines are not tested on a continuous basis.
=== Released Lucene/Solr and Java Versions
The success rate in our automated tests is similar with all the Java versions tested with the following caveats.
==== Lucene/Solr prior to 7.0
==== Lucene/Solr Prior to 7.0
* Lucene/Solr 7.0 was the first version that successfully passed our tests using Java 9+. Our best guidance is to avoid Java 9 or later for Lucene/Solr 6 or earlier
* Lucene/Solr 7.0 was the first version that successfully passed our tests using Java 9 and higher. You should avoid Java 9 or later for Lucene/Solr 6.x or earlier.
==== Lucene/Solr 7
==== Lucene/Solr 7.x
* Requires Java 8+
* This version had continuous testing with Java 9, 10, 11, 12 and the pre release version of Java 13. Regular testing stopped when Lucene/Solr 8.0 was released.
* Lucene/Solr 7.0 is the first release of Lucene/Solr that successfully completed our testing with Java 9+.
* Requires Java 8 or higher.
* This version had continuous testing with Java 9, 10, 11, 12 and the pre-release version of Java 13. Regular testing stopped when Lucene/Solr 8.0 was released.
* Hadoop with Java 9+ may not work in all situations, test in your environment.
* Kerberos with Java 9+ may not work in all situations, test in your environment.
* Be sure to test with SSL/TLS and/or authorization enabled in your environment if you require either when using Java 9+.
==== Lucene/Solr 8.x
==== Lucene/Solr 8
* Requires Java 8+
* This version has continuous testing with Java 9, 10, 11, 12 and the pre release version of Java 13.
* There were known issues with Kerberos with Java 9+ that will be addressed in Lucene/Solr 8.1, test in your environment.
* Requires Java 8 or higher.
* This version has continuous testing with Java 9, 10, 11, 12 and the pre-release version of Java 13.
* There were known issues with Kerberos with Java 9+ prior to Solr 8.1. If using 8.0, you should test in your environment.
* Be sure to test with SSL/TLS and/or authorization enabled in your environment if you require either when using Java 9+.

View File

@ -448,7 +448,7 @@ Since there is no node that can host a replica for `shard2` without causing a vi
After re-issuing the `SecondCollection` CREATE command, the replica for `shard1` will be placed on "nodeA": it's least loaded, so is tested first, and no policy violation will result from placement there. The `shard2` replica could be placed on any of the 3 nodes, since they're all equally loaded, and the chosen node will remain below its maximum core count after placement. The CREATE command succeeds.
== Testing the autoscaling configuration and suggestions
== Testing Autoscaling Configuration and Suggestions
It's not always easy to predict the impact of autoscaling configuration changes on the
cluster layout. Starting with release 8.1 Solr provides a tool for assessing the impact of
such changes without affecting the state of the target cluster.

View File

@ -132,7 +132,7 @@ An example, to be included under `<config><updateHandler>` in `solrconfig.xml`,
</updateLog>
----
== Other options
== Other Options
In some cases complex updates (such as spatial/shape) may take very long time to complete. In the default
configuration other updates that fall into the same internal version bucket will wait indefinitely and
eventually these outstanding requests may pile up and lead to thread exhaustion and eventually to