elasticsearch/docs/reference/licensing/update-license.asciidoc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

170 lines
5.2 KiB
Plaintext
Raw Normal View History

[role="xpack"]
[testenv="basic"]
[[update-license]]
2018-12-21 02:23:28 +08:00
=== Update license API
++++
<titleabbrev>Update license</titleabbrev>
++++
Updates the license for your {es} cluster.
[[update-license-api-request]]
==== {api-request-title}
`PUT _license`
`POST _license`
[[update-license-api-prereqs]]
==== {api-prereq-title}
* If {es} {security-features} are enabled, you need `manage`
<<privileges-list-cluster,cluster privilege>> to install the license.
* If {es} {security-features} are enabled and you are installing a gold or higher
license, you must enable TLS on the transport networking layer before you
[DOCS] Overhaul TLS security docs (#68946) * Removing security overview and condensing. * Adding new security file. * Minor changes. * Removing link to pass build. * Adding minimal security page. * Adding minimal security page. * Changes to intro. * Add basic and basic + http configurations. * Lots of changes, removed files, and redirects. * Moving some AD and LDAP sections, plus more redirects. * Redirects for SAML. * Updating snippet languages and redirects. * Adding another SAML redirect. * Hopefully fixing the ci/2 error. * Fixing another broken link for SAML. * Adding what's next sections and some cleanup. * Removes both security tutorials from the TOC. * Adding redirect for removed tutorial. * Add graphic for Elastic Security layers. * Incorporating reviewer feedback. * Update x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com> * Update x-pack/docs/en/security/securing-communications/security-minimal-setup.asciidoc Co-authored-by: Yang Wang <ywangd@gmail.com> * Update x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc Co-authored-by: Yang Wang <ywangd@gmail.com> * Update x-pack/docs/en/security/index.asciidoc Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com> * Update x-pack/docs/en/security/securing-communications/security-basic-setup-https.asciidoc Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com> * Apply suggestions from code review Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com> Co-authored-by: Yang Wang <ywangd@gmail.com> * Additional changes from review feedback. * Incorporating reviewer feedback. * Incorporating more reviewer feedback. * Clarify that TLS is for authenticating nodes Co-authored-by: Tim Vernum <tim@adjective.org> * Clarify security between nodes Co-authored-by: Tim Vernum <tim@adjective.org> * Clarify that TLS is between nodes Co-authored-by: Tim Vernum <tim@adjective.org> * Update title for configuring Kibana with a password Co-authored-by: Tim Vernum <tim@adjective.org> * Move section for enabling passwords between Kibana and ES to minimal security. * Add section for transport description, plus incorporate more reviewer feedback. * Moving operator privileges lower in the navigation. Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com> Co-authored-by: Ioannis Kakavas <ikakavas@protonmail.com> Co-authored-by: Yang Wang <ywangd@gmail.com> Co-authored-by: Tim Vernum <tim@adjective.org>
2021-03-25 23:54:39 +08:00
install the license. See <<encrypt-internode-communication>>.
* If the <<operator-privileges,{operator-feature}>> is enabled, only operator
users can use this API.
[[update-license-api-desc]]
==== {api-description-title}
You can update your license at runtime without shutting down your nodes. License
updates take effect immediately. If the license you are installing does not
support all of the features that were available with your previous license,
however, you are notified in the response. You must then re-submit the API
request with the `acknowledge` parameter set to `true`.
For more information about the different types of licenses, see
https://www.elastic.co/subscriptions.
[[update-license-api-query-params]]
==== {api-query-parms-title}
`acknowledge`::
2020-10-29 21:04:43 +08:00
(Optional, Boolean)
Specifies whether you acknowledge the license changes. The default
value is `false`.
[[update-license-api-request-body]]
==== {api-request-body-title}
`licenses`::
(Required, array)
A sequence of one or more JSON documents containing the license information.
[[update-license-api-example]]
==== {api-examples-title}
The following example updates to a basic license:
[source,console]
------------------------------------------------------------
PUT _license
{
"licenses": [
{
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
"type":"basic",
"issue_date_in_millis":1411948800000,
"expiry_date_in_millis":1914278399999,
"max_nodes":1,
"issued_to":"issuedTo",
"issuer":"issuer",
"signature":"xx"
}
]
}
------------------------------------------------------------
// TEST[skip:license testing issues]
NOTE: These values are invalid; you must substitute the appropriate content
from your license file.
You can also install your license file using a `curl` command. Be sure to add
`@` before the license file path to instruct curl to treat it as an input file.
[source,shell]
------------------------------------------------------------
curl -XPUT -u <user> 'http://<host>:<port>/_license' -H "Content-Type: application/json" -d @license.json
------------------------------------------------------------
// NOTCONSOLE
On Windows, use the following command:
[source,shell]
------------------------------------------------------------
Invoke-WebRequest -uri http://<host>:<port>/_license -Credential elastic -Method Put -ContentType "application/json" -InFile .\license.json
------------------------------------------------------------
In these examples,
* `<user>` is a user ID with the appropriate authority.
* `<host>` is the hostname of any node in the {es} cluster (`localhost` if
executing locally)
* `<port>` is the http port (defaults to `9200`)
* `license.json` is the license JSON file
NOTE: If your {es} node has SSL enabled on the HTTP interface, you must
start your URL with `https://`
If you previously had a license with more features than the basic license, you
receive the following response:
[source,js]
------------------------------------------------------------
{
"acknowledged": false,
"license_status": "valid",
"acknowledge": {
"message": """This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the "acknowledge=true" parameter:""",
"watcher": [
"Watcher will be disabled"
],
"logstash": [
"Logstash will no longer poll for centrally-managed pipelines"
],
"security": [
"The following X-Pack security functionality will be disabled: ..." ]
}
}
------------------------------------------------------------
// NOTCONSOLE
To complete the update, you must re-submit the API request and set the
`acknowledge` parameter to `true`. For example:
[source,console]
------------------------------------------------------------
PUT _license?acknowledge=true
{
"licenses": [
{
"uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
"type":"basic",
"issue_date_in_millis":1411948800000,
"expiry_date_in_millis":1914278399999,
"max_nodes":1,
"issued_to":"issuedTo",
"issuer":"issuer",
"signature":"xx"
}
]
}
------------------------------------------------------------
// TEST[skip:license testing issues]
Alternatively:
[source,sh]
------------------------------------------------------------
curl -XPUT -u elastic 'http://<host>:<port>/_license?acknowledge=true' -H "Content-Type: application/json" -d @license.json
------------------------------------------------------------
// NOTCONSOLE
For more information about the features that are disabled when your license
expires, see
{kibana-ref}/managing-licenses.html#license-expiration[License expiration].