- Elasticsearch Guide: other versions:
- What’s new in 8.17
- Elasticsearch basics
- Quick starts
- Set up Elasticsearch
- Run Elasticsearch locally
- Installing Elasticsearch
- Configuring Elasticsearch
- Important Elasticsearch configuration
- Secure settings
- Auditing settings
- Circuit breaker settings
- Cluster-level shard allocation and routing settings
- Miscellaneous cluster settings
- Cross-cluster replication settings
- Discovery and cluster formation settings
- Field data cache settings
- Health Diagnostic settings
- Index lifecycle management settings
- Data stream lifecycle settings
- Index management settings
- Index recovery settings
- Indexing buffer settings
- License settings
- Local gateway settings
- Logging
- Machine learning settings
- Inference settings
- Monitoring settings
- Nodes
- Networking
- Node query cache settings
- Search settings
- Security settings
- Shard request cache settings
- Snapshot and restore settings
- Transforms settings
- Thread pools
- Watcher settings
- Advanced configuration
- Important system configuration
- Bootstrap Checks
- Heap size check
- File descriptor check
- Memory lock check
- Maximum number of threads check
- Max file size check
- Maximum size virtual memory check
- Maximum map count check
- Client JVM check
- Use serial collector check
- System call filter check
- OnError and OnOutOfMemoryError checks
- Early-access check
- All permission check
- Discovery configuration check
- Bootstrap Checks for X-Pack
- Starting Elasticsearch
- Stopping Elasticsearch
- Discovery and cluster formation
- Add and remove nodes in your cluster
- Full-cluster restart and rolling restart
- Remote clusters
- Plugins
- Upgrade Elasticsearch
- Index modules
- Mapping
- Dynamic mapping
- Explicit mapping
- Runtime fields
- Field data types
- Aggregate metric
- Alias
- Arrays
- Binary
- Boolean
- Completion
- Date
- Date nanoseconds
- Dense vector
- Flattened
- Geopoint
- Geoshape
- Histogram
- IP
- Join
- Keyword
- Nested
- Numeric
- Object
- Pass-through object
- Percolator
- Point
- Range
- Rank feature
- Rank features
- Search-as-you-type
- Semantic text
- Shape
- Sparse vector
- Text
- Token count
- Unsigned long
- Version
- Metadata fields
- Mapping parameters
analyzer
coerce
copy_to
doc_values
dynamic
eager_global_ordinals
enabled
format
ignore_above
index.mapping.ignore_above
ignore_malformed
index
index_options
index_phrases
index_prefixes
meta
fields
normalizer
norms
null_value
position_increment_gap
properties
search_analyzer
similarity
store
subobjects
term_vector
- Mapping limit settings
- Removal of mapping types
- Text analysis
- Overview
- Concepts
- Configure text analysis
- Built-in analyzer reference
- Tokenizer reference
- Token filter reference
- Apostrophe
- ASCII folding
- CJK bigram
- CJK width
- Classic
- Common grams
- Conditional
- Decimal digit
- Delimited payload
- Dictionary decompounder
- Edge n-gram
- Elision
- Fingerprint
- Flatten graph
- Hunspell
- Hyphenation decompounder
- Keep types
- Keep words
- Keyword marker
- Keyword repeat
- KStem
- Length
- Limit token count
- Lowercase
- MinHash
- Multiplexer
- N-gram
- Normalization
- Pattern capture
- Pattern replace
- Phonetic
- Porter stem
- Predicate script
- Remove duplicates
- Reverse
- Shingle
- Snowball
- Stemmer
- Stemmer override
- Stop
- Synonym
- Synonym graph
- Trim
- Truncate
- Unique
- Uppercase
- Word delimiter
- Word delimiter graph
- Character filters reference
- Normalizers
- Index templates
- Data streams
- Ingest pipelines
- Example: Parse logs
- Enrich your data
- Processor reference
- Append
- Attachment
- Bytes
- Circle
- Community ID
- Convert
- CSV
- Date
- Date index name
- Dissect
- Dot expander
- Drop
- Enrich
- Fail
- Fingerprint
- Foreach
- Geo-grid
- GeoIP
- Grok
- Gsub
- HTML strip
- Inference
- IP Location
- Join
- JSON
- KV
- Lowercase
- Network direction
- Pipeline
- Redact
- Registered domain
- Remove
- Rename
- Reroute
- Script
- Set
- Set security user
- Sort
- Split
- Terminate
- Trim
- Uppercase
- URL decode
- URI parts
- User agent
- Ingest pipelines in Search
- Aliases
- Search your data
- Re-ranking
- Query DSL
- Aggregations
- Bucket aggregations
- Adjacency matrix
- Auto-interval date histogram
- Categorize text
- Children
- Composite
- Date histogram
- Date range
- Diversified sampler
- Filter
- Filters
- Frequent item sets
- Geo-distance
- Geohash grid
- Geohex grid
- Geotile grid
- Global
- Histogram
- IP prefix
- IP range
- Missing
- Multi Terms
- Nested
- Parent
- Random sampler
- Range
- Rare terms
- Reverse nested
- Sampler
- Significant terms
- Significant text
- Terms
- Time series
- Variable width histogram
- Subtleties of bucketing range fields
- Metrics aggregations
- Pipeline aggregations
- Average bucket
- Bucket script
- Bucket count K-S test
- Bucket correlation
- Bucket selector
- Bucket sort
- Change point
- Cumulative cardinality
- Cumulative sum
- Derivative
- Extended stats bucket
- Inference bucket
- Max bucket
- Min bucket
- Moving function
- Moving percentiles
- Normalize
- Percentiles bucket
- Serial differencing
- Stats bucket
- Sum bucket
- Bucket aggregations
- Geospatial analysis
- Connectors
- EQL
- ES|QL
- SQL
- Overview
- Getting Started with SQL
- Conventions and Terminology
- Security
- SQL REST API
- SQL Translate API
- SQL CLI
- SQL JDBC
- SQL ODBC
- SQL Client Applications
- SQL Language
- Functions and Operators
- Comparison Operators
- Logical Operators
- Math Operators
- Cast Operators
- LIKE and RLIKE Operators
- Aggregate Functions
- Grouping Functions
- Date/Time and Interval Functions and Operators
- Full-Text Search Functions
- Mathematical Functions
- String Functions
- Type Conversion Functions
- Geo Functions
- Conditional Functions And Expressions
- System Functions
- Reserved keywords
- SQL Limitations
- Scripting
- Data management
- ILM: Manage the index lifecycle
- Tutorial: Customize built-in policies
- Tutorial: Automate rollover
- Index management in Kibana
- Overview
- Concepts
- Index lifecycle actions
- Configure a lifecycle policy
- Migrate index allocation filters to node roles
- Troubleshooting index lifecycle management errors
- Start and stop index lifecycle management
- Manage existing indices
- Skip rollover
- Restore a managed data stream or index
- Data tiers
- Autoscaling
- Monitor a cluster
- Roll up or transform your data
- Set up a cluster for high availability
- Snapshot and restore
- Secure the Elastic Stack
- Elasticsearch security principles
- Start the Elastic Stack with security enabled automatically
- Manually configure security
- Updating node security certificates
- User authentication
- Built-in users
- Service accounts
- Internal users
- Token-based authentication services
- User profiles
- Realms
- Realm chains
- Security domains
- Active Directory user authentication
- File-based user authentication
- LDAP user authentication
- Native user authentication
- OpenID Connect authentication
- PKI user authentication
- SAML authentication
- Kerberos authentication
- JWT authentication
- Integrating with other authentication systems
- Enabling anonymous access
- Looking up users without authentication
- Controlling the user cache
- Configuring SAML single-sign-on on the Elastic Stack
- Configuring single sign-on to the Elastic Stack using OpenID Connect
- User authorization
- Built-in roles
- Defining roles
- Role restriction
- Security privileges
- Document level security
- Field level security
- Granting privileges for data streams and aliases
- Mapping users and groups to roles
- Setting up field and document level security
- Submitting requests on behalf of other users
- Configuring authorization delegation
- Customizing roles and authorization
- Enable audit logging
- Restricting connections with IP filtering
- Securing clients and integrations
- Operator privileges
- Troubleshooting
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Common Kerberos exceptions
- Common SAML issues
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- Failures due to relocation of the configuration files
- Limitations
- Watcher
- Cross-cluster replication
- Data store architecture
- REST APIs
- API conventions
- Common options
- REST API compatibility
- Autoscaling APIs
- Behavioral Analytics APIs
- Compact and aligned text (CAT) APIs
- cat aliases
- cat allocation
- cat anomaly detectors
- cat component templates
- cat count
- cat data frame analytics
- cat datafeeds
- cat fielddata
- cat health
- cat indices
- cat master
- cat nodeattrs
- cat nodes
- cat pending tasks
- cat plugins
- cat recovery
- cat repositories
- cat segments
- cat shards
- cat snapshots
- cat task management
- cat templates
- cat thread pool
- cat trained model
- cat transforms
- Cluster APIs
- Cluster allocation explain
- Cluster get settings
- Cluster health
- Health
- Cluster reroute
- Cluster state
- Cluster stats
- Cluster update settings
- Nodes feature usage
- Nodes hot threads
- Nodes info
- Prevalidate node removal
- Nodes reload secure settings
- Nodes stats
- Cluster Info
- Pending cluster tasks
- Remote cluster info
- Task management
- Voting configuration exclusions
- Create or update desired nodes
- Get desired nodes
- Delete desired nodes
- Get desired balance
- Reset desired balance
- Cross-cluster replication APIs
- Connector APIs
- Create connector
- Delete connector
- Get connector
- List connectors
- Update connector API key id
- Update connector configuration
- Update connector index name
- Update connector features
- Update connector filtering
- Update connector name and description
- Update connector pipeline
- Update connector scheduling
- Update connector service type
- Create connector sync job
- Cancel connector sync job
- Delete connector sync job
- Get connector sync job
- List connector sync jobs
- Check in a connector
- Update connector error
- Update connector last sync stats
- Update connector status
- Check in connector sync job
- Claim connector sync job
- Set connector sync job error
- Set connector sync job stats
- Data stream APIs
- Document APIs
- Enrich APIs
- EQL APIs
- ES|QL APIs
- Features APIs
- Fleet APIs
- Graph explore API
- Index APIs
- Alias exists
- Aliases
- Analyze
- Analyze index disk usage
- Clear cache
- Clone index
- Close index
- Create index
- Create or update alias
- Create or update component template
- Create or update index template
- Create or update index template (legacy)
- Delete component template
- Delete dangling index
- Delete alias
- Delete index
- Delete index template
- Delete index template (legacy)
- Exists
- Field usage stats
- Flush
- Force merge
- Get alias
- Get component template
- Get field mapping
- Get index
- Get index settings
- Get index template
- Get index template (legacy)
- Get mapping
- Import dangling index
- Index recovery
- Index segments
- Index shard stores
- Index stats
- Index template exists (legacy)
- List dangling indices
- Open index
- Refresh
- Resolve index
- Resolve cluster
- Rollover
- Shrink index
- Simulate index
- Simulate template
- Split index
- Unfreeze index
- Update index settings
- Update mapping
- Index lifecycle management APIs
- Create or update lifecycle policy
- Get policy
- Delete policy
- Move to step
- Remove policy
- Retry policy
- Get index lifecycle management status
- Explain lifecycle
- Start index lifecycle management
- Stop index lifecycle management
- Migrate indices, ILM policies, and legacy, composable and component templates to data tiers routing
- Inference APIs
- Delete inference API
- Get inference API
- Perform inference API
- Create inference API
- Stream inference API
- Update inference API
- AlibabaCloud AI Search inference service
- Amazon Bedrock inference service
- Anthropic inference service
- Azure AI studio inference service
- Azure OpenAI inference service
- Cohere inference service
- Elasticsearch inference service
- ELSER inference service
- Google AI Studio inference service
- Google Vertex AI inference service
- HuggingFace inference service
- Mistral inference service
- OpenAI inference service
- Watsonx inference service
- Info API
- Ingest APIs
- Licensing APIs
- Logstash APIs
- Machine learning APIs
- Machine learning anomaly detection APIs
- Add events to calendar
- Add jobs to calendar
- Close jobs
- Create jobs
- Create calendars
- Create datafeeds
- Create filters
- Delete calendars
- Delete datafeeds
- Delete events from calendar
- Delete filters
- Delete forecasts
- Delete jobs
- Delete jobs from calendar
- Delete model snapshots
- Delete expired data
- Estimate model memory
- Flush jobs
- Forecast jobs
- Get buckets
- Get calendars
- Get categories
- Get datafeeds
- Get datafeed statistics
- Get influencers
- Get jobs
- Get job statistics
- Get model snapshots
- Get model snapshot upgrade statistics
- Get overall buckets
- Get scheduled events
- Get filters
- Get records
- Open jobs
- Post data to jobs
- Preview datafeeds
- Reset jobs
- Revert model snapshots
- Start datafeeds
- Stop datafeeds
- Update datafeeds
- Update filters
- Update jobs
- Update model snapshots
- Upgrade model snapshots
- Machine learning data frame analytics APIs
- Create data frame analytics jobs
- Delete data frame analytics jobs
- Evaluate data frame analytics
- Explain data frame analytics
- Get data frame analytics jobs
- Get data frame analytics jobs stats
- Preview data frame analytics
- Start data frame analytics jobs
- Stop data frame analytics jobs
- Update data frame analytics jobs
- Machine learning trained model APIs
- Clear trained model deployment cache
- Create or update trained model aliases
- Create part of a trained model
- Create trained models
- Create trained model vocabulary
- Delete trained model aliases
- Delete trained models
- Get trained models
- Get trained models stats
- Infer trained model
- Start trained model deployment
- Stop trained model deployment
- Update trained model deployment
- Migration APIs
- Node lifecycle APIs
- Query rules APIs
- Reload search analyzers API
- Repositories metering APIs
- Rollup APIs
- Root API
- Script APIs
- Search APIs
- Search Application APIs
- Searchable snapshots APIs
- Security APIs
- Authenticate
- Change passwords
- Clear cache
- Clear roles cache
- Clear privileges cache
- Clear API key cache
- Clear service account token caches
- Create API keys
- Create or update application privileges
- Create or update role mappings
- Create or update roles
- Bulk create or update roles API
- Bulk delete roles API
- Create or update users
- Create service account tokens
- Delegate PKI authentication
- Delete application privileges
- Delete role mappings
- Delete roles
- Delete service account token
- Delete users
- Disable users
- Enable users
- Enroll Kibana
- Enroll node
- Get API key information
- Get application privileges
- Get builtin privileges
- Get role mappings
- Get roles
- Query Role
- Get service accounts
- Get service account credentials
- Get Security settings
- Get token
- Get user privileges
- Get users
- Grant API keys
- Has privileges
- Invalidate API key
- Invalidate token
- OpenID Connect prepare authentication
- OpenID Connect authenticate
- OpenID Connect logout
- Query API key information
- Query User
- Update API key
- Update Security settings
- Bulk update API keys
- SAML prepare authentication
- SAML authenticate
- SAML logout
- SAML invalidate
- SAML complete logout
- SAML service provider metadata
- SSL certificate
- Activate user profile
- Disable user profile
- Enable user profile
- Get user profiles
- Suggest user profile
- Update user profile data
- Has privileges user profile
- Create Cross-Cluster API key
- Update Cross-Cluster API key
- Snapshot and restore APIs
- Snapshot lifecycle management APIs
- SQL APIs
- Synonyms APIs
- Text structure APIs
- Transform APIs
- Usage API
- Watcher APIs
- Definitions
- Command line tools
- elasticsearch-certgen
- elasticsearch-certutil
- elasticsearch-create-enrollment-token
- elasticsearch-croneval
- elasticsearch-keystore
- elasticsearch-node
- elasticsearch-reconfigure-node
- elasticsearch-reset-password
- elasticsearch-saml-metadata
- elasticsearch-service-tokens
- elasticsearch-setup-passwords
- elasticsearch-shard
- elasticsearch-syskeygen
- elasticsearch-users
- Optimizations
- Troubleshooting
- Fix common cluster issues
- Diagnose unassigned shards
- Add a missing tier to the system
- Allow Elasticsearch to allocate the data in the system
- Allow Elasticsearch to allocate the index
- Indices mix index allocation filters with data tiers node roles to move through data tiers
- Not enough nodes to allocate all shard replicas
- Total number of shards for an index on a single node exceeded
- Total number of shards per node has been reached
- Troubleshooting corruption
- Fix data nodes out of disk
- Fix master nodes out of disk
- Fix other role nodes out of disk
- Start index lifecycle management
- Start Snapshot Lifecycle Management
- Restore from snapshot
- Troubleshooting broken repositories
- Addressing repeated snapshot policy failures
- Troubleshooting an unstable cluster
- Troubleshooting discovery
- Troubleshooting monitoring
- Troubleshooting transforms
- Troubleshooting Watcher
- Troubleshooting searches
- Troubleshooting shards capacity health issues
- Troubleshooting an unbalanced cluster
- Capture diagnostics
- Migration guide
- Release notes
- Elasticsearch version 8.17.0
- Elasticsearch version 8.16.1
- Elasticsearch version 8.16.0
- Elasticsearch version 8.15.5
- Elasticsearch version 8.15.4
- Elasticsearch version 8.15.3
- Elasticsearch version 8.15.2
- Elasticsearch version 8.15.1
- Elasticsearch version 8.15.0
- Elasticsearch version 8.14.3
- Elasticsearch version 8.14.2
- Elasticsearch version 8.14.1
- Elasticsearch version 8.14.0
- Elasticsearch version 8.13.4
- Elasticsearch version 8.13.3
- Elasticsearch version 8.13.2
- Elasticsearch version 8.13.1
- Elasticsearch version 8.13.0
- Elasticsearch version 8.12.2
- Elasticsearch version 8.12.1
- Elasticsearch version 8.12.0
- Elasticsearch version 8.11.4
- Elasticsearch version 8.11.3
- Elasticsearch version 8.11.2
- Elasticsearch version 8.11.1
- Elasticsearch version 8.11.0
- Elasticsearch version 8.10.4
- Elasticsearch version 8.10.3
- Elasticsearch version 8.10.2
- Elasticsearch version 8.10.1
- Elasticsearch version 8.10.0
- Elasticsearch version 8.9.2
- Elasticsearch version 8.9.1
- Elasticsearch version 8.9.0
- Elasticsearch version 8.8.2
- Elasticsearch version 8.8.1
- Elasticsearch version 8.8.0
- Elasticsearch version 8.7.1
- Elasticsearch version 8.7.0
- Elasticsearch version 8.6.2
- Elasticsearch version 8.6.1
- Elasticsearch version 8.6.0
- Elasticsearch version 8.5.3
- Elasticsearch version 8.5.2
- Elasticsearch version 8.5.1
- Elasticsearch version 8.5.0
- Elasticsearch version 8.4.3
- Elasticsearch version 8.4.2
- Elasticsearch version 8.4.1
- Elasticsearch version 8.4.0
- Elasticsearch version 8.3.3
- Elasticsearch version 8.3.2
- Elasticsearch version 8.3.1
- Elasticsearch version 8.3.0
- Elasticsearch version 8.2.3
- Elasticsearch version 8.2.2
- Elasticsearch version 8.2.1
- Elasticsearch version 8.2.0
- Elasticsearch version 8.1.3
- Elasticsearch version 8.1.2
- Elasticsearch version 8.1.1
- Elasticsearch version 8.1.0
- Elasticsearch version 8.0.1
- Elasticsearch version 8.0.0
- Elasticsearch version 8.0.0-rc2
- Elasticsearch version 8.0.0-rc1
- Elasticsearch version 8.0.0-beta1
- Elasticsearch version 8.0.0-alpha2
- Elasticsearch version 8.0.0-alpha1
- Dependencies and versions
Update security certificates with a different CA
editUpdate security certificates with a different CA
editIf you have to trust a new CA from your organization, or you need to generate a new CA yourself, use this new CA to sign the new node certificates and instruct your nodes to trust the new CA.
Generate a new certificate for the transport layer
editCreate a new CA certificate, or get the CA certificate of your organization, and add it to your existing CA truststore. After you finish updating your certificates for all nodes, you can remove the old CA certificate from your truststore (but not before!).
The following examples use PKCS#12 files, but the same steps apply to JKS keystores.
-
Open the
ES_PATH_CONF/elasticsearch.yml
file and check the names and locations of the keystores that are currently in use. You’ll use the same names for your new keystores.In this example, the keystore and truststore are using different files. Your configuration might use the same file for both the keystore and the truststore.
These instructions assume that the provided certificate is signed by a trusted CA and the verification mode is set to
certificate
. This setting ensures that nodes to not attempt to perform hostname verification.xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 xpack.security.transport.ssl.verification_mode: certificate
-
On any node in your cluster, generate a new CA certificate. You only need to complete this step one time. If you’re using the CA certificate of your organization, then skip this step.
./bin/elasticsearch-certutil ca --pem
Command parameters
-
--pem
- Generates a directory containing a CA certificate and key in PEM format instead of PKCS#12.
-
Enter a name for the compressed output file that will contain your
certificate and key, or accept the default name of
elastic-stack-ca.zip
. -
Unzip the output file. The resulting directory contains a CA certificate (
ca.crt
) and a private key (ca.key
).Keep these file in a secure location as they contain the private key for your CA.
-
-
On every node in your cluster, import the new
ca.crt
certificate into your existing CA truststore. This step ensures that your cluster trusts the new CA certificate. This example uses the Javakeytool
utility to import the certificate into theelastic-stack-ca.p12
CA truststore.keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ -storepass <password> -alias new-ca -file ca.crt
Command parameters
-
-keystore
- Name of the truststore that you are importing the new CA certificate into.
-
-storepass
- Password for the CA truststore.
-
-alias
- Name that you want to assign to the new CA certificate entry in the keystore.
-
-file
- Name of the new CA certificate to import.
-
-
Check that the new CA certificate was added to your truststore.
keytool -keystore config/elastic-stack-ca.p12 -list
When prompted, enter the password for the CA truststore.
The output should contain both the existing CA certificate and your new certificate. If you previously used the
elasticsearch-certutil
tool to generate your keystore, the alias of the old CA defaults toca
and the type of entry isPrivateKeyEntry
.
Generate a new certificate for each node in your cluster
editNow that your CA truststore is updated, use your new CA certificate to sign a certificate for your nodes.
If your organization has its own CA, you’ll need to generate Certificate Signing Requests (CSRs). CSRs contain information that your CA uses to generate and sign a security certificate.
-
Using the new CA certificate and key, create a new certificate for your nodes.
./bin/elasticsearch-certutil cert --ca-cert ca/ca.crt --ca-key ca/ca.key
Command parameters
-
--ca-cert
-
Specifies the path to your new CA certificate (
ca.crt
) in PEM format. You must also specify the--ca-key
parameter. -
--ca-key
-
Specifies the path to the private key (
ca.key
) for your CA certificate. You must also specify the--ca-cert
parameter.
-
Enter a name for the output file or accept the default of
elastic-certificates.p12
. - When prompted, enter a password for your node certificate.
-
-
On the current node in your cluster where you’re updating the keystore, start a rolling restart.
Stop at the step indicating Perform any needed changes, and then proceed to the next step in this procedure.
-
Replace your existing keystore with the new keystore, ensuring that the file names match. For example,
elastic-certificates.p12
.If your keystore password is changing, then save the keystore with a new filename so that Elasticsearch doesn’t attempt to reload the file before you update the password.
-
If you needed to save the new keystore with a new filename, update the
ES_PATH_CONF/elasticsearch.yml
file to use the filename of the new keystore. For example:xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12
- Start the node where you updated the keystore.
-
(Optional) Use the SSL certificate API to verify that Elasticsearch loaded the new keystore.
resp = client.ssl.certificates() print(resp)
const response = await client.ssl.certificates(); console.log(response);
GET /_ssl/certificates
-
If you’re only updating certificates for the transport layer (and not the HTTP layer), then complete step 2 through step 6 one node at a time until you’ve updated all keystores in your cluster. You can then complete the remaining steps for a rolling restart.
Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer.
-
(Optional) After replacing keystores on each node in your cluster, list the certificates in your truststore and then remove the old CA certificate.
If you previously used the
elasticsearch-certutil
tool to generate your keystore, the alias of the old CA defaults toca
and the type of entry isPrivateKeyEntry
.keytool -delete -noprompt -alias ca -keystore config/elastic-stack-ca.p12 \ -storepass <password>
Command parameters
-
-alias
- Name of the keystore alias for the old CA certificate that you want to remove from your truststore.
-
What’s next?
editWell done! You’ve updated the keystore for the transport layer. You can also update the keystore for the HTTP layer if necessary. If you’re not updating the keystore for the HTTP layer, then you’re all set.
Generate a new certificate for the HTTP layer
editYou can generate certificates for the HTTP layer using your new CA certificate and private key. Other components such as Kibana or any of the Elastic language clients verify this certificate when they connect to Elasticsearch.
If your organization has its own CA, you’ll need to
generate Certificate Signing Requests (CSRs). CSRs contain
information that your CA uses to generate and sign a security certificate
instead of using self-signed certificates that the elasticsearch-certutil
tool
generates.
-
On any node in your cluster where Elasticsearch is installed, run the Elasticsearch HTTP certificate tool.
./bin/elasticsearch-certutil http
This command generates a
.zip
file that contains certificates and keys to use with Elasticsearch and Kibana. Each folder contains aREADME.txt
explaining how to use these files.-
When asked if you want to generate a CSR, enter
n
. -
When asked if you want to use an existing CA, enter
y
. -
Enter the absolute path to your new CA certificate, such as the path to
the
ca.crt
file. -
Enter the absolute path to your new CA certificate private key, such as
the path to the
ca.key
file. -
Enter an expiration value for your certificate. You can enter the
validity period in years, months, or days. For example, enter
1y
for one year. -
When asked if you want to generate one certificate per node, enter
y
.Each certificate will have its own private key, and will be issued for a specific hostname or IP address.
-
When prompted, enter the name of the first node in your cluster. Use the
same node name as the value for the
node.name
parameter in theelasticsearch.yml
file. -
Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate.
List every hostname and variant used to connect to your cluster over HTTPS.
- Enter the IP addresses that clients can use to connect to your node.
- Repeat these steps for each additional node in your cluster.
-
When asked if you want to generate a CSR, enter
- After generating a certificate for each of your nodes, enter a password for your keystore when prompted.
-
Unzip the generated
elasticsearch-ssl-http.zip
file. This compressed file contains one directory for both Elasticsearch and Kibana. Within the/elasticsearch
directory is a directory for each node that you specified with its ownhttp.p12
file. For example:/node1 |_ README.txt |_ http.p12 |_ sample-elasticsearch.yml
/node2 |_ README.txt |_ http.p12 |_ sample-elasticsearch.yml
/node3 |_ README.txt |_ http.p12 |_ sample-elasticsearch.yml
-
If necessary, rename each
http.p12
file to match the name of your existing certificate for HTTP client communications. For example,node1-http.p12
. -
On the current node in your cluster where you’re updating the keystore, start a rolling restart.
Stop at the step indicating Perform any needed changes, and then proceed to the next step in this procedure.
-
Replace your existing keystore with the new keystore, ensuring that the file names match. For example,
node1-http.p12
.If your keystore password is changing, then save the keystore with a new filename so that Elasticsearch doesn’t attempt to reload the file before you update the password.
-
If you needed to save the new keystore with a new filename, update the
ES_PATH_CONF/elasticsearch.yml
file to use the filename of the new keystore. For example:xpack.security.http.ssl.enabled: true xpack.security.http.ssl.keystore.path: node1-http.p12
-
If your keystore password is changing, add the password for your private key to the secure settings in Elasticsearch.
./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password
-
Start the node where you updated the keystore.
Use the cat nodes API to confirm that the node joined the cluster:
resp = client.cat.nodes() print(resp)
response = client.cat.nodes puts response
const response = await client.cat.nodes(); console.log(response);
GET _cat/nodes
-
(Optional) Use the SSL certificate API to verify that Elasticsearch loaded the new keystore.
resp = client.ssl.certificates() print(resp)
const response = await client.ssl.certificates(); console.log(response);
GET /_ssl/certificates
- One node at a time, complete step 5 through step 10 until you’ve updated all keystores in your cluster.
- Complete the remaining steps for a rolling restart, beginning with the step to Reenable shard allocation.
What’s next?
editWell done! You’ve updated the keystore for the HTTP layer. You can now update encryption between Kibana and Elasticsearch.
Update encryption between Kibana and Elasticsearch
editWhen you ran the elasticsearch-certutil
tool with the http
option, it
created a /kibana
directory containing an elasticsearch-ca.pem
file. You
use this file to configure Kibana to trust the Elasticsearch CA for the HTTP
layer.
-
Copy the
elasticsearch-ca.pem
file to the Kibana configuration directory, as defined by theKBN_PATH_CONF
path.KBN_PATH_CONF
contains the path for the Kibana configuration files. If you installed Kibana using archive distributions (zip
ortar.gz
), the path defaults toKBN_HOME/config
. If you used package distributions (Debian or RPM), the path defaults to/etc/kibana
. -
If you modified the filename for the
elasticsearch-ca.pem
file, editkibana.yml
and update the configuration to specify the location of the security certificate for the HTTP layer.elasticsearch.ssl.certificateAuthorities: KBN_PATH_CONF/elasticsearch-ca.pem
- Restart Kibana.
On this page