epugh commented on code in PR #5306: URL: https://github.com/apache/solr/pull/5306#discussion_r4539273653
########## solr/solr-ref-guide/modules/getting-started/pages/tutorial-securing-solr.adoc: ########## @@ -0,0 +1,511 @@ += Exercise 7: Securing Solr +// 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. + +This exercise starts a two node Solr cluster, enables HTTPS, assigns separate administration, indexing, and search accounts, and protects ZooKeeper data with access control lists (ACLs). +You will verify HTTPS for both client requests and requests between Solr nodes. +Each step uses the tools included in the Solr distribution, JDK `keytool`, OpenSSL, and `curl`. + +Use a fresh full Solr installation on Unix or macOS, with ports 8983, 8984, and 9983 available. +Run the commands in the same Bash-compatible shell, from the installation directory, using an installation path without spaces. +Do not run these commands against an existing cluster. + +IMPORTANT: This is a local learning exercise with demonstration passwords and a shared self-signed certificate. +Keep the cluster on loopback. +ZooKeeper authentication and ACLs do not encrypt its connection; this exercise leaves ZooKeeper transport on loopback without TLS. +For deployment guidance, see xref:deployment-guide:securing-solr.adoc[], xref:deployment-guide:enabling-ssl.adoc[], and xref:deployment-guide:zookeeper-access-control.adoc[]. + +== Start Two Nodes + +Prepare two isolated Solr homes by copying the distribution's configuration files. +Then start the first node with the ordinary `bin/solr start` command: + +[source,bash] +---- +umask 077 # Makes new files and directories accessible only to your user +export TUTORIAL_HOME="$PWD/tutorial/secure" +mkdir -p "$TUTORIAL_HOME/node1/solr" "$TUTORIAL_HOME/node2/solr" "$TUTORIAL_HOME/tls" +for node in node1 node2; do + cp server/solr/solr.xml "$TUTORIAL_HOME/$node/solr/" + cp server/solr/zoo.cfg "$TUTORIAL_HOME/$node/solr/" +done +cat > "$TUTORIAL_HOME/tls/solr.in.sh" <<EOF +SOLR_ULIMIT_CHECKS=false +SOLR_HOST_BIND=127.0.0.1 +SOLR_HOST_ADVERTISE=127.0.0.1 +SOLR_PID_DIR="$TUTORIAL_HOME" +SOLR_OPTS="-Dsolr.security.allow.paths=$TUTORIAL_HOME" +EOF +export SOLR_INCLUDE="$TUTORIAL_HOME/tls/solr.in.sh" +SOLR_LOGS_DIR="$TUTORIAL_HOME/node1/logs" \ + bin/solr start --solr-home "$TUTORIAL_HOME/node1/solr" +---- + +`SOLR_ULIMIT_CHECKS=false` suppresses resource-limit warnings for this local exercise. + +`SOLR_LOGS_DIR` gives each node its own log directory. + +The first SolrCloud node listens on `localhost:8983` and starts embedded ZooKeeper on `localhost:9983`. +The embedded ZooKeeper is suitable for this exercise; production clusters should use an external ensemble. + +Check that it responds over HTTP, then start the second node: + +[source,bash] +---- +curl --fail 'http://localhost:8983/api/node/health' +SOLR_LOGS_DIR="$TUTORIAL_HOME/node2/logs" \ + bin/solr start -p 8984 --solr-home "$TUTORIAL_HOME/node2/solr" -z localhost:9983 +curl --fail 'http://localhost:8984/api/node/health' +curl --fail --silent --show-error \ + 'http://localhost:8983/api/cluster/nodes' +---- + +Wait for each health request to succeed before proceeding; repeat the corresponding `curl` command if the node is still initializing. +A listening TCP port alone does not mean Solr has finished starting. + +Both nodes use ZooKeeper's root namespace. +The first node runs embedded ZooKeeper; the second joins it with `-z localhost:9983`. +Each home starts with only configuration files and stores its own data. + +The response's `nodes` array must contain two nodes, with ports 8983 and 8984. +If only one node appears, repeat the `curl` command after the second node finishes initializing; continue when both are present. +Both nodes share the first node's ZooKeeper, rather than forming separate clusters. +The working directory holds both nodes' data, certificates, and a private configuration file. +Node logs are under `tutorial/secure/node1/logs` and `tutorial/secure/node2/logs`. + +== Create a Certificate and PKCS12 Stores + +Generate a private key and self-signed certificate directly in a PKCS12 keystore. +The subject alternative names cover both names used in this exercise: + +[source,bash] +---- +keytool -genkeypair -alias solr-ssl -keyalg RSA -keysize 2048 \ + -validity 365 -dname 'CN=localhost' \ + -ext 'SAN=DNS:localhost,IP:127.0.0.1' \ + -storetype PKCS12 -keystore "$TUTORIAL_HOME/tls/solr-ssl.keystore.p12" \ + -storepass SolrRocks -keypass SolrRocks +keytool -exportcert -alias solr-ssl -rfc \ + -keystore "$TUTORIAL_HOME/tls/solr-ssl.keystore.p12" -storetype PKCS12 \ + -storepass SolrRocks -file "$TUTORIAL_HOME/tls/cert.pem" +keytool -importcert -noprompt -alias solr-ssl \ + -file "$TUTORIAL_HOME/tls/cert.pem" \ + -keystore "$TUTORIAL_HOME/tls/solr-ssl.truststore.p12" -storetype PKCS12 \ + -storepass SolrRocks +openssl x509 -in "$TUTORIAL_HOME/tls/cert.pem" -noout -subject -dates -text +---- + +The keystore contains the private key and certificate presented by each server. +The truststore contains the certificate trusted by Solr's outbound HTTPS clients. +The PEM certificate lets `curl` verify the server without disabling certificate checks. +Using the same keystore on both nodes simplifies the exercise; real deployments should manage certificates and private keys separately for each node. + +== Enable HTTPS on Both Nodes + +Write an include file used only for this exercise. +The unquoted heredoc expands the absolute working-directory path now; escaped dollar signs preserve variables for later launches: + +[source,bash] +---- +cat > "$TUTORIAL_HOME/tls/solr.in.sh" <<EOF +SOLR_ULIMIT_CHECKS=false +SOLR_HOST_BIND=127.0.0.1 +SOLR_HOST_ADVERTISE=127.0.0.1 +SOLR_PID_DIR="$TUTORIAL_HOME" +SOLR_OPTS="-Dsolr.security.allow.paths=$TUTORIAL_HOME" +SOLR_SSL_ENABLED=true +SOLR_SSL_KEY_STORE="$TUTORIAL_HOME/tls/solr-ssl.keystore.p12" +SOLR_SSL_KEY_STORE_PASSWORD=SolrRocks +SOLR_SSL_KEY_STORE_TYPE=PKCS12 +SOLR_SSL_TRUST_STORE="$TUTORIAL_HOME/tls/solr-ssl.truststore.p12" +SOLR_SSL_TRUST_STORE_PASSWORD=SolrRocks +SOLR_SSL_TRUST_STORE_TYPE=PKCS12 +SOLR_SSL_CLIENT_TRUST_STORE="\${SOLR_SSL_CLIENT_TRUST_STORE:-$TUTORIAL_HOME/tls/solr-ssl.truststore.p12}" +SOLR_SSL_CLIENT_TRUST_STORE_PASSWORD=SolrRocks +SOLR_SSL_CLIENT_TRUST_STORE_TYPE=PKCS12 +SOLR_SSL_NEED_CLIENT_AUTH=false +SOLR_SSL_WANT_CLIENT_AUTH=false +SOLR_SSL_CHECK_PEER_NAME=true +EOF +chmod 600 "$TUTORIAL_HOME/tls/solr.in.sh" +---- + +The server's truststore and the outbound client's truststore are explicit. +Nodes advertise the IPv4 loopback address `127.0.0.1`; client URLs can also use `localhost`, because the certificate covers both. +Hostname verification remains enabled. +Client certificates are not required; later steps authenticate users with Basic Authentication over HTTPS. + +Before restarting, set the cluster's advertised URL scheme while ZooKeeper is still running. Review Comment: Both addressed. Added an explicit heads-up before the include-file rewrite that a restart is coming. On the urlScheme question: you were right to be suspicious — I removed the 'bin/solr cluster --property urlScheme --value https' step entirely from both the tool and the doc, and verified via a live run of test_secure_example.bats (including the assertions on https:// shard addresses) that it's unnecessary. This lines up with the Solr 10.1 upgrade note that SOLR_SSL_ENABLED now suffices for scheme detection — the property is redundant since then. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
