🔎 Open source distributed and RESTful search engine.
Go to file
Jason Tedor 2bf8f4b0bc Remove print writer wrapping for users tools
When writing the users and users_roles files, we wrap a custom writer in
a print writer. There is a problem with this though: when print writer
closes it closes our underlying custom writer and the close
implementation for our custom writer is not trivial, it executes code
that can throw an I/O exception. When print writer invokes this close
and an I/O exception is thrown, it swallows that exception and sets the
status on the print writer to error. One would think that we could
simply check this status but alas print writer is broken here. The act
of checking the status causes print writer to try to flush the
underyling stream which is going to be completely undefined because the
underlying stream might or might not be closed. This might cause another
exception to be thrown, losing the original. Print writer screwed the
pooch here, there is no good reason to try to do any I/O after the
underlying writer entered a failed state. To address this we remove the
use of print writer, we use our custom writer directly. This allows any
thrown exceptions to bubble up.

Relates elastic/x-pack-elasticsearch#2288

Original commit: elastic/x-pack-elasticsearch@11b8dd5641
2017-08-16 12:50:39 -04:00
.github Add issue template 2017-03-19 16:37:21 -04:00
buildSrc Rename x-pack project names to new names with split repo 2017-02-10 11:02:42 -08:00
dev-tools [DOCS] Copy RN script from Elasticsearch (elastic/x-pack-elasticsearch#2163) 2017-08-15 16:34:51 -07:00
docs [DOCS] Add custom URL instructions (elastic/x-pack-elasticsearch#2215) 2017-08-15 10:32:11 -07:00
license-tools Respond to rename random ASCII helper methods 2017-04-04 11:04:37 -04:00
migrate Add migration script to split xpack (elastic/elasticsearch#4949) 2017-02-10 08:00:51 -08:00
plugin Remove print writer wrapping for users tools 2017-08-16 12:50:39 -04:00
qa Tests: Ensure responses are closed in watch backwards compat tests 2017-08-16 16:29:52 +02:00
test Re-enable OpenLDAP tests and run against vagrant instance (elastic/x-pack-elasticsearch#2121) 2017-08-04 09:44:08 -06:00
transport-client Rename core plugin and transport dirs 2017-02-10 11:02:42 -08:00
.dir-locals.el Update .dir-locals.el for enforced line length 2016-02-04 14:55:41 -07:00
.gitignore Adding new build files after split 2017-02-10 11:02:42 -08:00
.projectile Add .dir-locals.el and .projectile 2015-10-30 11:16:29 -06:00
GRADLE.CHEATSHEET.asciidoc Fixing grammar in GRADLE.CHEATSHEET 2016-05-18 14:17:13 -04:00
LICENSE.txt Initial X-Pack commit 2018-04-20 14:16:58 -07:00
NOTICE.txt Build: Enable notice generation for x-pack (elastic/x-pack-elasticsearch#695) 2017-03-02 19:06:15 -08:00
README.asciidoc [DOCS] Update readme with token requirements 2017-08-15 16:49:52 -07:00
build.gradle Build: allow building snapshot of release branches (elastic/x-pack-elasticsearch#1582) 2017-05-30 09:04:27 -04:00
gradle.properties Gradle daemon is a demon 2015-11-25 10:39:08 -05:00
migrate-issues.py Introduce issue migration script 2017-02-09 17:09:30 -05:00
settings.gradle Rename x-pack project names to new names with split repo 2017-02-10 11:02:42 -08:00

README.asciidoc

= Elasticsearch X-Pack

A set of Elastic's commercial plugins for Elasticsearch:

- License
- Security
- Watcher
- Monitoring
- Machine Learning
- Graph

= Setup

You must checkout `x-pack-elasticsearch` and `elasticsearch` with a specific directory structure. The
`elasticsearch` checkout will be used when building `x-pack-elasticsearch`. The structure is:

- /path/to/elastic/elasticsearch
- /path/to/elastic/elasticsearch-extra/x-pack-elasticsearch

== Vault Secret

The build requires a Vault Secret ID. You can use a GitHub token by following these steps:

1. Go to https://github.com/settings/tokens
2. Click *Generate new token*
3. Set permissions to `read:org`
4. Copy the token into `~/.elastic/github.token`
5. Set the token's file permissions to `600`

```
$ mkdir ~/.elastic
$ vi ~/.elastic/github.token
# Add your_token exactly as it is into the file and save it
$ chmod 600 ~/.elastic/github.token
```

If you do not create the token, then you will see something along the lines of this as the failure when trying to build X-Pack:

```
* What went wrong:
Missing ~/.elastic/github.token file or VAULT_SECRET_ID environment variable, needed to authenticate with vault for secrets
```

=== Offline Mode

When running the build in offline mode (`--offline`), it will not required to have the vault secret setup.

== Native Code

**This is mandatory as tests depend on it**

Machine Learning requires platform specific binaries, build from https://github.com/elastic/machine-learning-cpp via CI servers.

The native artifacts are stored in S3. To retrieve them infra's team Vault service is utilized, which 
requires a github token. Please setup a github token as documented: 

https://github.com/elastic/infra/blob/master/docs/vault.md#github-auth

The github token has to be put into ~/.elastic/github.token, while the file rights must be set to 0600. 

= Build

- Run unit tests:
+
[source, txt]
-----
gradle clean test
-----

- Run all tests:
+
[source, txt]
-----
gradle clean check
-----

- Run integration tests:
+
[source, txt]
-----
gradle clean integTest
-----

- Package X-Pack (without running tests)
+
[source, txt]
-----
gradle clean assemble
-----

- Install X-Pack (without running tests)
+
[source, txt]
-----
gradle clean install
-----

= Building documentation

The source files in this repository can be included in either the X-Pack Reference or the Elasticsearch Reference. 

NOTE: In 5.5 and later, the Elasticsearch Reference includes X-Pack-specific content when it is built from this repo.

To build the Elasticsearch Reference on your local machine:

* Use the `index.asciidoc` file in the docs/en directory.
* Specify the location of the `elasticsearch/docs` directory with the `--resource` option when you run `build_docs.pl`.

For example:

[source, txt]
-----
./docs/build_docs.pl --doc elasticsearch-extra/x-pack-elasticsearch/docs/en/index.asciidoc 
--resource=elasticsearch/docs --chunk 1
-----

For information about building the X-Pack Reference, see the README in the x-pack repo.

To build a release notes page for the pull requests in this repository:

* Use the dev-tools/xes-release-notes.pl script.
* Specify the version label for which you want the release notes.
* Redirect the output to a new local file.

NOTE: You must have a personal access token called ~/.github_auth with "repo" scope. Use steps similar to "Vault Secret" to create this file. 

For example:
[source, txt]
-----
./dev-tools/xes_release_notes.pl v5.5.2 > ~/tmp/5.5.2.asciidoc
-----

== Adding Images

When you include an image in the documentation, specify the path relative to the location of the asciidoc file. By convention, we put images in an `images` subdirectory.

For example to insert `watcher-ui-edit-watch.png` in `watcher/limitations.asciidoc`:

. Add an `images` subdirectory to the watcher directory if it doesn't already exist. 
. In `limitations.asciidoc` specify:
+
[source, txt]
-----
 image::images/watcher-ui-edit-watch.png["Editing a watch"]
-----
 
Please note that image names and anchor IDs must be unique within the book, so do not use generic identifiers.