Apache Solr open-source search software
SOLR-18469: Refine Implicit Request Handlers Ref Guide page to show all the information a user needs, and not duplicate anything. (#4928)
Serhiy Bzhezytskyy91cbb6a343e4
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adocindex 43f47a2eb19..13ed2e03f32 100644--- a/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/configuration-files.adoc@@ -105,3 +105,22 @@ Configuration files cannot be edited with this screen, so a text editor of someThis screen is related to the xref:indexing-guide:schema-browser-screen.adoc[], in that they both can display information from the schema.However, the Schema Browser provides a way to drill into the analysis chain and displays linkages between field types, fields, and dynamic field rules.++== Restricting File Access++Both the Files Screen above and the `/admin/file` endpoint it's built on are served by `ShowFileRequestHandler`, which by default exposes every file in `${solr.home}/conf/`.++To hide specific files, list them as `hidden` invariants in `solrconfig.xml` - a bare `*` hides everything else, but patterns like `*.xml` are not supported, only exact filenames:++[source,xml]+----+<requestHandler name="/admin/file" class="solr.admin.ShowFileRequestHandler">+ <lst name="invariants">+ <str name="hidden">synonyms.txt</str>+ <str name="hidden">anotherfile.txt</str>+ <str name="hidden">*</str>+ </lst>+</requestHandler>+----++When fetching a file directly from the endpoint, use the `contentType` parameter to override the returned `Content-Type`, e.g. `solr/admin/file?file=schema.xml&contentType=text/plain`.diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adocindex 6522beb7f10..0aad010ddc9 100644--- a/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc+++ b/solr/solr-ref-guide/modules/configuration-guide/pages/implicit-requesthandlers.adoc@@ -20,12 +20,15 @@Solr ships with many out-of-the-box request handlers, which are called implicit because they do not need to be configured in `solrconfig.xml` before you are able to use them.-These handlers have pre-defined default parameters, known as _paramsets_, which can be modified if necessary.+Each implicit handler ships with a named bundle of default, invariant, and appended parameters - a _paramset_ - equivalent to the `<defaults>`, `<invariants>`, and `<appends>` blocks you'd normally write into a `<requestHandler>` definition in `solrconfig.xml`.+Because implicit handlers have no entry in `solrconfig.xml` to edit directly, their paramset (shown for each handler below, e.g. `_ADMIN_PING` for the Ping handler) is the only way to override their parameters - see <<How to View Implicit Handler Paramsets>> and <<How to Edit Implicit Handler Paramsets>> below.== Available Implicit EndpointsNOTE: All endpoint paths listed below should be placed after Solr's host and port (if a port is used) to construct a URL.+NOTE: V2 paths that start with `api/collections/` exist only in SolrCloud mode. In user-managed mode use the `api/cores/<core>/...` form of the same endpoint.+=== Admin HandlersMany of these handlers are used throughout the Admin UI to show information about Solr.@@ -34,83 +37,173 @@ Many of these handlers are used throughout the Admin UI to show information abouFile:: Return content of files in `${solr.home}/conf/`.This handler must have a collection name in the path to the endpoint.+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/admin/file` |{solr-javadocs}/core/org/apache/solr/handler/admin/ShowFileRequestHandler.html[ShowFileRequestHandler] |`_ADMIN_FILE`-|===+*Documentation*: xref:configuration-files.adoc#restricting-file-access[Restricting File Access]+++[source,bash]+----+solr/<collection>/admin/file+----+++Paramset: `_ADMIN_FILE`-Health:: Report the health of the node, via the `api/node/health` endpoint ({solr-javadocs}/core/org/apache/solr/handler/admin/api/NodeHealth.html[NodeHealth]).-See xref:deployment-guide:healthcheck.adoc[] for details, parameters, and examples.+Health:: Report the health of the node.+++*Documentation*: xref:deployment-guide:healthcheck.adoc[]+++[tabs#health-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/admin/info/health+----+====++V2 API::+++====+[source,bash]+----+api/node/health+----+====+======+++Paramset: noneLogging:: Retrieve and modify registered loggers.+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoints |Class & Javadocs |Paramset-|v1: `solr/admin/info/logging`+[tabs#logging-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/admin/info/logging+----+====-v2: `api/node/logging` |{solr-javadocs}/core/org/apache/solr/handler/admin/LoggingHandler.html[LoggingHandler] |`_ADMIN_LOGGING`-|===+V2 API::+++====+[source,bash]+----+api/node/logging/levels+----+====+======+++The log messages kept in memory come from `solr/admin/info/logging?since=0` in V1 and from `api/node/logging/messages?since=0` in V2.+In the response, `history` is a document list with the messages under `docs` in V1, and a plain array of messages in V2.+++Paramset: noneLuke:: Expose the internal Lucene index.This handler must have a collection name in the path to the endpoint.+*Documentation*: xref:indexing-guide:luke-request-handler.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/admin/luke` |{solr-javadocs}/core/org/apache/solr/handler/admin/LukeRequestHandler.html[LukeRequestHandler] |`_ADMIN_LUKE`-|===+[source,bash]+----+solr/<collection>/admin/luke+----+++Paramset: `_ADMIN_LUKE`-Ping:: Health check.+Ping:: Health check designed for use by a load balancer.This handler must have a collection name in the path to the endpoint.+-CAUTION: `PingRequestHandler` is deprecated and will be removed in a future release. Use the `Health` endpoint below instead.+CAUTION: `PingRequestHandler` is deprecated and will be removed in a future release. Use the `Health` endpoint above instead.+*Documentation*: xref:deployment-guide:ping.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/admin/ping` |{solr-javadocs}/core/org/apache/solr/handler/PingRequestHandler.html[PingRequestHandler] |`_ADMIN_PING`-|===+[source,bash]+----+solr/<collection>/admin/ping+----+++Paramset: `_ADMIN_PING`System Properties:: Return JRE system properties.Secret values are redacted.+*Documentation*: xref:deployment-guide:jvm-settings.adoc#java-properties-screen[Java Properties Screen]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoints |Class & Javadocs |Paramset-|v1: `solr/admin/info/properties`+[tabs#properties-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/admin/info/properties+-----v2: `api/node/properties` |v1: {solr-javadocs}/core/org/apache/solr/handler/admin/PropertiesRequestHandler.html[PropertiesRequestHandler]+To fetch a single property, use a `name` query parameter:-v2: {solr-javadocs}/core/org/apache/solr/handler/admin/api/GetNodeProperties.html[GetNodeProperties] |`_ADMIN_PROPERTIES`-|===+[source,bash]+----+solr/admin/info/properties?name=java.version+----+====++V2 API::+-To fetch a single property, v1 uses a `name` query parameter (`solr/admin/info/properties?name=java.version`) and v2 uses a path segment (`api/node/properties/java.version`).+====+[source,bash]+----+api/node/properties+----++To fetch a single property, use a path segment:++[source,bash]+----+api/node/properties/java.version+----+====+======+++Paramset: noneSegments:: Return info on last commit generation Lucene index segments.+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/admin/segments` |{solr-javadocs}/core/org/apache/solr/handler/admin/SegmentsInfoRequestHandler.html[SegmentsInfoRequestHandler] |`_ADMIN_SEGMENTS`-|===+[tabs#segments-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/admin/segments+----+====++V2 API::+++====+[source,bash]+----+api/cores/<core>/segments+----+====+======+++Paramset: `_ADMIN_SEGMENTS`Core Info:: Return core information.+*Documentation*: xref:core-info-handler.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoints |Class & Javadocs |Paramset-|v1: `solr/<collection>/admin/info`|{solr-javadocs}/core/org/apache/solr/handler/admin/CoreInfoHandler.html[CoreInfoHandler] |-|===+[source,bash]+----+solr/<collection>/admin/info+----+++Paramset: `_ADMIN_CORE`Threads:: Return info on all JVM threads.+@@ -159,33 +252,90 @@ The thread dump is an array of objects, each containing a `"thread"` property:==========+-[cols="2*.",frame=none,grid=cols,options="header"]-|===-|Class & Javadocs |Paramset-|{solr-javadocs}/core/org/apache/solr/handler/admin/ThreadDumpHandler.html[ThreadDumpHandler] |`_ADMIN_THREADS`-|===+Paramset: none=== Analysis Handlers[horizontal]Document Analysis:: Return a breakdown of the analysis process of the given document.+-*Documentation*: https://cwiki.apache.org/confluence/display/solr/AnalysisRequestHandler+Expects a single content stream shaped like this, where every document includes a field serving as the unique key (used to associate each analysis breakdown back to its document):+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/analysis/document` |{solr-javadocs}/core/org/apache/solr/handler/DocumentAnalysisRequestHandler.html[DocumentAnalysisRequestHandler] |`_ANALYSIS_DOCUMENT`-|===+[source,xml]+----+<docs>+ <doc>+ <field name="id">1</field>+ <field name="name">Running Analyzers</field>+ </doc>+ <doc>...</doc>+ ...+</docs>+----+++[source,bash]+----+curl "http://localhost:8983/solr/<collection>/analysis/document" -H "Content-type:text/xml" --data-binary @mydoc.xml+----+++The response breaks each field down by analysis stage, alternating the analyzer/filter class name with the tokens it produced (trimmed here for brevity):+++[source,json]+----+{+ "analysis": {+ "1": {+ "name": {+ "index": {+ "Running Analyzers": [+ "org.apache.lucene.analysis.standard.StandardTokenizer",+ [+ {"text": "Running", "start": 0, "end": 7, "position": 1},+ {"text": "Analyzers", "start": 8, "end": 17, "position": 2}+ ],+ "org.apache.lucene.analysis.core.LowerCaseFilter",+ [+ {"text": "running", "start": 0, "end": 7, "position": 1},+ {"text": "analyzers", "start": 8, "end": 17, "position": 2}+ ]+ ]+ }+ }+ }+ }+}+----+++Also supports query-time analysis via an `analysis.query` or `q` parameter, plus `analysis.showmatch=true` to mark matching field tokens with `"match": true`.+++[source,bash]+----+solr/<collection>/analysis/document+----+++Paramset: `_ANALYSIS_DOCUMENT`Field Analysis:: Return index- and query-time analysis over the given field(s)/field type(s).This handler drives the xref:indexing-guide:analysis-screen.adoc[] in Solr's Admin UI.+-[cols="3*.",frame=none,grid=cols,options="header"]+[cols="2*.",frame=none,grid=cols,options="header"]|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/analysis/field` |{solr-javadocs}/core/org/apache/solr/handler/FieldAnalysisRequestHandler.html[FieldAnalysisRequestHandler] |`_ANALYSIS_FIELD`+|Parameter |Description+|`analysis.fieldname` |Analyze based on this field's type. Accepts a comma-separated list.+|`analysis.fieldtype` |Analyze based on this field type. Accepts a comma-separated list.+|`analysis.fieldvalue` |Text to analyze, mimicking index-time analysis.+|`analysis.query` / `q` |Text to analyze, mimicking query-time analysis. `analysis.query` takes precedence over `q`.+|`analysis.showmatch` |When `true` and query analysis is performed, marks field-value tokens that match the query's tokens.|===+++If neither `analysis.fieldname` nor `analysis.fieldtype` is given, the default search field's analyzer is used; one of `analysis.fieldvalue`, `analysis.query`, or `q` is required.+++[source,bash]+----+solr/<collection>/analysis/field+----+++Paramset: `_ANALYSIS_FIELD`=== Handlers for Configuration@@ -194,42 +344,79 @@ Config API:: Retrieve and modify Solr configuration.+*Documentation*: xref:config-api.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|v1: `solr/<collection>/config`+[tabs#config-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/config+----+====-v2: `api/collections/<collection>/config` |{solr-javadocs}/core/org/apache/solr/handler/SolrConfigHandler.html[SolrConfigHandler] |`_CONFIG`-|===+V2 API::+++====+[source,bash]+----+api/collections/<collection>/config+----+====+======+++Paramset: `_CONFIG`Dump:: Echo the request contents back to the client.+This handler must have a collection name in the path to the endpoint.+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/debug/dump` |{solr-javadocs}/core/org/apache/solr/handler/DumpRequestHandler.html[DumpRequestHandler] |`_DEBUG_DUMP`-|===+[source,bash]+----+solr/<collection>/debug/dump+----+++Paramset: `_DEBUG_DUMP`Replication:: Replicate indexes for SolrCloud recovery and user-managed cluster index distribution.This handler must have a core name in the path to the endpoint.+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<core>/replication` |{solr-javadocs}/core/org/apache/solr/handler/ReplicationHandler.html[ReplicationHandler] |`_REPLICATION`-|===+*Documentation*: xref:deployment-guide:user-managed-index-replication.adoc[]+++[source,bash]+----+solr/<core>/replication+----+++Paramset: `_REPLICATION`Schema API:: Retrieve and modify the Solr schema.+*Documentation*: xref:indexing-guide:schema-api.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|v1: `solr/<collection>/schema`, `solr/<core>/schema`+[tabs#schema-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/schema+solr/<core>/schema+----+====-v2: `api/collections/<collection>/schema`, `api/cores/<core>/schema` |{solr-javadocs}/core/org/apache/solr/handler/SchemaHandler.html[SchemaHandler] |`_SCHEMA`-|===+V2 API::+++====+[source,bash]+----+api/collections/<collection>/schema+api/cores/<core>/schema+----+====+======+++Paramset: `_SCHEMA`=== Query Handlers@@ -238,61 +425,141 @@ Export:: Export full sorted result sets.+*Documentation*: xref:query-guide:exporting-result-sets.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/export` |{solr-javadocs}/core/org/apache/solr/handler/ExportHandler.html[ExportHandler] |`_EXPORT`-|===+[source,bash]+----+solr/<collection>/export+----+++Paramset: `_EXPORT`RealTimeGet:: Low-latency retrieval of the latest version of a document.+*Documentation*: xref:realtime-get.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/get` |{solr-javadocs}/core/org/apache/solr/handler/RealTimeGetHandler.html[RealTimeGetHandler] |`_GET`-|===+[tabs#realtime-get-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/get+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/get+----+====+======+++Paramset: `_GET`Graph Traversal:: Return http://graphml.graphdrawing.org/[GraphML] formatted output from a `gatherNodes` streaming expression.+*Documentation*: xref:query-guide:graph-traversal.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/graph` |{solr-javadocs}/core/org/apache/solr/handler/GraphHandler.html[GraphHandler] |`_ADMIN_GRAPH`-|===+[source,bash]+----+solr/<collection>/graph+----+++Paramset: `_ADMIN_GRAPH`SQL:: SQL query support.++This handler is part of the `sql` xref:solr-modules.adoc[Solr Module], which must be enabled before the endpoint responds.++*Documentation*: xref:query-guide:sql-query.adoc#sql-request-handler[SQL Request Handler]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/sql` |{solr-javadocs}/modules/sql/org/apache/solr/handler/sql/SQLHandler.html[SQLHandler] |`_SQL`-|===+[source,bash]+----+solr/<collection>/sql+----+++Paramset: `_SQL`Streaming Expressions:: Distributed stream processing.+*Documentation*: xref:query-guide:streaming-expressions.adoc#streaming-requests-and-responses[Streaming Requests and Responses]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/stream` |{solr-javadocs}/core/org/apache/solr/handler/StreamHandler.html[StreamHandler] |`_STREAM`-|===+[source,bash]+----+solr/<collection>/stream+----+++Paramset: `_STREAM`Terms:: Return a field's indexed terms and the number of documents containing each term.+*Documentation*: xref:query-guide:terms-component.adoc#using-the-terms-component-in-a-request-handler[Using the Terms Component in a Request Handler]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/terms` |{solr-javadocs}/core/org/apache/solr/handler/component/SearchHandler.html[SearchHandler] |`_TERMS`-|===+[source,bash]+----+solr/<collection>/terms+----+++Paramset: `_TERMS`++Task List:: List the active cancellable tasks, or check whether one task is still active.+This handler must have a collection name in the path to the endpoint.+++*Documentation*: xref:deployment-guide:task-management.adoc[]+++[tabs#task-list-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/tasks/list+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/tasks+----+====+======+++Paramset: `_LIST_TASKS`++Task Cancellation:: Cancel an active task by its ID.+This handler must have a collection name in the path to the endpoint.+++*Documentation*: xref:deployment-guide:task-management.adoc[]+++[tabs#task-cancel-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/tasks/cancel+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/tasks/<task_id>+----+====+======+++Paramset: `_TASK_CANCELLATION`=== Update Handlers@@ -301,41 +568,106 @@ Update:: Add, delete and update indexed documents formatted as SolrXML, CSV, Sol+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/update` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE`-|===+[tabs#update-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/update+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/update+----+====+======+++Paramset: `_UPDATE`CSV Updates:: Add and update CSV-formatted documents.+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc#csv-update-convenience-paths[CSV Update Convenience Paths]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/update/csv` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_CSV`-|===+[tabs#csv-update-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/update/csv+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/update/csv+----+====+======+++Paramset: `_UPDATE_CSV`JSON Updates:: Add, delete and update SolrJSON-formatted documents.+*Documentation*: xref:indexing-guide:indexing-with-update-handlers.adoc#json-update-convenience-paths[JSON Update Convenience Paths]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/update/json` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_JSON`-|===+[tabs#json-update-endpoint]+======+V1 API::+++====+[source,bash]+----+solr/<collection>/update/json+----+====++V2 API::+++====+[source,bash]+----+api/collections/<collection>/update/json+----+====+======+++Paramset: `_UPDATE_JSON`Custom JSON Updates:: Add and update custom JSON-formatted documents.+*Documentation*: xref:indexing-guide:transforming-and-indexing-custom-json.adoc[]+-[cols="3*.",frame=none,grid=cols,options="header"]-|===-|API Endpoint |Class & Javadocs |Paramset-|`solr/<collection>/update/json/docs` |{solr-javadocs}/core/org/apache/solr/handler/UpdateRequestHandler.html[UpdateRequestHandler] |`_UPDATE_JSON_DOCS`-|===+Both the v2 `/update` and `/update/json` endpoints above are internally rewritten to this path, which is why it has no distinct v2 endpoint of its own.+++[source,bash]+----+solr/<collection>/update/json/docs+----+++Paramset: `_UPDATE_JSON_DOCS`++CBOR Updates:: Add and update CBOR-formatted documents.+++*Documentation*: xref:indexing-guide:indexing-with-cbor.adoc[]+++[source,bash]+----+solr/<collection>/update/cbor+----+++Paramset: `_UPDATE_CBOR`== How to View Implicit Handler Paramsets@@ -402,7 +734,8 @@ The response will look similar to:== How to Edit Implicit Handler Paramsets-Because implicit request handlers are not present in `solrconfig.xml`, configuration of their associated `default`, `invariant` and `appends` parameters may be edited via the xref:request-parameters-api.adoc[] using the paramset listed in the above table.+Because implicit request handlers are not present in `solrconfig.xml`, configuration of their associated `default`, `invariant` and `appends` parameters may be edited via the xref:request-parameters-api.adoc[] using the Paramset listed in each handler's entry above.+See xref:request-parameters-api.adoc#the-useparams-parameter[The useParams Parameter] to override a paramset at request time instead of editing it.However, other parameters, including SearchHandler components, may not be modified.The invariants and appends specified in the implicit configuration cannot be overridden.diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adocindex 9f1a062feb6..b3cce8cfd39 100644--- a/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc@@ -177,8 +177,26 @@ The API provides an endpoint with specific commands to set user details or delet=== API Entry Point-* v1: `\http://localhost:8983/solr/admin/authentication`-* v2: `\http://localhost:8983/api/cluster/security/authentication`+[tabs#authentication-entry-point]+======+V1 API::+++====+[source,bash]+----+http://localhost:8983/solr/admin/authentication+----+====++V2 API::+++====+[source,bash]+----+http://localhost:8983/api/cluster/security/authentication+----+====+======This endpoint is not collection-specific, so users are created for the entire Solr cluster.If users need to be restricted to a specific collection, that can be done with the authorization rules.diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adocindex 558dddac292..5edd0ae4efc 100644--- a/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/ping.adoc@@ -30,6 +30,41 @@ image::ping/ping.png[image,width=171,height=195]The search executed by a Ping is configured with the xref:configuration-guide:request-parameters-api.adoc[].See xref:configuration-guide:implicit-requesthandlers.adoc[] for the paramset to use for the `/admin/ping` endpoint.+== Configuring Ping++`PingRequestHandler` delegates to a configured query, set via `qt`/`q` invariants, and responds `OK` if that query succeeds, or with the delegated handler's error if it doesn't:++[source,xml]+----+<requestHandler name="/admin/ping" class="solr.PingRequestHandler">+ <lst name="invariants">+ <str name="qt">/search</str> <!-- handler to delegate to -->+ <str name="q">some test query</str>+ </lst>+</requestHandler>+----++You can also configure a `healthcheckFile` to enable or disable the handler independent of whether Solr itself is healthy - useful for pulling a node out of load balancer rotation for maintenance:++[source,xml]+----+<requestHandler name="/admin/ping" class="solr.PingRequestHandler">+ <!-- relative paths are resolved against the data dir -->+ <str name="healthcheckFile">server-enabled.txt</str>+ <lst name="invariants">+ <str name="qt">/search</str>+ </lst>+</requestHandler>+----++With `healthcheckFile` configured, an `action` request parameter controls it:++* `action=enable` - creates the health check file if it doesn't already exist+* `action=disable` - deletes the health check file if it exists+* `action=status` - reports `enabled`, `disabled`, or `not_configured`++If the file is configured but missing, Ping returns an HTTP error even if the server is otherwise healthy.+The Ping option doesn't open a page, but the status of the request can be seen on the core overview page shown when clicking on a collection name.The length of time the request has taken is displayed next to the Ping option, in milliseconds.