Search Guard is optional and can be toggled on or off in the TeamConnect installer. For the standard Elasticsearch installation without Search Guard, please see Elasticsearch Setup.
This documentation covers a basic installation of Search Guard for TeamConnect Global Search. For more information on generating your own security certificates or configuring Search Guard roles, please see the plugin documentation here: http://floragunncom.github.io/search-guard-docs/.
Important: Users upgrading from previous versions of Elasticsearch must re-index their instances. Preliminary testing finds that it takes roughly one hour per 4GB for indexing. This number will vary based on the types of files present in the index.
The following instructions detail a RedHat installation via the Elasticsearch file. If your system is unable to perform this type of installation, please contact Mitratech Support at email@example.com.
1. Download the RPM file from https://www.elastic.co/downloads/pas...icsearch-5-3-0. TeamConnect is only certified against Elasticsearch 5.3.0. Later 5.3.x patches and updates will be supported. No updates outside of the 5.3.x line will be supported.
2. yum install the elasticsearch.xxxxx.rpm or rpm –Uvh elasticsearch.xxxxx.rpm
3. chkconfig –add elasticsearch to have Elasticsearch start on boot.
For the following steps, the paths listed below should be accurate to your installation. If not, find the elasticsearch/bin folder and substitute that path in the directions below.
1. Run the following command from the root Elasticsearch directory:
bin\elasticsearch-plugin install mapper-attachments
This plug-in provides the 'attachment' field type to Elasticsearch, thereby allowing it to index to content of documents like PDF files and Microsoft Word files.
2. Configure properties as detailed in Elasticsearch Configuration.
3. Start elasticsearch with: /etc/init.d/elasticsearch start after configuration is set.
1. Download the Elasticsearch zip file from the following website:
Note: If you are looking for an older version of ES, look here: https://www.elastic.co/downloads/past-releases
2. Unzip the file in your directory of choice. Having a dedicated folder not in Program Files is usually a good choice. (e.g. C:\...\Apache\Elasticsearch)
3. Navigate to your Elasticsearch /bin either through the command line using Windows Explorer and typing cmd in the top bar.
The directory should be similar to C:\...\app\Apache\Elasticsearch\elasticsearch-5.3\bin
4. Install the Mapper Attachments Plugin
This plugin is used to parse documents that are sent over from TeamConnect. It must be installed for documents to index properly. https://github.com/elastic/elasticse...er-attachments
5. Run the following command from the root Elasticsearch directory:
bin\elasticsearch-plugin install mapper-attachments
6. Configure properties as detailed in Elasticsearch Configuration.
Running Elasticsearch on Windows is fairly simple, just navigate to the bin directory of your Elasticsearch installation and start the elasticsearch.bat file.
Elasticsearch picks up your java path from your environment variables, so you'll have to add the JAVA_HOME variable pointed to Java 1.8.
In order to set the heap size for ES, you must define an environment variable for it.
- From the Start menu or Windows Explorer, right click on Computer and select Properties"
- From the left nav, select "Advanced System Settings".
- In System Properties, select "Environment Variables".
- Under "System variables", add a new variable with:
5. Select "OK" and "apply"
The steps from here forward apply to both Linux and Windows users seeking to install Search Guard.
Installing Search Guard
1. Install the Search Guard plugin.
Open the command prompt and change directory to your Elasticsearch folder
Run the command:
bin\elasticsearch-plugin install -b com.floragunn:search-guard-5:5.3.0-12
2. Users will need to create or obtain their own security certificates as these will not be provided by Mitratech. These certificates will need to be in .jks storage format.
- The node certificate must have a SAN (Subject Alternative Name) with an OID of 220.127.116.11.5.5
- For network communication, the SAN must also contain the machine's unique IP address, and the full computer name as a DNS name
3. Implement your configuration and certificate files.
Place node-keystore.jks & a copy of truststore.jks in the Elasticsearch/config directory
Place client-keystore.jks & truststore.jks in the directory of your choosing. Please ensure that this directory is accessible by TeamConnect.
Ensure that the teamconnect.properties file has accurately populated the relevant Search Guard fields. These fields are detailed below in Searchguard Properties in teamconnect.properties.
4. Close all Java instances. Run the following shell commands, as administrator, from the Elasticsearch\config directory.
Whitelist your certificates by adding the signing authority to your keytool chain. For example:
keytool -importcert -keystore "%JAVA_HOME%\jre\lib\security\cacerts" -storepass changeit -alias signing-ca -file signing-ca.crt
5. Update elasticsearch.yml, sg_config.yml, sg_roles.yml, sg_roles_mapping.yml, sg_action_groups.yml and sg_internal_users.yml settings to match appropriately. These files can be found in the TeamConnect/utilities/config folder of your TeamConnect installation.
Configuring Elasticsearch properties
Place the signing authority, node-keystore.jks & truststore.jks in Elasticsearch/config
Navigate to elasticseach/config & update the elasticsearch.yml settings
- cluster.name: elasticsearch
- This setting should match the cluster name in teamconnect.properties
- node.name: node-0
- Its recommended that this setting match your certificate name
- bootstrap.memory_lock: true
- network.host: 127.0.0.1
- transport.tcp.port: 9300
- These two should match the location in teamconnect.properties
- searchguard.ssl.transport.keystore_filepath: node-keystore.jks
- searchguard.ssl.transport.keystore_password: changeit
- Passwords are stored as clear text
- searchguard.ssl.transport.truststore_filepath: truststore.jks
- searchguard.ssl.transport.truststore_password: changeit
- searchguard.ssl.transport.enforce_hostname_verification: false
- searchguard.ssl.transport.keystore_alias: node-0
- Set the alias to match the alias of your node's keystore
- This setting configures the admin certificate that you can use with sgadmin
Configuring SearchGuard properties
Navigate to elasticsearch/plugins/search-guard-5/sgconfig. Move the generated utilities/config files into this folder.
- Add the full name of each client keystore as below
- Add the unencrypted username & bcrypt encrypted password following the format below.
- The username & hash are the unencrypted elasticsearch.transport.username & elasticsearch.transport.password located in teamconnect.properties
In this file, add the following lines under authc
6. Start Elasticsearch by running "elasticsearch.bat" in Elasticsearch/bin.
7. Customize your roles & permissions. Then load these settings into elasticsearch in order to initialize the cluster.
Open a cmd shell in "Elasticsearch\plugins\search-guard-5\tools"
Run the command:
sgadmin -ks ..\..\..\config\node-keystore.jks -kspass changeit -ts ..\..\..\config\truststore.jks -tspass changeit -cd ..\sgconfig -nhnv
The following serve as optional parameters for the sgadmin tool:
-h elasticsearch hostname, default: localhost
-p elasticsearch port, default: 9300
-cn clustername, default: elasticsearch
Re-run this command every time searchguard config changes are made.
Configuring Searchguard Properties
1. Navigate to elasticsearch/plugins/search-guard-5/sgconfig
Add the full name of each client keystore as below
2. Add the unencrypted username & brcrypt encrypted password following the format below.
The fields can be found as elasticsearch.transport.username & elasticsearch.transport.password in teamconnect.properties
username: hash: $2y$10$X1B8ncqRb1B.5SrjMEjM2e9wOtggziRF0AlceAmL0In.sMaeDe91i
Add the keystore name & username to the sg_all_access group as below
3. (Optional) Create your own custom role instead of using sg_all_access and add it to SG_ROLES.YML & SG_ROLES_MAPPING.YML
Searchguard Properties in teamconnect.properties
|elasticsearch.client.keystore.password=[password here]||These are the passwords for your keystore and truststore after being run encrypted.
If you generated one from the steps above, retrieve the output using your password.
|elasticsearch.transport.username=||These fields serve as the username and password to be paired with Search Guard for authentication.|
|elasticsearch.keystore.path=config/certs/keystore.jks||These are the actual locations of your files.
While you can use absolute path or relative path in listing these, absolute is recommended as best practices.
|elasticsearch.encryption.enabled=YES||Set this value to "YES" to enable Search Guard. Set this value to "NO" to disable Search Guard.|
|elasticsearch.client.notification.email=||The email set here will receive certificate expiration notices.|
Note: These fields can be configured in the TeamConnect Installer and do not have to be edited manually. For more information on this, please see Running the Installer in the TeamConnect Installation Help.