forked from zammad/zammad-documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathinstall-elasticsearch.rst
468 lines (372 loc) · 33.4 KB
/
install-elasticsearch.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
.. _install_elasticsearch:
Set up Elasticsearch
********************
We use Elasticsearch for the awesome search in Zammad.
Currently we support:
* Elasticsearch 2.4.x to 5.5.x with mapper-attachments plugin
* Elasticsearch 5.6.x, 6.x, 7.x with ingest-attachment plugin
This manual uses the ``zammad run`` command which is only available if you installed Zammad from one of our package repos.
If you're using a source code based install, simply leave that part away and just run ``rails ...`` or ``rake ...`` where ever neded.
Install Elasticsearch and its Attachment plugin
===============================================
Generic install Elasticsearch 2.4 (mapper-attachments):
-------------------------------------------------------
* Download and install via https://www.elastic.co/downloads/elasticsearch (2.4.x)
* Install the Attachment plugin
::
cd /usr/share/elasticsearch
bin/plugin install mapper-attachments
* Start elasticsearch
Generic install Elasticsearch 5.0-5.5 (mapper-attachments):
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Download and install via https://www.elastic.co/downloads/elasticsearch (5.0-5.5)
* Install the Attachment plugin
::
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install mapper-attachments
* Setting vm.max_map_count for Elasticsearch
::
sysctl -w vm.max_map_count=262144
On Mac you also have to do:
* https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docker.html#docker-cli-run-prod-mode
* Start elasticsearch
Generic install Elasticsearch 5.6, 6.x, 7.x (ingest-attachment):
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
* Download and install via https://www.elastic.co/downloads/elasticsearch (5.6, 6.x or 7.x)
* Install the Attachment plugin
::
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
* Setting vm.max_map_count for Elasticsearch
::
sysctl -w vm.max_map_count=262144
.. Tip:: On Mac OS you also have to do: https://www.elastic.co/guide/en/elasticsearch/reference/5.6/docker.html#docker-cli-run-prod-mode
* Start elasticsearch
The most current repository installation path can be found `here <https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html>`_.
CentOS 7:
+++++++++
::
rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
echo "[elasticsearch-7.x]
name=Elasticsearch repository for 7.x packages
baseurl=https://artifacts.elastic.co/packages/7.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md"| sudo tee /etc/yum.repos.d/elasticsearch-7.x.repo
yum install -y java-1.8.0-openjdk elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl start elasticsearch
systemctl enable elasticsearch
Debian 8:
+++++++++
::
apt-get install apt-transport-https sudo wget
echo "deb http://ftp.debian.org/debian jessie-backports main" | sudo tee -a /etc/apt/sources.list.d/debian-backports.list
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install -t jessie-backports openjdk-8-jre
apt-get install elasticsearch
sudo /var/lib/dpkg/info/ca-certificates-java.postinst configure
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Debian 9:
+++++++++
::
apt-get install apt-transport-https sudo wget
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install openjdk-8-jre elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Ubuntu 16.04 & 18.04:
+++++++++++++++++++++
::
apt-get install apt-transport-https sudo wget
echo "deb https://artifacts.elastic.co/packages/7.x/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-7.x.list
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
apt-get update
apt-get install openjdk-8-jre elasticsearch
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
systemctl restart elasticsearch
systemctl enable elasticsearch
Configure Zammad to work with Elasticsearch
*******************************************
::
zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"
Create Elasticsearch index
--------------------------
After you have configured Zammad for using Elasticsearch, you need to rebuild the index with the following command:
::
zammad run rake searchindex:rebuild
Optional settings
=================
Elasticsearch with HTTP basic auth
----------------------------------
If you're using another elasticsearch instance, you might need to authenticate against it.
Below options help you with that.
::
zammad run rails r "Setting.set('es_user', 'elasticsearch')"
zammad run rails r "Setting.set('es_password', 'zammad')"
Extra Elasticsearch index name space
------------------------------------
If you're running several Zammad instances (or other services using ES) with a central elasticsearch server,
you might want to specify which index Zammad should use.
::
zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')"
Ignore certain file extensions for indexing
-------------------------------------------
Some attachments might be troublesome when indexing or simply not needed within the search index.
You can tell Zammad to ignore those attachments by specifying their file extension so it won't post it to elasticsearch.
::
zammad run rails r "Setting.set('es_attachment_ignore', [ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )"
Maximum attachment size which is used for indexing
--------------------------------------------------
.. Note:: By default Zammad will limit indexing to attachments to 50 MB.
Limiting the maximum size of attachments (for indexing) might be usefull, you can set it like so:
::
zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)"
Using Elasticsearch on another server
=====================================
Elasticsearch can also be installed on another server but you have to know that this is insecure out of the box because Elasticsearch has no authentication.
For this reason you should run elasticsearch on 127.0.0.1 and use a reverse proxy with authentication to access it from Zammad.
.. Note:: Depending on the elasticsearch version it can provide authentication. There are also subscription based authentication features you can get from the elastic-team.
`You can find an Nginx reverse proxy config here <https://github.com/zammad/zammad/blob/develop/contrib/nginx/elasticsearch.conf>`_.
List of values which are stored in ElasticSearch
================================================
Ticket
------
Please note that these fields may vary if you created custom fields (objects) in the admin interface.
+------------------------------+--------------------------+---------------------------------------------------------------+
| Field | Sample Value | Description |
+------------------------------+--------------------------+---------------------------------------------------------------+
| article | Article | Article Hash, which includes all articles stored on a ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| article_count | 1 | Count of articles |
+------------------------------+--------------------------+---------------------------------------------------------------+
| close_at | null | First close time, after create |
+------------------------------+--------------------------+---------------------------------------------------------------+
| close_diff_in_min | null | Business hours in minutes within or above the specified SLA |
| | | for closing the ticket. |
+------------------------------+--------------------------+---------------------------------------------------------------+
| close_escalation_at | null | Time stamp of the escalation if the SLA of the closing time |
| | | has been violated. (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| close_in_min | null | Business hours in minutes it took to close the ticket. |
+------------------------------+--------------------------+---------------------------------------------------------------+
| create_article_sender | Customer | Who has created the first article (Agent,Customer) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| create_article_sender_id | 2 | Sender id of the first article (Agent|Customer) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| create_article_type | web | Article type for the first article (note, email, phone...) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| create_article_type_id | 11 | Article type ID for the first article (note, email, phone...) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| created_at | 2017-08-03T14:21:38.701Z | Created timestamp (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| created_by | User | User details of the user who created the ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| created_by_id | 13 | User id of user who created the ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| customer | User | Customer details |
+------------------------------+--------------------------+---------------------------------------------------------------+
| customer_id | 13 | User id of the current customer (assigned to ticket) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| escalation_at | null | Next first escalation date (nearest close_escalation_at, |
| | | first_response_escalation_at or update_escalation_at |
| | | (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| first_response_at | null | Time stamp of the first reaction to the customer |
| | | (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| first_response_diff_in_min | null | Business hours in minutes within or above the specified SLA |
| | | for the first reaction to the customer. |
+------------------------------+--------------------------+---------------------------------------------------------------+
| first_response_escalation_at | null | Time stamp of the escalation if the SLA of the first reaction |
| | | time has been violated. (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| first_response_in_min | null | Business hours in minutes it took to send inital response to |
| | | customer. |
+------------------------------+--------------------------+---------------------------------------------------------------+
| group | Sales | Current ticket group (Sales, Support...) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| group_id | 1 | Current ticket group id |
+------------------------------+--------------------------+---------------------------------------------------------------+
| id | 19 | Ticket id |
+------------------------------+--------------------------+---------------------------------------------------------------+
| last_contact_agent_at | null | Last contact to customer from agent, timestamp (DateTime, UTC)|
+------------------------------+--------------------------+---------------------------------------------------------------+
| last_contact_at | 2017-08-03T14:21:38.701Z | Last contact timestamp (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| last_contact_customer_at | 2017-08-03T14:21:38.701Z | Last contact from a customer, timestamp (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| note | null | Internal note for ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| number | 61019 | The uniq ticket number |
+------------------------------+--------------------------+---------------------------------------------------------------+
| organization_id | null | Id of the organization of a given customer |
+------------------------------+--------------------------+---------------------------------------------------------------+
| owner | User | Current owner (agent) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| owner_id | 1 | User id of owner |
+------------------------------+--------------------------+---------------------------------------------------------------+
| pending_time | null | Current pending time (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| preferences | | Sub Hash for special information |
+------------------------------+--------------------------+---------------------------------------------------------------+
| priority | 2 normal | Ticket priority |
+------------------------------+--------------------------+---------------------------------------------------------------+
| priority_id | 2 | ID of the currently set priority |
+------------------------------+--------------------------+---------------------------------------------------------------+
| state | new | Ticket state (new, open...) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| state_id | 1 | Ticket state id for available ticket states (new, open...) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| time_unit | null | Accounted time units for this ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| title | Feedback Form | Ticket title |
+------------------------------+--------------------------+---------------------------------------------------------------+
| type | null | Ticket Type (deprecated) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| update_diff_in_min | null | Business hours in minutes within or above the specified SLA |
| | | for updating the ticket. |
+------------------------------+--------------------------+---------------------------------------------------------------+
| update_escalation_at | null | Time stamp of the last update reaction to the customer |
| | | (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| update_in_min | null | Business hours in minutes it took to send the last update |
| | | response to customer |
+------------------------------+--------------------------+---------------------------------------------------------------+
| updated_at | 2017-08-03T14:21:38.701Z | Last update timestamp (DateTime, UTC) |
+------------------------------+--------------------------+---------------------------------------------------------------+
| updated_by | User | User who updated the ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
| updated_by_id | 13 | User id of user who updated the ticket |
+------------------------------+--------------------------+---------------------------------------------------------------+
Article
-------
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| Field | Sample Value | Description |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| attachment.title | file1.txt | File name |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| attachment.content | Hello world | File Content |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| attachment.keywords | keyword | File Keywords |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| attachment.content | Max | File Author |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| body | :) | Content of the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| cc | null | Content of the optional cc field |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| content_type | text/plain | Content type |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| created_at | 2017-08-03T14:21:38.000Z | Article create date (DateTime, UTC) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| created_by | See User | Who has created the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| created_by_id | 13 | Who (UserID) has created the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| from | Christopher Miller via <order@chrispresso.com> | Sender address of the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| id | 19 | internal (DB) article id |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| in_reply_to | null | Content of reply to field |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| internal | FALSE | Is article visible for customer |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| message_id | null | Message ID (if article was an email) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| message_id_md5 | null | internal message id MD5 Checksum |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| origin_by_id | null | For which real user (UserID) the article creation has been |
| | | done. For example the customer which was calling on the phone|
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| preferences | { } | Hash for additional information. |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| references | null | Email references header. |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| reply_to | null | Content of the reply to field |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| sender | Customer | Who is the sender (Customer, Agent) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| sender_id | 2 | Which type of user has created the article (Agent, Customer) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| subject | Feedback Form | Article subject |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| ticket_id | 19 | referencing ticket ID |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| to | null | Content of the to field |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| type | web | Article type (phone, email, web...) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| type_id | 11 | Article type id (phone, email, web...) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| updated_at | 2017-08-03T14:21:38.701Z | Update time of the article (DateTime, UTC) |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| updated_by | See User | Who has updated the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
| updated_by_id | 13 | Who (UserID) has updated the article |
+---------------------+------------------------------------------------+--------------------------------------------------------------+
User
++++
Please note that these fields may vary if you created custom fields (objects) in the admin interface.
+-----------------+--------------------------+-----------------------------------------+
| Field | Sample Value | Description |
+-----------------+--------------------------+-----------------------------------------+
| active | TRUE | is activ (boolean) |
+-----------------+--------------------------+-----------------------------------------+
| address | | User Adress |
+-----------------+--------------------------+-----------------------------------------+
| city | | User City |
+-----------------+--------------------------+-----------------------------------------+
| country | | User Country |
+-----------------+--------------------------+-----------------------------------------+
| created_at | 2017-07-26T21:21:28.000Z | User creation date (DateTime, UTC) |
+-----------------+--------------------------+-----------------------------------------+
| created_by_id | 1 | ID of user who created the current user |
+-----------------+--------------------------+-----------------------------------------+
| department | | User Department |
+-----------------+--------------------------+-----------------------------------------+
| email | chris@chrispresso.com | User E-Mail |
+-----------------+--------------------------+-----------------------------------------+
| fax | | User Fax |
+-----------------+--------------------------+-----------------------------------------+
| firstname | Christopher | User Firstname |
+-----------------+--------------------------+-----------------------------------------+
| id | 3 | Internal id (database, autincrement) |
+-----------------+--------------------------+-----------------------------------------+
| last_login | 2017-07-26T21:23:15.019Z | User last login (DateTime, UTC) |
+-----------------+--------------------------+-----------------------------------------+
| lastname | Miller | User Lastname |
+-----------------+--------------------------+-----------------------------------------+
| login | chris@chrispresso.com | User Login |
+-----------------+--------------------------+-----------------------------------------+
| mobile | | User Mobile |
+-----------------+--------------------------+-----------------------------------------+
| note | | internal note |
+-----------------+--------------------------+-----------------------------------------+
| organization | Chrispresso Inc | Orgnaization name of the current user |
+-----------------+--------------------------+-----------------------------------------+
| organization_id | 2 | ID which links to the organization name |
+-----------------+--------------------------+-----------------------------------------+
| phone | | User Phone |
+-----------------+--------------------------+-----------------------------------------+
| street | | User Street |
+-----------------+--------------------------+-----------------------------------------+
| updated_at | 2017-07-27T15:04:47.270Z | Last update date (DateTime, UTC) |
+-----------------+--------------------------+-----------------------------------------+
| updated_by_id | 3 | ID of user who updated the current user |
+-----------------+--------------------------+-----------------------------------------+
| verified | FALSE | is verified (boolean) |
+-----------------+--------------------------+-----------------------------------------+
| vip | FALSE | Is VIP (boolean) |
+-----------------+--------------------------+-----------------------------------------+
| web | | User Web Url |
+-----------------+--------------------------+-----------------------------------------+
| zip | | User ZIP |
+-----------------+--------------------------+-----------------------------------------+