OOZIE-3217 Enable definition of admin users using oozie-site.xml (orova via andras...
[oozie.git] / docs / src / site / twiki / AG_Install.twiki
1 <noautolink>
2
3 [[index][::Go back to Oozie Documentation Index::]]
4
5 ---+!! Oozie Installation and Configuration
6
7 %TOC%
8
9 ---++ Basic Setup
10
11 Follow the instructions at [[DG_QuickStart][Oozie Quick Start]].
12
13 ---++ Environment Setup
14
15 *IMPORTANT:* Oozie ignores any set value for =OOZIE_HOME=, Oozie computes its home automatically.
16
17 When running Oozie with its embedded Jetty server, the =conf/oozie-env.sh= file can be
18 used to configure the following environment variables used by Oozie:
19
20 *JETTY_OPTS* : settings for the Embedded Jetty that runs Oozie. Java System properties
21 for Oozie should be specified in this variable. No default value.
22
23 *OOZIE_CONFIG_FILE* : Oozie configuration file to load from Oozie configuration directory.
24 Default value =oozie-site.xml=.
25
26 *OOZIE_LOGS* : Oozie logs directory. Default value =logs/= directory in the Oozie installation
27 directory.
28
29 *OOZIE_LOG4J_FILE* :  Oozie Log4J configuration file to load from Oozie configuration directory.
30 Default value =oozie-log4j.properties=.
31
32 *OOZIE_LOG4J_RELOAD* : Reload interval of the Log4J configuration file, in seconds.
33 Default value =10=
34
35 *OOZIE_CHECK_OWNER* : If set to =true=, Oozie setup/start/run/stop scripts will check that the
36 owner of the Oozie installation directory matches the user invoking the script. The default
37 value is undefined and interpreted as a =false=.
38
39 *OOZIE_INSTANCE_ID* : The instance id of the Oozie server.  When using HA, each server instance should have a unique instance id.
40 Default value =${OOZIE_HTTP_HOSTNAME}=
41
42 ---++ Oozie Server Setup
43
44 The =oozie-setup.sh= script prepares the embedded Jetty server to run Oozie.
45
46 The =oozie-setup.sh= script options are:
47
48 <verbatim>
49 Usage  : oozie-setup.sh <Command and OPTIONS>
50           sharelib create -fs FS_URI [-locallib SHARED_LIBRARY] [-concurrency CONCURRENCY]
51                                                                 (create sharelib for oozie,
52                                                                 FS_URI is the fs.default.name
53                                                                 for hdfs uri; SHARED_LIBRARY, path to the
54                                                                 Oozie sharelib to install, it can be a tarball
55                                                                 or an expanded version of it. If omitted,
56                                                                 the Oozie sharelib tarball from the Oozie
57                                                                 installation directory will be used.
58                                                                 CONCURRENCY is a number of threads to be used
59                                                                 for copy operations.
60                                                                 By default 1 thread will be used)
61                                                                 (action fails if sharelib is already installed
62                                                                 in HDFS)
63           sharelib upgrade -fs FS_URI [-locallib SHARED_LIBRARY] ([deprecated][use create command to create new version]
64                                                                   upgrade existing sharelib, fails if there
65                                                                   is no existing sharelib installed in HDFS)
66           db create|upgrade|postupgrade -run [-sqlfile <FILE>] (create, upgrade or postupgrade oozie db with an
67                                                                 optional sql File)
68           export <file>                                         exports the oozie database to the specified
69                                                                 file in zip format
70           import <file>                                         imports the oozie database from the zip file
71                                                                 created by export
72           (without options prints this usage information)
73 </verbatim>
74
75 If a directory =libext/= is present in Oozie installation directory, the =oozie-setup.sh= script will
76 include all JARs in Jetty's =webapp/WEB_INF/lib/= directory.
77
78 If the ExtJS ZIP file is present in the =libext/= directory, it will be added to the Jetty's =webapp/= directory as well.
79 The ExtJS library file name be =ext-2.2.zip=.
80
81 ---+++ Setting Up Oozie with an Alternate Tomcat
82
83 Use the =addtowar.sh= script to prepare the Oozie server only if Oozie will run with a different
84 servlet  container than the embedded Jetty provided with the distribution.
85
86 The =addtowar.sh= script adds Hadoop JARs, JDBC JARs and the ExtJS library to the Oozie WAR file.
87
88 The =addtowar.sh= script options are:
89
90 <verbatim>
91  Usage  : addtowar <OPTIONS>
92  Options: -inputwar INPUT_OOZIE_WAR
93           -outputwar OUTPUT_OOZIE_WAR
94           [-hadoop HADOOP_VERSION HADOOP_PATH]
95           [-extjs EXTJS_PATH]
96           [-jars JARS_PATH] (multiple JAR path separated by ':')
97           [-secureWeb WEB_XML_PATH] (path to secure web.xml)
98 </verbatim>
99
100 The original =oozie.war= file is in the Oozie server installation directory.
101
102 After the Hadoop JARs and the ExtJS library has been added to the =oozie.war= file Oozie is ready to run.
103
104 Delete any previous deployment of the =oozie.war= from the servlet container (if using Tomcat, delete
105 =oozie.war= and =oozie= directory from Tomcat's =webapps/= directory)
106
107 Deploy the prepared =oozie.war= file (the one that contains the Hadoop JARs and the ExtJS library) in the
108 servlet container (if using Tomcat, copy the prepared =oozie.war= file to Tomcat's =webapps/= directory).
109
110 *IMPORTANT:* Only one Oozie instance can be deployed per Tomcat instance.
111
112 ---++ Database Configuration
113
114 Oozie works with HSQL, Derby, MySQL, Oracle, PostgreSQL or SQL Server databases.
115
116 By default, Oozie is configured to use Embedded Derby.
117
118 Oozie bundles the JDBC drivers for HSQL, Embedded Derby and PostgreSQL.
119
120 HSQL is normally used for test cases as it is an in-memory database and all data is lost every time Oozie is stopped.
121
122 If using Derby, MySQL, Oracle, PostgreSQL, or SQL Server, the Oozie database schema must be created using the =ooziedb.sh= command
123 line tool.
124
125 If using MySQL, Oracle, or SQL Server, the corresponding JDBC driver JAR file must be copied to Oozie's =libext/= directory and
126 it must be added to Oozie WAR file using the =bin/addtowar.sh= or the =oozie-setup.sh= scripts using the =-jars= option.
127
128 *IMPORTANT:* It is recommended to set the database's timezone to GMT (consult your database's documentation on how to do this).
129 Databases don't handle Daylight Saving Time shifts correctly, and may cause problems if you run any Coordinators with actions
130 scheduled to materialize during the 1 hour period where we "fall back".  For Derby, you can add '-Duser.timezone=GMT'
131 to =JETTY_OPTS= in oozie-env.sh to set this.  Alternatively, if using MySQL, you can have Oozie use GMT with MySQL without
132 setting MySQL's timezone to GMT by adding 'useLegacyDatetimeCode=false&serverTimezone=GMT' arguments to the JDBC
133 URL, =oozie.service.JPAService.jdbc.url=.  Be advised that changing the timezone on an existing Oozie database while Coordinators
134 are already running may cause Coordinators to shift by the offset of their timezone from GMT once after making this change.
135
136 The SQL database used by Oozie is configured using the following configuration properties (default values shown):
137
138 <verbatim>
139   oozie.db.schema.name=oozie
140   oozie.service.JPAService.create.db.schema=false
141   oozie.service.JPAService.validate.db.connection=false
142   oozie.service.JPAService.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
143   oozie.service.JPAService.jdbc.url=jdbc:derby:${oozie.data.dir}/${oozie.db.schema.name}-db;create=true
144   oozie.service.JPAService.jdbc.username=sa
145   oozie.service.JPAService.jdbc.password=
146   oozie.service.JPAService.pool.max.active.conn=10
147 </verbatim>
148
149 *NOTE:* If the =oozie.db.schema.create= property is set to =true= (default value is =false=) the Oozie tables
150 will be created automatically without having to use the =ooziedb= command line tool. Setting this property to
151  =true= it is recommended only for development.
152
153 *NOTE:* If the =oozie.db.schema.create= property is set to true, the =oozie.service.JPAService.validate.db.connection=
154 property value is ignored and Oozie handles it as set to =false=.
155
156 Once =oozie-site.xml= has been configured with the database configuration execute the =ooziedb.sh= command line tool to
157 create the database:
158
159 <verbatim>
160 $ bin/ooziedb.sh create -sqlfile oozie.sql -run
161
162 Validate DB Connection.
163 DONE
164 Check DB schema does not exist
165 DONE
166 Check OOZIE_SYS table does not exist
167 DONE
168 Create SQL schema
169 DONE
170 DONE
171 Create OOZIE_SYS table
172 DONE
173
174 Oozie DB has been created for Oozie version '3.2.0'
175
176 The SQL commands have been written to: oozie.sql
177
178 $
179 </verbatim>
180
181 NOTE: If using MySQL, Oracle, or SQL Server, copy the corresponding JDBC driver JAR file to the =libext/= directory before running
182 the =ooziedb.sh= command line tool.
183
184 NOTE: If instead using the '-run' option, the '-sqlfile <FILE>' option is used, then all the
185 database changes will be written to the specified file and the database won't be modified.
186
187 If using HSQL there is no need to use the =ooziedb= command line tool as HSQL is an in-memory database. Use the
188 following configuration properties in the oozie-site.xml:
189
190 <verbatim>
191   oozie.db.schema.name=oozie
192   oozie.service.JPAService.create.db.schema=true
193   oozie.service.JPAService.validate.db.connection=false
194   oozie.service.JPAService.jdbc.driver=org.hsqldb.jdbcDriver
195   oozie.service.JPAService.jdbc.url=jdbc:hsqldb:mem:${oozie.db.schema.name}
196   oozie.service.JPAService.jdbc.username=sa
197   oozie.service.JPAService.jdbc.password=
198   oozie.service.JPAService.pool.max.active.conn=10
199 </verbatim>
200
201 If you are interested in fine tuning how Oozie can retry database operations on failing database connectivity or errors, you can
202 set following properties to other values. Here are the default ones:
203
204 <verbatim>
205   oozie.service.JPAService.retry.initial-wait-time.ms=100
206   oozie.service.JPAService.retry.maximum-wait-time.ms=30000
207   oozie.service.JPAService.retry.max-retries=10
208 </verbatim>
209
210 If you set either =oozie.service.JPAService.retry.max-retries= or =oozie.service.JPAService.retry.maximum-wait-time.ms= to =0=,
211 no retry attempts will be made on any database connectivity issues. Exact settings for these properties depend also on how much load
212 is on Oozie regarding workflow and coordinator jobs.
213
214 The database operation retry functionality kicks in when there is a =javax.persistence.PersistenceException= those root cause is not
215 part of the normal everyday operation - filtered against a blacklist consisting of descendants like =NoSuchResultException=,
216 =NonUniqueResultException=, and the like. This way Oozie won't retry database operations on errors that are more related to the
217 current query, or otherwise part of the everyday life. This way it's ensured that this blacklist is database agnostic.
218
219 It has been tested with a MySQL / failing every minute 10 seconds / an Oozie coordinator job of an Oozie workflow consisting of four
220 workflow actions (some of them are asynchronous). On this setup Oozie was recovering after each and every database outage.
221
222 To set up such a failing MySQL scenario following has to be performed:
223
224    * Set =oozie.service.JPAService.connection.data.source= to =org.apache.oozie.util.db.BasicDataSourceWrapper=
225    within =oozie-site.xml=
226    * Set =oozie.service.JPAService.jdbc.driver= to =org.apache.oozie.util.db.FailingMySQLDriverWrapper= within =oozie-site.xml=
227    * Restart Oozie server
228    * Submit / start some workflows, coordinators etc.
229    * See how Oozie is retrying on injected database errors by looking at the Oozie server logs, grepping =JPAException= instances
230    with following message prefix: <verbatim>Deliberately failing to prepare statement.</verbatim>
231
232 ---++ Database Migration
233
234 Oozie provides an easy way to switch between databases without losing any data. Oozie servers should be stopped during the
235 database migration process.
236 The export of the database can be done using the following command:
237 <verbatim>
238 $ bin/oozie-setup.sh export /tmp/oozie_db.zip
239 1 rows exported from OOZIE_SYS
240 50 rows exported from WF_JOBS
241 340 rows exported from WF_ACTIONS
242 10 rows exported from COORD_JOBS
243 70 rows exported from COORD_ACTIONS
244 0 rows exported from BUNDLE_JOBS
245 0 rows exported from BUNDLE_ACTIONS
246 0 rows exported from SLA_REGISTRATION
247 0 rows exported from SLA_SUMMARY
248 </verbatim>
249
250 The database configuration is read from =oozie-site.xml=. After updating the configuration to point to the new database,
251 the tables have to be created with ooziedb.sh in the [[AG_Install#Database_Configuration][Database configuration]]
252 section above.
253 Once the tables are created, they can be filled with data using the following command:
254
255 <verbatim>
256 $ bin/oozie-setup.sh import /tmp/oozie_db.zip
257 Loading to Oozie database version 3
258 50 rows imported to WF_JOBS
259 340 rows imported to WF_ACTIONS
260 10 rows imported to COORD_JOBS
261 70 rows imported to COORD_ACTIONS
262 0 rows imported to BUNDLE_JOBS
263 0 rows imported to BUNDLE_ACTIONS
264 0 rows imported to SLA_REGISTRATION
265 0 rows imported to SLA_SUMMARY
266 </verbatim>
267
268 NOTE: The database version of the zip must match the version of the Oozie database it's imported to.
269
270 After starting the Oozie server, the history and the currently running workflows should be available.
271
272 *IMPORTANT:* The tool was primarily developed to make the migration from embedded databases (e.g. Derby) to standalone databases
273  (e.g. MySQL, PosgreSQL, Oracle, MS SQL Server), though it will work between any supported databases.
274 It is *not* optimized to handle databases over 1 Gb. If the database size is larger, it should be purged before migration.
275
276 ---++ Oozie Configuration
277
278 By default, Oozie configuration is read from Oozie's =conf/= directory
279
280 The Oozie configuration is distributed in 3 different files:
281
282    * =oozie-site.xml= : Oozie server configuration
283    * =oozie-log4j.properties= : Oozie logging configuration
284    * =adminusers.txt= : Oozie admin users list
285
286 ---+++ Oozie Configuration Properties
287
288 All Oozie configuration properties and their default values are defined in the =oozie-default.xml= file.
289
290 Oozie resolves configuration property values in the following order:
291
292    * If a Java System property is defined, it uses its value
293    * Else, if the Oozie configuration file (=oozie-site.xml=) contains the property, it uses its value
294    * Else, it uses the default value documented in the =oozie-default.xml= file
295
296 *NOTE:* The =oozie-default.xml= file found in Oozie's =conf/= directory is not used by Oozie, it is there
297 for reference purposes only.
298
299 ---+++ Precedence of Configuration Properties
300
301 For compatibility reasons across Hadoop / Oozie versions, some configuration properties can be defined using multiple keys
302 in the launcher configuration. Beginning with Oozie 5.0.0, some of them can be overridden, some others will be prepended to default
303 configuration values.
304
305 ---++++ Overriding Configuration Values
306
307 Overriding happens for following configuration entries with =oozie.launcher= prefix, by switching =oozie.launcher.override=
308 (on by default).
309
310 For those, following is the general approach:
311    * check whether a YARN compatible entry is present. If yes, use it to override default value
312    * check whether a MapReduce v2 compatible entry is present. If yes, use it to override default value
313    * check whether a MapReduce v1 compatible entry is present. If yes, use it to override default value
314    * use default value
315
316 Such properties are (legend: YARN / MapReduce v2 / MapReduce v1):
317    * max attempts of the MapReduce Application Master:
318       * N / A
319       * =mapreduce.map.maxattempts=
320       * =mapred.map.max.attempts=
321    * memory amount in MB of the MapReduce Application Master:
322       * =yarn.app.mapreduce.am.resource.mb=
323       * =mapreduce.map.memory.mb=
324       * =mapred.job.map.memory.mb=
325    * CPU vcore count of the MapReduce Application Master:
326       * =yarn.app.mapreduce.am.resource.cpu-vcores=
327       * =mapreduce.map.cpu.vcores=
328       * N / A
329    * logging level of the MapReduce Application Master:
330       * N / A
331       * =mapreduce.map.log.level=
332       * =mapred.map.child.log.level=
333    * MapReduce Application Master JVM options:
334       * =yarn.app.mapreduce.am.command-opts=
335       * =mapreduce.map.java.opts=
336       * =mapred.child.java.opts=
337    * MapReduce Application Master environment variable settings:
338       * =yarn.app.mapreduce.am.env=
339       * =mapreduce.map.env=
340       * =mapred.child.env=
341    * MapReduce Application Master job priority:
342       * N / A
343       * =mapreduce.job.priority=
344       * =mapred.job.priority=
345    * MapReduce Application Master job queue name:
346       * N / A
347       * =mapreduce.job.queuename=
348       * =mapred.job.queue.name=
349    * MapReduce View ACL settings:
350       * N / A
351       * =mapreduce.job.acl-view-job=
352       * N / A
353    * MapReduce Modify ACL settings:
354       * N / A
355       * =mapreduce.job.acl-modify-job=
356       * N / A
357
358 This list can be extended or modified by adding new configuration entries or updating existing values
359 beginning with =oozie.launcher.override.= within =oozie-site.xml=. Examples can be found in =oozie-default.xml=.
360
361 ---++++ Prepending Configuration Values
362
363 Prepending happens for following configuration entries with =oozie.launcher= prefix, by switching =oozie.launcher.prepend=
364 (on by default).
365
366 For those, following is the general approach:
367    * check whether a YARN compatible entry is present. If yes, use it to prepend to default value
368    * use default value
369
370 Such properties are (legend: YARN only):
371    * MapReduce Application Master JVM options: =yarn.app.mapreduce.am.admin-command-opts=
372    * MapReduce Application Master environment settings: =yarn.app.mapreduce.am.admin.user.env=
373
374 This list can be extended or modified by adding new configuration entries or updating existing values
375 beginning with =oozie.launcher.prepend.= within =oozie-site.xml=. Examples can be found in =oozie-default.xml=.
376
377 ---+++ Logging Configuration
378
379 By default, Oozie log configuration is defined in the =oozie-log4j.properties= configuration file.
380
381 If the Oozie log configuration file changes, Oozie reloads the new settings automatically.
382
383 By default, Oozie logs to Oozie's =logs/= directory.
384
385 Oozie logs in 4 different files:
386
387    * oozie.log: web services log streaming works from this log
388    * oozie-ops.log: messages for Admin/Operations to monitor
389    * oozie-instrumentation.log: instrumentation data, every 60 seconds (configurable)
390    * oozie-audit.log: audit messages, workflow jobs changes
391
392 The embedded Jetty and embedded Derby log files are also written to Oozie's =logs/= directory.
393
394 ---+++ Oozie User Authentication Configuration
395
396 Oozie supports Kerberos HTTP SPNEGO authentication, pseudo/simple authentication and anonymous access
397 for client connections.
398
399 Anonymous access (*default*) does not require the user to authenticate and the user ID is obtained from
400 the job properties on job submission operations, other operations are anonymous.
401
402 Pseudo/simple authentication requires the user to specify the user name on the request, this is done by
403 the PseudoAuthenticator class by injecting the =user.name= parameter in the query string of all requests.
404 The =user.name= parameter value is taken from the client process Java System property =user.name=.
405
406 Kerberos HTTP SPNEGO authentication requires the user to perform a Kerberos HTTP SPNEGO authentication sequence.
407
408 If Pseudo/simple or Kerberos HTTP SPNEGO authentication mechanisms are used, Oozie will return the user an
409 authentication token HTTP Cookie that can be used in later requests as identity proof.
410
411 Oozie uses Apache Hadoop-Auth (Java HTTP SPNEGO) library for authentication.
412 This library can be extended to support other authentication mechanisms.
413
414 Oozie user authentication is configured using the following configuration properties (default values shown):
415
416 <verbatim>
417   oozie.authentication.type=simple
418   oozie.authentication.token.validity=36000
419   oozie.authentication.signature.secret=
420   oozie.authentication.cookie.domain=
421   oozie.authentication.simple.anonymous.allowed=true
422   oozie.authentication.kerberos.principal=HTTP/localhost@${local.realm}
423   oozie.authentication.kerberos.keytab=${oozie.service.HadoopAccessorService.keytab.file}
424 </verbatim>
425
426 The =type= defines authentication used for Oozie HTTP endpoint, the supported values are:
427 simple | kerberos | #AUTHENTICATION_HANDLER_CLASSNAME#.
428
429 The =token.validity= indicates how long (in seconds) an authentication token is valid before it has
430 to be renewed.
431
432 The =signature.secret= is the signature secret for signing the authentication tokens. It is recommended to not set this, in which
433 case Oozie will randomly generate one on startup.
434
435 The =oozie.authentication.cookie.domain= The domain to use for the HTTP cookie that stores the
436 authentication token. In order to authentication to work correctly across all Hadoop nodes web-consoles
437 the domain must be correctly set.
438
439 The =simple.anonymous.allowed= indicates if anonymous requests are allowed. This setting is meaningful
440 only when using 'simple' authentication.
441
442 The =kerberos.principal= indicates the Kerberos principal to be used for HTTP endpoint.
443 The principal MUST start with 'HTTP/' as per Kerberos HTTP SPNEGO specification.
444
445 The =kerberos.keytab= indicates the location of the keytab file with the credentials for the principal.
446 It should be the same keytab file Oozie uses for its Kerberos credentials for Hadoop.
447
448 ---+++ Oozie Hadoop Authentication Configuration
449
450 Oozie works with Hadoop versions which support Kerberos authentication.
451
452 Oozie Hadoop authentication is configured using the following configuration properties (default values shown):
453
454 <verbatim>
455   oozie.service.HadoopAccessorService.kerberos.enabled=false
456   local.realm=LOCALHOST
457   oozie.service.HadoopAccessorService.keytab.file=${user.home}/oozie.keytab
458   oozie.service.HadoopAccessorService.kerberos.principal=${user.name}/localhost@{local.realm}
459 </verbatim>
460
461 The above default values are for a Hadoop 0.20 secure distribution (with support for Kerberos authentication).
462
463 To enable Kerberos authentication, the following property must be set:
464
465 <verbatim>
466   oozie.service.HadoopAccessorService.kerberos.enabled=true
467 </verbatim>
468
469 When using Kerberos authentication, the following properties must be set to the correct values (default values shown):
470
471 <verbatim>
472   local.realm=LOCALHOST
473   oozie.service.HadoopAccessorService.keytab.file=${user.home}/oozie.keytab
474   oozie.service.HadoopAccessorService.kerberos.principal=${user.name}/localhost@{local.realm}
475 </verbatim>
476
477 *IMPORTANT:* When using Oozie with a Hadoop 20 with Security distribution, the Oozie user in Hadoop must be configured
478 as a proxy user.
479
480 ---+++ User ProxyUser Configuration
481
482 Oozie supports impersonation or proxyuser functionality (identical to Hadoop proxyuser capabilities and conceptually
483 similar to Unix 'sudo').
484
485 Proxyuser enables other systems that are Oozie clients to submit jobs on behalf of other users.
486
487 Because proxyuser is a powerful capability, Oozie provides the following restriction capabilities
488 (similar to Hadoop):
489
490    * Proxyuser is an explicit configuration on per proxyuser user basis.
491    * A proxyuser user can be restricted to impersonate other users from a set of hosts.
492    * A proxyuser user can be restricted to impersonate users belonging to a set of groups.
493
494 There are 2 configuration properties needed to set up a proxyuser:
495
496    * oozie.service.ProxyUserService.proxyuser.#USER#.hosts: hosts from where the user #USER# can impersonate other users.
497    * oozie.service.ProxyUserService.proxyuser.#USER#.groups: groups the users being impersonated by user #USER# must belong to.
498
499 Both properties support the '*' wildcard as value. Although this is recommended only for testing/development.
500
501 ---+++ User Authorization Configuration
502
503 Oozie has a basic authorization model:
504
505    * Users have read access to all jobs
506    * Users have write access to their own jobs
507    * Users have write access to jobs based on an Access Control List (list of users and groups)
508    * Users have read access to admin operations
509    * Admin users have write access to all jobs
510    * Admin users have write access to admin operations
511
512 If security is disabled all users are admin users.
513
514 Oozie security is set via the following configuration property (default value shown):
515
516 <verbatim>
517   oozie.service.AuthorizationService.security.enabled=false
518 </verbatim>
519
520 NOTE: the old ACL model where a group was provided is still supported if the following property is set
521 in =oozie-site.xml=:
522
523 <verbatim>
524   oozie.service.AuthorizationService.default.group.as.acl=true
525 </verbatim>
526
527 Admin users are determined from the list of admin groups, specified in
528  =oozie.service.AuthorizationService.admin.groups= property. Use commas to separate multiple groups, spaces, tabs
529 and ENTER characters are trimmed.
530
531 If the above property for admin groups is not set, then defining the admin users can happen in the following manners.
532 The list of admin users can be in the =conf/adminusers.txt= file. The syntax of this file is:
533
534    * One user name per line
535    * Empty lines and lines starting with '#' are ignored
536
537 Admin users can also be defined in
538 =oozie.serviceAuthorizationService.admin.users= property. Use commas to separate multiple admin users, spaces, tabs
539 and ENTER characters are trimmed.
540
541 In case there are admin users defined using both methods, the effective list of admin users will be the union
542 of the admin users found in the adminusers.txt and those specified with =oozie.serviceAuthorizationService.admin.users=.
543
544
545 ---+++ Oozie System ID Configuration
546
547 Oozie has a system ID that is is used to generate the Oozie temporary runtime directory, the workflow job IDs, and the
548 workflow action IDs.
549
550 Two Oozie systems running with the same ID will not have any conflict but in case of troubleshooting it will be easier
551 to identify resources created/used by the different Oozie systems if they have different system IDs (default value
552 shown):
553
554 <verbatim>
555   oozie.system.id=oozie-${user.name}
556 </verbatim>
557
558 ---+++ Filesystem Configuration
559
560 Oozie lets you to configure the allowed Filesystems by using the following configuration property in oozie-site.xml:
561 <verbatim>
562   <property>
563     <name>oozie.service.HadoopAccessorService.supported.filesystems</name>
564     <value>hdfs</value>
565   </property>
566 </verbatim>
567
568 The above value, =hdfs=, which is the default, means that Oozie will only allow HDFS filesystems to be used.  Examples of other
569 filesystems that Oozie is compatible with are: hdfs, hftp, webhdfs, and viewfs.  Multiple filesystems can be specified as
570 comma-separated values.  Putting a * will allow any filesystem type, effectively disabling this check.
571
572 ---+++ HCatalog Configuration
573
574 Refer to the [[DG_HCatalogIntegration][Oozie HCatalog Integration]] document for a overview of HCatalog and
575 integration of Oozie with HCatalog. This section explains the various settings to be configured in oozie-site.xml on
576 the Oozie server to enable Oozie to work with HCatalog.
577
578 *Adding HCatalog jars to Oozie war:*
579
580  For Oozie server to talk to HCatalog server, HCatalog and hive jars need to be in the server classpath.
581 hive-site.xml which has the configuration to talk to the HCatalog server also needs to be in the classpath or specified by the
582 following configuration property in oozie-site.xml:
583 <verbatim>
584   <property>
585     <name>oozie.service.HCatAccessorService.hcat.configuration</name>
586     <value>/local/filesystem/path/to/hive-site.xml</value>
587   </property>
588 </verbatim>
589 The hive-site.xml can also be placed in a location on HDFS and the above property can have a value
590 of =hdfs://HOST:PORT/path/to/hive-site.xml= to point there instead of the local file system.
591
592 The oozie-[version]-hcataloglibs.tar.gz in the oozie distribution bundles the required hcatalog and hive jars that
593 needs to be placed in the Oozie server classpath. If using a version of HCatalog bundled in
594 Oozie hcataloglibs/, copy the corresponding HCatalog jars from hcataloglibs/ to the libext/ directory. If using a
595 different version of HCatalog, copy the required HCatalog jars from such version in the libext/ directory.
596 This needs to be done before running the =oozie-setup.sh= script so that these jars get added for Oozie.
597
598 *Configure HCatalog URI Handling:*
599
600 <verbatim>
601   <property>
602     <name>oozie.service.URIHandlerService.uri.handlers</name>
603     <value>org.apache.oozie.dependency.FSURIHandler,org.apache.oozie.dependency.HCatURIHandler</value>
604     <description>
605         Enlist the different uri handlers supported for data availability checks.
606     </description>
607   </property>
608 </verbatim>
609
610 The above configuration defines the different uri handlers which check for existence of data dependencies defined in a
611 Coordinator. The default value is =org.apache.oozie.dependency.FSURIHandler=. FSURIHandler supports uris with
612 schemes defined in the configuration =oozie.service.HadoopAccessorService.supported.filesystems= which are hdfs, hftp
613 and webhcat by default. HCatURIHandler supports uris with the scheme as hcat.
614
615 *Configure HCatalog services:*
616
617 <verbatim>
618   <property>
619     <name>oozie.services.ext</name>
620     <value>
621         org.apache.oozie.service.JMSAccessorService,
622         org.apache.oozie.service.PartitionDependencyManagerService,
623         org.apache.oozie.service.HCatAccessorService
624       </value>
625     <description>
626           To add/replace services defined in 'oozie.services' with custom implementations.
627           Class names must be separated by commas.
628     </description>
629   </property>
630 </verbatim>
631
632 PartitionDependencyManagerService and HCatAccessorService are required to work with HCatalog and support Coordinators
633 having HCatalog uris as data dependency. If the HCatalog server is configured to publish partition availability
634 notifications to a JMS compliant messaging provider like ActiveMQ, then JMSAccessorService needs to be added
635 to =oozie.services.ext= to handle those notifications.
636
637 *Configure JMS Provider JNDI connection mapping for HCatalog:*
638
639 <verbatim>
640   <property>
641     <name>oozie.service.HCatAccessorService.jmsconnections</name>
642     <value>
643       hcat://hcatserver.colo1.com:8020=java.naming.factory.initial#Dummy.Factory;java.naming.provider.url#tcp://broker.colo1.com:61616,
644       default=java.naming.factory.initial#org.apache.activemq.jndi.ActiveMQInitialContextFactory;java.naming.provider.url#tcp://broker.colo.com:61616;connectionFactoryNames#ConnectionFactory
645     </value>
646     <description>
647         Specify the map  of endpoints to JMS configuration properties. In general, endpoint
648         identifies the HCatalog server URL. "default" is used if no endpoint is mentioned
649         in the query. If some JMS property is not defined, the system will use the property
650         defined jndi.properties. jndi.properties files is retrieved from the application classpath.
651         Mapping rules can also be provided for mapping Hcatalog servers to corresponding JMS providers.
652         hcat://${1}.${2}.com:8020=java.naming.factory.initial#Dummy.Factory;java.naming.provider.url#tcp://broker.${2}.com:61616
653     </description>
654   </property>
655 </verbatim>
656
657   Currently HCatalog does not provide APIs to get the connection details to connect to the JMS Provider it publishes
658 notifications to. It only has APIs which provide the topic name in the JMS Provider to which the notifications are
659 published for a given database table. So the JMS Provider's connection properties needs to be manually configured
660 in Oozie using the above setting. You can either provide a =default= JNDI configuration which will be used as the
661 JMS Provider for all HCatalog servers, or can specify a configuration per HCatalog server URL or provide a
662 configuration based on a rule matching multiple HCatalog server URLs. For example: With the configuration of
663 hcat://${1}.${2}.com:8020=java.naming.factory.initial#Dummy.Factory;java.naming.provider.url#tcp://broker.${2}.com:61616,
664 request URL of hcat://server1.colo1.com:8020 will map to tcp://broker.colo1.com:61616, hcat://server2.colo2.com:8020
665 will map to tcp://broker.colo2.com:61616 and so on.
666
667 *Configure HCatalog Polling Frequency:*
668
669 <verbatim>
670   <property>
671     <name>oozie.service.coord.push.check.requeue.interval
672         </name>
673     <value>600000</value>
674     <description>Command re-queue interval for push dependencies (in millisecond).
675     </description>
676   </property>
677 </verbatim>
678
679   If there is no JMS Provider configured for a HCatalog Server, then oozie polls HCatalog based on the frequency defined
680 in =oozie.service.coord.input.check.requeue.interval=. This config also applies to HDFS polling.
681 If there is a JMS provider configured for a HCatalog Server, then oozie polls HCatalog based on the frequency defined
682 in =oozie.service.coord.push.check.requeue.interval= as a fallback.
683 The defaults for =oozie.service.coord.input.check.requeue.interval= and =oozie.service.coord.push.check.requeue.interval=
684 are 1 minute and 10 minutes respectively.
685
686 ---+++ Notifications Configuration
687
688 Oozie supports publishing notifications to a JMS Provider for job status changes and SLA met and miss events. For
689 more information on the feature, refer [[DG_JMSNotifications][JMS Notifications]] documentation. Oozie can also send email
690 notifications on SLA misses.
691
692    * *Message Broker Installation*: <br/>
693 For Oozie to send/receive messages, a JMS-compliant broker should be installed. Apache ActiveMQ is a popular JMS-compliant
694 broker usable for this purpose. See [[http://activemq.apache.org/getting-started.html][here]] for instructions on
695 installing and running ActiveMQ.
696
697    * *Services*: <br/>
698 Add/modify =oozie.services.ext= property in =oozie-site.xml= to include the following services.
699      <verbatim>
700      <property>
701         <name>oozie.services.ext</name>
702         <value>
703             org.apache.oozie.service.JMSAccessorService,
704             org.apache.oozie.service.JMSTopicService,
705             org.apache.oozie.service.EventHandlerService,
706             org.apache.oozie.sla.service.SLAService
707         </value>
708      </property>
709      </verbatim>
710
711    * *Event Handlers*: <br/>
712    <verbatim>
713      <property>
714         <name>oozie.service.EventHandlerService.event.listeners</name>
715         <value>
716             org.apache.oozie.jms.JMSJobEventListener,
717             org.apache.oozie.sla.listener.SLAJobEventListener,
718             org.apache.oozie.jms.JMSSLAEventListener,
719             org.apache.oozie.sla.listener.SLAEmailEventListener
720         </value>
721      </property>
722      </verbatim>
723     It is also recommended to increase =oozie.service.SchedulerService.threads= to 15 for faster event processing and sending notifications. The services and their functions are as follows: <br/>
724       JMSJobEventListener - Sends JMS job notifications <br/>
725       JMSSLAEventListener - Sends JMS SLA notifications <br/>
726       SLAEmailEventListener - Sends Email SLA notifications <br/>
727       SLAJobEventListener - Processes job events and calculates SLA. Does not send any notifications
728    * *JMS properties*:  <br/>
729 Add =oozie.jms.producer.connection.properties= property in =oozie-site.xml=. Its value corresponds to an
730 identifier (e.g. default) assigned to a semi-colon separated key#value list of properties from your JMS broker's
731 =jndi.properties= file. The important properties are =java.naming.factory.initial= and =java.naming.provider.url=.
732
733      As an example, if using ActiveMQ in local env, the property can be set to
734      <verbatim>
735      <property>
736         <name>oozie.jms.producer.connection.properties</name>
737         <value>
738             java.naming.factory.initial#org.apache.activemq.jndi.ActiveMQInitialContextFactory;java.naming.provider.url#tcp://localhost:61616;connectionFactoryNames#ConnectionFactory
739         </value>
740      </property>
741      </verbatim>
742    * *JMS Topic name*: <br/>
743 JMS consumers listen on a particular "topic". Hence Oozie needs to define a topic variable with which to publish messages
744 about the various jobs.
745      <verbatim>
746      <property>
747         <name>oozie.service.JMSTopicService.topic.name</name>
748         <value>
749             default=${username}
750         </value>
751         <description>
752             Topic options are ${username}, ${jobId}, or a fixed string which can be specified as default or for a
753             particular job type.
754             For e.g To have a fixed string topic for workflows, coordinators and bundles,
755             specify in the following comma-separated format: {jobtype1}={some_string1}, {jobtype2}={some_string2}
756             where job type can be WORKFLOW, COORDINATOR or BUNDLE.
757             Following example defines topic for workflow job, workflow action, coordinator job, coordinator action,
758             bundle job and bundle action
759             WORKFLOW=workflow,
760             COORDINATOR=coordinator,
761             BUNDLE=bundle
762             For jobs with no defined topic, default topic will be ${username}
763         </description>
764      </property>
765      </verbatim>
766
767      Another related property is the topic prefix.
768      <verbatim>
769      <property>
770         <name>oozie.service.JMSTopicService.topic.prefix</name>
771         <value></value>
772         <description>
773             This can be used to append a prefix to the topic in oozie.service.JMSTopicService.topic.name. For eg: oozie.
774         </description>
775      </property>
776      </verbatim>
777
778
779 ---+++ Setting Up Oozie with HTTPS (SSL)
780
781 *IMPORTANT*:
782 The default HTTPS configuration will cause all Oozie URLs to use HTTPS except for the JobTracker callback URLs. This is to simplify
783 configuration (no changes needed outside of Oozie), but this is okay because Oozie doesn't inherently trust the callbacks anyway;
784 they are used as hints.
785
786 The related environment variables are explained at [[AG_Install#Environment_Setup][Environment Setup]].
787
788 You can use either a certificate from a Certificate Authority or a Self-Signed Certificate.  Using a self-signed certificate
789 requires some additional configuration on each Oozie client machine.  If possible, a certificate from a Certificate Authority is
790 recommended because it's simpler to configure.
791
792 There's also some additional considerations when using Oozie HA with HTTPS.
793
794 ---++++To use a Self-Signed Certificate
795 There are many ways to create a Self-Signed Certificate, this is just one way.  We will be using
796 the [[http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html][keytool]] program, which is
797 included with your JRE. If it's not on your path, you should be able to find it in $JAVA_HOME/bin.
798
799 1. Run the following command (as the Oozie user) to create the keystore file, which will be named =.keystore= and located in the
800 Oozie user's home directory.
801 <verbatim>
802 keytool -genkeypair -alias jetty -keyalg RSA -dname "CN=hostname" -storepass password -keypass password
803 </verbatim>
804 The =hostname= should be the host name of the Oozie Server or a wildcard on the subdomain it belongs to.  Make sure to include
805 the "CN=" part.  You can change =storepass= and =keypass= values, but they should be the same.  If you do want to use something
806 other than password, you'll also need to change the value of the =oozie.https.keystore.pass= property in =oozie-site.xml= to
807 match; =password= is the default.
808
809 For example, if your Oozie server was at oozie.int.example.com, then you would do this:
810 <verbatim>
811 keytool -genkeypair -alias jetty -keyalg RSA -dname "CN=oozie.int.example.com" -storepass password -keypass password
812 </verbatim>
813 If you're going to be using Oozie HA, it's simplest if you have a single certificate that all Oozie servers in the HA group can use.
814 To do that, you'll need to use a wildcard on the subdomain it belongs to:
815 <verbatim>
816 keytool -genkeypair -alias jetty -keyalg RSA -dname "CN=*.int.example.com" -storepass password -keypass password
817 </verbatim>
818 The above would work on any server in the int.example.com domain.
819
820 2. Run the following command (as the Oozie user) to export a certificate file from the keystore file:
821 <verbatim>
822 keytool -exportcert -alias jetty -file path/to/anywhere/certificate.cert -storepass password
823 </verbatim>
824
825 3. Run the following command (as any user) to create a truststore containing the certificate we just exported:
826 <verbatim>
827 keytool -import -alias jetty -file path/to/certificate.cert -keystore /path/to/anywhere/oozie.truststore -storepass password2
828 </verbatim>
829 You'll need the =oozie.truststore= later if you're using the Oozie client (or other Java-based client); otherwise, you can skip
830 this step.  The =storepass= value here is only used to verify or change the truststore and isn't typically required when only
831 reading from it; so it does not have to be given to users only using the client.
832
833 ---++++To use a Certificate from a Certificate Authority
834
835 1. You will need to make a request to a Certificate Authority in order to obtain a proper Certificate; please consult a Certificate
836 Authority on this procedure.  If you're going to be using Oozie HA, it's simplest if you have a single certificate that all Oozie
837 servers in the HA group can use.  To do that, you'll need to use a wild on the subdomain it belongs to (e.g. "*.int.example.com").
838
839 2. Once you have your .cert file, run the following command (as the Oozie user) to create a keystore file from your certificate:
840 <verbatim>
841 keytool -import -alias jetty -file path/to/certificate.cert
842 </verbatim>
843 The keystore file will be named =.keystore= and located in the Oozie user's home directory.
844
845 ---++++Configure the Oozie Server to use SSL (HTTPS)
846
847 1. Make sure the Oozie server isn't running
848
849 2. Configure settings necessary for enabling SSL/TLS support in =oozie-site.xml=.
850
851 2a. Set =oozie.https.enabled= to =true=. To revert back to HTTP, set =oozie.https.enabled= to =false=.
852 2b. Set location and password for the keystore and location for truststore by setting =oozie.https.keystore.file=,
853 =oozie.https.keystore.pass=, =oozie.https.truststore.file=.
854
855 *Note:* =oozie.https.truststore.file= can be overridden by setting =javax.net.ssl.trustStore= system property.
856
857 The default HTTPS port Oozie listens on for secure connections is 11443; it can be changed via =oozie.https.port=.
858
859 It is possible to specify other HTTPS settings via =oozie-site.xml=:
860 - To include / exclude cipher suites, set =oozie.https.include.cipher.suites= / =oozie.https.exclude.cipher.suites=.
861 - To include / exclude TLS protocols, set =oozie.https.include.protocols= / =oozie.https.exclude.protocols=.
862 *Note:* Exclude is always preferred over include (i.e. if you both include and exclude an entity, it will be excluded).
863
864 3. Start the Oozie server
865
866 *Note:* If using Oozie HA, make sure that each Oozie server has a copy of the .keystore file.
867
868 ---++++Configure the Oozie Client to connect using SSL (HTTPS)
869
870 The first two steps are only necessary if you are using a Self-Signed Certificate; the third is required either way.
871 Also, these steps must be done on every machine where you intend to use the Oozie Client.
872
873 1. Copy or download the oozie.truststore file onto the client machine
874
875 2. When using any Java-based program, you'll need to pass =-Djavax.net.ssl.trustStore= to the JVM.  To
876 do this for the Oozie client:
877 <verbatim>
878 export OOZIE_CLIENT_OPTS='-Djavax.net.ssl.trustStore=/path/to/oozie.truststore'
879 </verbatim>
880
881 3. When using the Oozie Client, you will need to use https://oozie.server.hostname:11443/oozie instead of
882 http://oozie.server.hostname:11000/oozie -- Java will not automatically redirect from the http address to the https address.
883
884 ---++++Connect to the Oozie Web UI using SSL (HTTPS)
885
886 1. Use https://oozie.server.hostname:11443/oozie
887 though most browsers should automatically redirect you if you use http://oozie.server.hostname:11000/oozie
888
889 *IMPORTANT*: If using a Self-Signed Certificate, your browser will warn you that it can't verify the certificate or something
890 similar. You will probably have to add your certificate as an exception.
891
892 ---++++Additional considerations for Oozie HA with SSL
893
894 You'll need to configure the load balancer to do SSL pass-through.  This will allow the clients talking to Oozie to use the
895 SSL certificate provided by the Oozie servers (so the load balancer does not need one).  Please consult your load balancer's
896 documentation on how to configure this.  Make sure to point the load balancer at the https://HOST:HTTPS_PORT addresses for your
897 Oozie servers.  Clients can then connect to the load balancer at https://LOAD_BALANCER_HOST:PORT.
898
899 *Important:* Callbacks from the ApplicationMaster are done via http or https depending on what you enter for the
900 =OOZIE_BASE_URL= property.  If you are using a Certificate from a Certificate Authority, you can simply put the https address here.
901 If you are using a self-signed certificate, you have to do one of the following options (Option 1 is recommended):
902
903 Option 1) You'll need to follow the steps in
904 the [[AG_Install#Configure_the_Oozie_Client_to_connect_using_SSL_HTTPS][Configure the Oozie Client to connect using SSL (HTTPS)]]
905 section, but on the host of the ApplicationMaster.  You can then set =OOZIE_BASE_URL= to the load balancer https address.
906 This will allow the ApplicationMaster to contact the Oozie server with https (like the Oozie client, they are also Java
907 programs).
908
909 Option 2) You'll need setup another load balancer, or another "pool" on the existing load balancer, with the http addresses of the
910 Oozie servers.  You can then set =OOZIE_BASE_URL= to the load balancer http address.  Clients should use the https load balancer
911 address.  This will allow clients to use https while the ApplicationMaster uses http for callbacks.
912
913 ---+++ Fine Tuning an Oozie Server
914
915 Refer to the [[./oozie-default.xml][oozie-default.xml]] for details.
916
917 ---+++ Using Instrumentation instead of Metrics
918
919 As of version 4.1.0, Oozie includes a replacement for the Instrumentation based on Codahale's Metrics library.  It includes a
920 number of improvements over the original Instrumentation included in Oozie.  They both report most of the same information, though
921 the formatting is slightly different and there's some additional information in the Metrics version; the format of the output to the
922 oozie-instrumentation log is also different.
923
924 As of version 5.0.0, =MetricsInstrumentationService= is the default one, it's enlisted in =oozie.services=:
925     <verbatim>
926     <property>
927         <name>oozie.services</name>
928         <value>
929             ...
930             org.apache.oozie.service.MetricsInstrumentationService,
931             ...
932         </value>
933      </property>
934      </verbatim>
935
936 The deprecated =InstrumentationService= can be enabled by adding =InstrumentationService= reference to the list of
937 =oozie.services.ext=:
938     <verbatim>
939     <property>
940         <name>oozie.services.ext</name>
941         <value>
942             ...
943             org.apache.oozie.service.InstrumentationService,
944             ...
945         </value>
946      </property>
947      </verbatim>
948
949 By default the =admin/instrumentation= REST endpoint is no longer be available and instead the =admin/metrics= endpoint can
950 be used (see the [[WebServicesAPI#Oozie_Metrics][Web Services API]] documentation for more details); the Oozie Web UI also replaces
951 the "Instrumentation" tab with a "Metrics" tab.
952
953 If the deprecated =InstrumentationService= is used, the =admin/instrumentation= REST endpoint gets enabled, the =admin/metrics=
954 REST endpoint is no longer available (see the [[WebServicesAPI#Oozie_Metrics][Web Services API]] documentation for more details);
955 the Oozie Web UI also replaces the "Metrics" tab with the "Instrumentation" tab.
956
957 We can also publish the instrumentation metrics to the external server graphite or ganglia. For this the following
958 properties should be specified in oozie-site.xml :
959     <verbatim>
960     <property>
961         <name>oozie.external_monitoring.enable</name>
962         <value>false</value>
963         <description>
964             If the oozie functional metrics needs to be exposed to the metrics-server backend, set it to true
965             If set to true, the following properties has to be specified : oozie.metrics.server.name,
966             oozie.metrics.host, oozie.metrics.prefix, oozie.metrics.report.interval.sec, oozie.metrics.port
967         </description>
968     </property>
969
970     <property>
971         <name>oozie.external_monitoring.type</name>
972         <value>graphite</value>
973         <description>
974             The name of the server to which we want to send the metrics, would be graphite or ganglia.
975         </description>
976     </property>
977
978     <property>
979         <name>oozie.external_monitoring.address</name>
980         <value>http://localhost:2020</value>
981     </property>
982
983     <property>
984         <name>oozie.external_monitoring.metricPrefix</name>
985         <value>oozie</value>
986     </property>
987
988     <property>
989         <name>oozie.external_monitoring.reporterIntervalSecs</name>
990         <value>60</value>
991     </property>
992     </verbatim>
993
994 We can also publish the instrumentation metrics via JMX interface. For this the following property should be specified
995 in oozie-site.xml :
996     <verbatim>
997     <property>
998          <name>oozie.jmx_monitoring.enable</name>
999          <value>false</value>
1000          <description>
1001              If the oozie functional metrics needs to be exposed via JMX interface, set it to true.
1002          </description>
1003      </property>>
1004     </verbatim>
1005
1006 #HA
1007 ---+++ High Availability (HA)
1008
1009 Multiple Oozie Servers can be configured against the same database to provide High Availability (HA) of the Oozie service.
1010
1011 ---++++ Pre-requisites
1012
1013 1. A database that supports multiple concurrent connections.  In order to have full HA, the database should also have HA support, or
1014 it becomes a single point of failure.
1015
1016 *NOTE:* The default derby database does not support this
1017
1018 2. A ZooKeeper ensemble.
1019
1020 Apache ZooKeeper is a distributed, open-source coordination service for distributed applications; the Oozie servers use it for
1021 coordinating access to the database and communicating with each other.  In order to have full HA, there should be at least 3
1022 ZooKeeper servers.
1023 More information on ZooKeeper can be found [[http://zookeeper.apache.org][here]].
1024
1025 3. Multiple Oozie servers.
1026
1027 *IMPORTANT:* While not strictly required for all configuration properties, all of the servers should ideally have exactly the same
1028 configuration for consistency's sake.
1029
1030 4. A Loadbalancer, Virtual IP, or Round-Robin DNS.
1031
1032 This is used to provide a single entry-point for users and for callbacks from the JobTracker/ResourceManager.  The load balancer
1033 should be configured for round-robin between the Oozie servers to distribute the requests.  Users (using either the Oozie client, a
1034 web browser, or the REST API) should connect through the load balancer.  In order to have full HA, the load balancer should also
1035 have HA support, or it becomes a single point of failure.
1036
1037 ---++++ Installation/Configuration Steps
1038
1039 1. Install identically configured Oozie servers normally.  Make sure they are all configured against the same database and make sure
1040 that you DO NOT start them yet.
1041
1042 2. Add the following services to the extension services configuration property in oozie-site.xml in all Oozie servers.  This will
1043 make Oozie use the ZooKeeper versions of these services instead of the default implementations.
1044
1045 <verbatim>
1046 <property>
1047     <name>oozie.services.ext</name>
1048     <value>
1049         org.apache.oozie.service.ZKLocksService,
1050         org.apache.oozie.service.ZKXLogStreamingService,
1051         org.apache.oozie.service.ZKJobsConcurrencyService,
1052         org.apache.oozie.service.ZKUUIDService
1053     </value>
1054 </property>
1055 </verbatim>
1056
1057 3. Add the following property to oozie-site.xml in all Oozie servers.  It should be a comma-separated list of host:port pairs of the
1058 ZooKeeper servers.  The default value is shown below.
1059
1060 <verbatim>
1061 <property>
1062    <name>oozie.zookeeper.connection.string</name>
1063    <value>localhost:2181</value>
1064 </property>
1065 </verbatim>
1066
1067 4. (Optional) Add the following property to oozie-site.xml in all Oozie servers to specify the namespace to use.  All of the Oozie
1068 Servers that are planning on talking to each other should have the same namespace.  If there are multiple Oozie setups each doing
1069 their own HA, they should have their own namespace.  The default value is shown below.
1070
1071 <verbatim>
1072 <property>
1073     <name>oozie.zookeeper.namespace</name>
1074     <value>oozie</value>
1075 </property>
1076 </verbatim>
1077
1078 5. Change the value of =OOZIE_BASE_URL= in oozie-site.xml to point to the loadbalancer or virtual IP, for example:
1079
1080 <verbatim>
1081 <property>
1082     <name>oozie.base.url</name>
1083     <value>http://my.loadbalancer.hostname:11000/oozie</value>
1084 </property>
1085 </verbatim>
1086
1087 6. (Optional) If using a secure cluster, see [[AG_Install#Security][Security]] below on configuring Kerberos with Oozie HA.
1088
1089 7. Start the ZooKeeper servers.
1090
1091 8. Start the Oozie servers.
1092
1093 Note: If one of the Oozie servers becomes unavailable, querying Oozie for the logs from a job in the Web UI, REST API, or client may
1094 be missing information until that server comes back up.
1095
1096 ---++++ Security
1097
1098 Oozie HA works with the existing Oozie security framework and settings. For HA features (log streaming, share lib, etc) to work
1099 properly in a secure setup, following property can be set on each server. If =oozie.server.authentication.type= is not set, then
1100 server-server authentication will fall back on =oozie.authentication.type=.
1101
1102 <verbatim>
1103 <property>
1104     <name>oozie.server.authentication.type</name>
1105     <value>kerberos</value>
1106 </property>
1107 </verbatim>
1108
1109 Below are some additional steps and information specific to Oozie HA:
1110
1111 1. (Optional) To prevent unauthorized users or programs from interacting with or reading the znodes used by Oozie in ZooKeeper,
1112 you can tell Oozie to use Kerberos-backed ACLs.  To enforce this for all of the Oozie-related znodes, simply add the following
1113 property to oozie-site.xml in all Oozie servers and set it to =true=.  The default is =false=.
1114
1115 <verbatim>
1116 <property>
1117     <name>oozie.zookeeper.secure</name>
1118     <value>true</value>
1119 </property>
1120 </verbatim>
1121
1122 Note: The Kerberos principals of each of the Oozie servers should have the same primary name (i.e. in =primary/instance@REALM=, each
1123 server should have the same value for =primary=).
1124
1125 *Important:* Once this property is set to =true=, it will set the ACLs on all existing Oozie-related znodes to only allow Kerberos
1126 authenticated users with a principal that has the same primary as described above (also for any subsequently created new znodes).
1127 This means that if you ever want to turn this feature off, you will have to manually connect to ZooKeeper using a Kerberos principal
1128 with the same primary and either delete all znodes under and including the namespace (i.e. if =oozie.zookeeper.namespace= = =oozie=
1129 then that would be =/oozie=); alternatively, instead of deleting them all, you can manually set all of their ACLs to =world:anyone=.
1130 In either case, make sure that no Oozie servers are running while this is being done.
1131
1132 Also, in your zoo.cfg for ZooKeeper, make sure to set the following properties:
1133 <verbatim>
1134 authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider
1135 kerberos.removeHostFromPrincipal=true
1136 kerberos.removeRealmFromPrincipal=true
1137 </verbatim>
1138
1139 2. Until Hadoop 2.5.0 and later, there is a known limitation where each Oozie server can only use one HTTP principal.  However,
1140 for Oozie HA, we need to use two HTTP principals: =HTTP/oozie-server-host@realm= and =HTTP/load-balancer-host@realm=.  This
1141 allows access to each Oozie server directly and through the load balancer.  While users should always go through the load balancer,
1142 certain features (e.g. log streaming) require the Oozie servers to talk to each other directly; it can also be helpful for an
1143 administrator to talk directly to an Oozie server.  So, if using a Hadoop version prior to 2.5.0, you will have to choose which
1144 HTTP principal to use as you cannot use both; it is recommended to choose =HTTP/load-balancer-host@realm= so users can connect
1145 through the load balancer.  This will prevent Oozie servers from talking to each other directly, which will effectively disable
1146 log streaming.
1147
1148 For Hadoop 2.5.0 and later:
1149
1150 2a. When creating the keytab used by Oozie, make sure to include Oozie's principal and the two HTTP principals mentioned above.
1151
1152 2b. Set =oozie.authentication.kerberos.principal= to * (that is, an asterisks) so it will use both HTTP principals.
1153
1154 For earlier versions of Hadoop:
1155
1156 2a. When creating the keytab used by Oozie, make sure to include Oozie's principal and the load balancer HTTP principal
1157
1158 2b. Set =oozie.authentication.kerberos.principal= to =HTTP/load-balancer-host@realm=.
1159
1160 3. With Hadoop 2.6.0 and later, a rolling random secret that is synchronized across all Oozie servers will be used for signing the
1161 Oozie auth tokens.  This is done automatically when HA is enabled; no additional configuration is needed.
1162
1163 For earlier versions of Hadoop, each server will have a different random secret.  This will still work but will likely result in
1164 additional calls to the KDC to authenticate users to the Oozie server (because the auth tokens will not be accepted by other
1165 servers, which will cause a fallback to Kerberos).
1166
1167 4. If you'd like to use HTTPS (SSL) with Oozie HA, there's some additional considerations that need to be made.
1168 See the [[AG_Install#Setting_Up_Oozie_with_HTTPS_SSL][Setting Up Oozie with HTTPS (SSL)]] section for more information.
1169
1170 ---++++ JobId sequence
1171 Oozie in HA mode, uses ZK to generate job id sequence. Job Ids are of following format.
1172 <Id sequence>-<yyMMddHHmmss(server start time)>-<system_id>-<W/C/B>
1173
1174 Where, <systemId> is configured as =oozie.system.id= (default is "oozie-" + "user.name")
1175 W/C/B is suffix to job id indicating that generated job is a type of workflow or coordinator or bundle.
1176
1177 Maximum allowed character for job id sequence is 40. "Id sequence" is stored in ZK and reset to 0 once maximum job id sequence is
1178 reached. Maximum job id sequence is configured as =oozie.service.ZKUUIDService.jobid.sequence.max=, default value is 99999999990.
1179
1180 <verbatim>
1181 <property>
1182     <name>oozie.service.ZKUUIDService.jobid.sequence.max</name>
1183     <value>99999999990</value>
1184 </property>
1185 </verbatim>
1186
1187 ---++ Starting and Stopping Oozie
1188
1189 Use the standard commands to start and stop Oozie.
1190
1191 ---++ Oozie Command Line Installation
1192
1193 Copy and expand the =oozie-client= TAR.GZ file bundled with the distribution. Add the =bin/= directory to the =PATH=.
1194
1195 Refer to the [[DG_CommandLineTool][Command Line Interface Utilities]] document for a full reference of the =oozie=
1196 command line tool.
1197
1198 ---++ Oozie Share Lib
1199
1200 The Oozie sharelib TAR.GZ file bundled with the distribution contains the necessary files to run Oozie map-reduce streaming, pig,
1201 hive, sqooop, and distcp actions.  There is also a sharelib for HCatalog.  The sharelib is required for these actions to work; any
1202 other actions (mapreduce, shell, ssh, and java) do not require the sharelib to be installed.
1203
1204 As of Oozie 4.0, the following property is included.  If true, Oozie will create and ship a "launcher jar" to hdfs that contains
1205 classes necessary for the launcher job.  If false, Oozie will not do this, and it is assumed that the necessary classes are in their
1206 respective sharelib jars or the "oozie" sharelib instead.  When false, the sharelib is required for ALL actions; when true, the
1207 sharelib is only required for actions that need additional jars (the original list from above).
1208
1209 <verbatim>
1210 <property>
1211     <name>oozie.action.ship.launcher.jar</name>
1212     <value>true</value>
1213 </property>
1214 </verbatim>
1215
1216 Using sharelib CLI, sharelib files are copied to new lib_<timestamped> directory. At start, server picks the sharelib from latest
1217 time-stamp directory. While starting, server also purges sharelib directory which are older than sharelib retention days
1218 (defined as oozie.service.ShareLibService.temp.sharelib.retention.days and 7 days is default).
1219
1220 Sharelib mapping file can be also configured. Configured file is a key value mapping, where key will be the sharelib name for the
1221 action and value is a comma separated list of DFS or local filesystem directories or jar files. Local filesystem refers to the local
1222 filesystem of the node where the Oozie launcher is running. This can be configured in oozie-site.xml as :
1223  <verbatim>
1224   <!-- OOZIE -->
1225     <property>
1226         <name>oozie.service.ShareLibService.mapping.file</name>
1227         <value></value>
1228         <description>
1229             Sharelib mapping files contains list of key=value,
1230             where key will be the sharelib name for the action and value is a comma separated list of
1231             DFS or local filesystem directories or jar files.
1232             Example.
1233             oozie.pig_10=hdfs:///share/lib/pig/pig-0.10.1/lib/
1234             oozie.pig=hdfs:///share/lib/pig/pig-0.11.1/lib/
1235             oozie.distcp=hdfs:///share/lib/hadoop-2.2.0/share/hadoop/tools/lib/hadoop-distcp-2.2.0.jar
1236             oozie.spark=hdfs:///share/lib/spark/lib/,hdfs:///share/lib/spark/python/lib/pyspark.zip,hdfs:///share/lib/spark/python/lib/py4j-0-9-src.zip
1237             oozie.hive=file:///usr/local/oozie/share/lib/hive/
1238         </description>
1239     </property>
1240  </verbatim>
1241
1242 Example mapping file with local filesystem resources:
1243
1244  <verbatim>
1245     <property>
1246         <name>oozie.service.ShareLibService.mapping.file</name>
1247         <value>
1248             oozie.distcp=file:///usr/local/oozie/share/lib/distcp
1249             oozie.hcatalog=file:///usr/local/oozie/share/lib/hcatalog
1250             oozie.hive=file:///usr/local/oozie/share/lib/hive
1251             oozie.hive2=file:///usr/local/oozie/share/lib/hive2
1252             oozie.mapreduce-streaming=file:///usr/local/oozie/share/lib/mapreduce-streaming
1253             oozie.oozie=file://usr/local/oozie/share/lib/oozie
1254             oozie.pig=file:///usr/local/oozie/share/lib/pig
1255             oozie.spark=file:///usr/local/oozie/share/lib/spark
1256             oozie.sqoop=file:///usr/localoozie/share/lib/sqoop
1257         </value>
1258     </property>
1259   </verbatim>
1260
1261 If you are using local filesystem resources in the mapping file, make sure corresponding jars are already deployed to
1262 all the nodes where Oozie launcher jobs will be executed, and the files are readable by the launchers. To do this, you
1263 can extract Oozie sharelib TAR.GZ file in the directory of your choice on the nodes, and set permission of the files.
1264
1265 Oozie sharelib TAR.GZ file bundled with the distribution does not contain pyspark and py4j zip files since they vary
1266 with Apache Spark version. Therefore, to run pySpark using Spark Action, user need to specify pyspark and py4j zip
1267 files. These files can be added either to workflow's lib/ directory, to the sharelib or in sharelib mapping file.
1268
1269
1270 ---++ Oozie Coordinators/Bundles Processing Timezone
1271
1272 By default Oozie runs coordinator and bundle jobs using =UTC= timezone for datetime values specified in the application
1273 XML and in the job parameter properties. This includes coordinator applications start and end times of jobs, coordinator
1274 datasets initial-instance, and bundle applications kickoff times. In addition, coordinator dataset instance URI templates
1275 will be resolved using datetime values of the Oozie processing timezone.
1276
1277 It is possible to set the Oozie processing timezone to a timezone that is an offset of UTC, alternate timezones must
1278 expressed in using a GMT offset ( =GMT+/-####= ). For example: =GMT+0530= (India timezone).
1279
1280 To change the default =UTC= timezone, use the =oozie.processing.timezone= property in the =oozie-site.xml=. For example:
1281
1282 <verbatim>
1283 <configuration>
1284     <property>
1285         <name>oozie.processing.timezone</name>
1286         <value>GMT+0530</value>
1287     </property>
1288 </configuration>
1289 </verbatim>
1290
1291 *IMPORTANT:* If using a processing timezone other than =UTC=, all datetime values in coordinator and bundle jobs must
1292 be expressed in the corresponding timezone, for example =2012-08-08T12:42+0530=.
1293
1294 *NOTE:* It is strongly encouraged to use =UTC=, the default Oozie processing timezone.
1295
1296 For more details on using an alternate Oozie processing timezone, please refer to the
1297 [[CoordinatorFunctionalSpec#datetime][Coordinator Functional Specification, section '4. Datetime']]
1298
1299 #UberJar
1300 ---++ MapReduce Workflow Uber Jars
1301 For Map-Reduce jobs (not including streaming or pipes), additional jar files can also be included via an uber jar. An uber jar is a
1302 jar file that contains additional jar files within a "lib" folder (see
1303 [[WorkflowFunctionalSpec#AppDeployment][Workflow Functional Specification]] for more information). Submitting a workflow with an uber jar
1304 requires at least Hadoop 2.2.0 or 1.2.0. As such, using uber jars in a workflow is disabled by default. To enable this feature, use
1305 the =oozie.action.mapreduce.uber.jar.enable= property in the =oozie-site.xml= (and make sure to use a supported version of Hadoop).
1306
1307 <verbatim>
1308 <configuration>
1309     <property>
1310         <name>oozie.action.mapreduce.uber.jar.enable</name>
1311         <value>true</value>
1312     </property>
1313 </configuration>
1314 </verbatim>
1315
1316 ---++ Advanced/Custom Environment Settings
1317
1318 Oozie can be configured to use Unix standard filesystem hierarchy for its different files
1319 (configuration, logs, data and temporary files).
1320
1321 These settings must be done in the =bin/oozie-env.sh= script.
1322
1323 This script is sourced before the configuration =oozie-env.sh= and supports additional
1324 environment variables (shown with their default values):
1325
1326 <verbatim>
1327 export OOZIE_CONFIG=${OOZIE_HOME}/conf
1328 export OOZIE_DATA={OOZIE_HOME}/data
1329 export OOZIE_LOG={OOZIE_HOME}/logs
1330 export JETTY_OUT=${OOZIE_LOGS}/jetty.out
1331 export JETTY_PID=/tmp/oozie.pid
1332 </verbatim>
1333
1334 Sample values to make Oozie follow Unix standard filesystem hierarchy:
1335
1336 <verbatim>
1337 export OOZIE_CONFIG=/etc/oozie
1338 export OOZIE_DATA=/var/lib/oozie
1339 export OOZIE_LOG=/var/log/oozie
1340 export JETTY_PID=/tmp/oozie.pid
1341 </verbatim>
1342
1343 [[index][::Go back to Oozie Documentation Index::]]
1344
1345 </noautolink>