diff --git a/docs/en/security/getting-started.asciidoc b/docs/en/security/getting-started.asciidoc index 8d3356467ad..74f99772443 100644 --- a/docs/en/security/getting-started.asciidoc +++ b/docs/en/security/getting-started.asciidoc @@ -4,7 +4,7 @@ To secure a cluster, you must install {xpack} on every node in the cluster. Basic authentication is enabled by default--to communicate with the cluster, you must specify a username and password. -Unless you <>, all +Unless you {xpack-ref}/anonymous-access.html[enable anonymous access], all requests that don't include a user name and password are rejected. {security} provides a built-in `elastic` superuser you can use @@ -95,19 +95,19 @@ xpack.security.audit.enabled: true By default, events are logged to a dedicated `elasticsearch-access.log` file in `ES_HOME/logs`. You can also store the events in an Elasticsearch index for easier analysis and control what events are logged. For more information, see -<>. +{xpack-ref}/auditing.html[Configuring Auditing]. -- [[moving-on]] IMPORTANT: Once you get these basic security measures in place, we strongly recommend that you secure communications to and from nodes by - configuring your cluster to use <>. + configuring your cluster to use {xpack-ref}/ssl-tls.html[SSL/TLS encryption]. Nodes that do not have encryption enabled send passwords in plain text! Depending on your security requirements, you might also want to: -* Integrate with <> or <>, -or <> for authentication. -* Use <> to allow or deny requests from particular +* Integrate with {xpack-ref}/ldap-realm.html[LDAP] or {xpack-ref}/active-directory-realm.html[Active Directory], +or {xpack-ref}/pki-realm.html[require certificates] for authentication. +* Use {xpack-ref}/ip-filtering.html[IP Filtering] to allow or deny requests from particular IP addresses or address ranges. diff --git a/docs/en/security/gs-index.asciidoc b/docs/en/security/gs-index.asciidoc new file mode 100644 index 00000000000..2beef9403fc --- /dev/null +++ b/docs/en/security/gs-index.asciidoc @@ -0,0 +1,100 @@ +[[xpack-security]] += Securing Elasticsearch and Kibana + +[partintro] +-- +{security} enables you to easily secure a cluster. With Security, +you can password-protect your data as well as implement more advanced security +measures such as encrypting communications, role-based access control, +IP filtering, and auditing. This guide describes how to configure the security +features you need, and interact with your secured cluster. + +Security protects Elasticsearch clusters by: + +* <> + with password protection, role-based access control, and IP filtering. +* <> + with message authentication and SSL/TLS encryption. +* <> + so you know who's doing what to your cluster and the data it stores. + +[float] +[[preventing-unauthorized-access]] +=== Preventing Unauthorized Access + +To prevent unauthorized access to your Elasticsearch cluster, you must have a +way to _authenticate_ users. This simply means that you need a way to validate +that a user is who they claim to be. For example, you have to make sure only +the person named _Kelsey Andorra_ can sign in as the user `kandorra`. X-Pack +Security provides a standalone authentication mechanism that enables you to +quickly password-protect your cluster. If you're already using {xpack-ref}/ldap-realm.html[LDAP], +{xpack-ref}/active-directory-realm.html[ Active Directory], or {xpack-ref}/pki-realm.html[ PKI] to manage +users in your organization, {security} is able to integrate with those +systems to perform user authentication. + +In many cases, simply authenticating users isn't enough. You also need a way to +control what data users have access to and what tasks they can perform. {security} +enables you to _authorize_ users by assigning access _privileges_ to _roles_, +and assigning those roles to users. For example, this +{xpack-ref}/authorization.html[role-based access control] mechanism (a.k.a RBAC) enables +you to specify that the user `kandorra` can only perform read operations on the +`events` index and can't do anything at all with other indices. + +{security} also supports {xpack-ref}/ip-filtering.html[ IP-based authorization]. You can +whitelist and blacklist specific IP addresses or subnets to control network-level +access to a server. + +[float] +[[preserving-data-integrity]] +=== Preserving Data Integrity + +A critical part of security is keeping confidential data confidential. +Elasticsearch has built-in protections against accidental data loss and +corruption. However, there's nothing to stop deliberate tampering or data +interception. {security} preserves the integrity of your data by +{xpack-ref}/ssl-tls.html[encrypting communications] to and from nodes and +{xpack-ref}/enable-message-authentication.html[authenticating message] to verify that they +have not been tampered with or corrupted in transit during node-to-node +communication. For even greater protection, you can increase the +{xpack-ref}/ciphers.html[encryption strength] and +{xpack-ref}/separating-node-client-traffic.html[separate client traffic from node-to-node communications]. + + +[float] +[[maintaining-audit-trail]] +=== Maintaining an Audit Trail + +Keeping a system secure takes vigilance. By using {security} to maintain +an audit trail, you can easily see who is accessing your cluster and what they're +doing. By analyzing access patterns and failed attempts to access your cluster, +you can gain insights into attempted attacks and data breaches. Keeping an +auditable log of the activity in your cluster can also help diagnose operational +issues. + +[float] +=== Where to Go Next + +* <> + steps through how to install and start using Security for basic authentication. + +* {xpack-ref}/how-security-works.html[How Security Works] + provides more information about how Security supports user authentication, + authorization, and encryption. + +* {xpack-ref}/tribe-clients-integrations.html[Integrations] + shows you how to interact with an Elasticsearch cluster protected by + X-Pack Security. + +* {xpack-ref}/security-reference.html[Reference] + provides detailed information about the access privileges you can grant to + users, the settings you can configure for Security in `elasticsearch.yml`, + and the files where Security configuration information is stored. + +[float] +=== Have Comments, Questions, or Feedback? + +Head over to our {security-forum}[Security Discussion Forum] +to share your experience, questions, and suggestions. +-- + +include::getting-started.asciidoc[] \ No newline at end of file diff --git a/docs/en/watcher/getting-started.asciidoc b/docs/en/watcher/getting-started.asciidoc index bf8e25bf2fb..e6739cee537 100644 --- a/docs/en/watcher/getting-started.asciidoc +++ b/docs/en/watcher/getting-started.asciidoc @@ -17,12 +17,12 @@ condition is met. [[log-add-input]] === Schedule the Watch and Define an Input -A watch <> controls how often a watch is triggered. -The watch <> gets the data that you want to evaluate. +A watch {xpack-ref}/trigger-schedule.html[schedule] controls how often a watch is triggered. +The watch {xpack-ref}/input.html[input] gets the data that you want to evaluate. To periodically search log data and load the results into the -watch, you could use an <> schedule and a -<> input. For example, the following Watch searches +watch, you could use an {xpack-ref}/schedule-interval.html[interval] schedule and a +{xpack-ref}/input-search.html[search] input. For example, the following Watch searches the `logs` index for errors every 10 seconds: [source,js] @@ -49,7 +49,7 @@ PUT _xpack/watcher/watch/log_error_watch // CONSOLE <1> Schedules are typically configured to run less frequently. This example sets the interval to 10 seconds so you can easily see the watches being triggered. - Since this watch runs so frequently, don't forget to <> + Since this watch runs so frequently, don't forget to {xpack-ref}/log-delete.html[delete the watch] when you're done experimenting. If you check the watch history you'll see that the watch is being triggered every @@ -75,7 +75,7 @@ GET .watcher-history*/_search?pretty [[log-add-condition]] === Add a Condition -A <> evaluates the data you've loaded into the watch and +A {xpack-ref}/condition.html[condition] evaluates the data you've loaded into the watch and determines if any action is required. Now that you've loaded log errors into the watch, you can define a condition that checks to see if any errors were found. @@ -106,7 +106,7 @@ PUT _xpack/watcher/watch/log_error_watch } -------------------------------------------------- // CONSOLE -<1> The <> condition lets you easily compare against +<1> The {xpack-ref}/condition-compare.html[compare] condition lets you easily compare against values in the execution context. For this compare condition to evaluate to `true`, you need to add an event @@ -154,7 +154,7 @@ GET .watcher-history*/_search?pretty Recording watch records in the watch history is nice, but the real power of {watcher} is being able to do something when the watch condition is met. A -watch's <> define what to do when the watch condition +watch's {xpack-ref}/actions.html[actions] define what to do when the watch condition evaluates to `true`. You can send emails, call third-party webhooks, write documents to an Elasticsearch index, or log messages to the standard Elasticsearch log files. @@ -226,9 +226,9 @@ allowed to execute read-only watch operations. [[next-steps]] === Where to Go Next -* See <> for more information about the +* See {xpack-ref}/how-watcher-works.html[How {watcher} Works] for more information about the anatomy of a watch and the watch lifecycle. -* See <> for more examples of setting up +* See {xpack-ref}/example-watches.html[Example Watches] for more examples of setting up a watch. * See the https://github.com/elastic/examples/tree/master/Alerting[Example Watches] in the Elastic Examples repo for additional sample watches you can use diff --git a/docs/en/watcher/gs-index.asciidoc b/docs/en/watcher/gs-index.asciidoc new file mode 100644 index 00000000000..e799adec40a --- /dev/null +++ b/docs/en/watcher/gs-index.asciidoc @@ -0,0 +1,67 @@ +[[xpack-alerting]] += Alerting on Cluster and Index Events + +[partintro] +-- +You can watch for changes or anomalies in your data and perform the necessary +actions in response. For example, you might want to: + +* Monitor social media as another way to detect failures in user-facing + automated systems like ATMs or ticketing systems. When the number of tweets + and posts in an area exceeds a threshold of significance, notify a service + technician. + +* Monitor your infrastructure, tracking disk usage over time. Open a helpdesk + ticket when any servers are likely to run out of free space in the next few + days. + +* Track network activity to detect malicious activity, and proactively change + firewall configuration to reject the malicious user. + +* Monitor Elasticsearch, and send immediate notification to the system + administrator if nodes leave the cluster or query throughput exceeds an + expected range. + +* Track application response times and if page-load time exceeds SLAs for more + than 5 minutes, open a helpdesk ticket. If SLAs are exceeded for an hour, + page the administrator on duty. + +All of these use-cases share a few key properties: + +* The relevant data or changes in data can be identified with a periodic + Elasticsearch query. + +* The results of the query can be checked against a condition. + +* One or more actions are taken if the condition is true -- an email is sent, a + 3rd party system is notified, or the query results are stored. + +[float] +=== How Watches Work + +{xpack} provides an API for creating, managing and testing _watches_. A watch +describes a single alert and can contain multiple notification actions. + +A watch is constructed from four simple building blocks: + +Schedule:: A schedule for running a query and checking the condition. + +Query:: The query to run as input to the condition. Watches + support the full Elasticsearch query language, including + aggregations. + +Condition:: A condition that determines whether or not to execute the actions. + You can use simple conditions (always true), or use scripting for + more sophisticated scenarios. + +Actions:: One or more actions, such as sending email, pushing data to + 3rd party systems through a webhook, or indexing the results of + the query. + +A full history of all watches is maintained in an Elasticsearch index. This +history keeps track of each time a watch is triggered and records the results +from the query, whether the condition was met, and what actions were taken. + +-- + +include::getting-started.asciidoc[]