Setting up ZooKeeper
When using Dragon Voice services (engines), you must install Apache ZooKeeper and configure it to connect to Resource Manager and the engines.
- You can install ZooKeeper on any host. This includes hosts with no Speech Suite components. The host must communicate with the Resource Manager host.
- For redundancy, you can install multiple Zookeeper instances on multiple hosts. Use the Zookeeper instructions to configure interoperation among the Zookeeper servers. Typically this means having an odd number of servers for “election” purposes (for example, 1, 3, 5, and so on). For testing and development purposes, a single ZooKeeper host is sufficient. For production environments, Nuance (and Apache) recommends at least three ZooKeeper hosts to ensure that the ZooKeeper service stays active.
- By default, the connection between Zookeeper and Resource Manager does not use authentication. For maximum security, see Configuring authentication.
Note: You cannot connect one Zookeeper to two different Speech Suite installations.
Preparation
Before you begin:
- Download the Apache ZooKeeper package on each host and extract it.
- Use the Apache ZooKeeper documentation for full instructions, including system requirements.
- Install 64-bit Java on each ZooKeeper host. If installing Zookeeper on a Speech Suite host, see the Speech Suite release notes for details about sharing the Java JRE.
-
IMPORTANT—You must configure Zookeeper's Java system property admin.serverPort to a non-default value. (The default port 8080 conflicts with the Management Station.) Alternatively, you can disable the admin feature with admin.enableServer=false in the zoo.cfg file.
Linux procedure
- Make a copy of the provided configuration file: /zookeeper/conf/zoo_sample.cfg
- Rename the copied file. For example: zoo.cfg
- Create a data directory, using a name of your choosing, in the installation directory.
- Edit these settings in zoo.cfg:
dataDir
: Enter the path to your data directory. For example:dataDir=/zookeeper/zookeeperDataDir
server.1
: Enter the hostname of your ZooKeeper host. For example:server.1=zookeeper-hostname:2888:3888
Note: If you have more than one ZooKeeper host, edit the zoo.cfg on each host and add
server.x
settings (incrementing the server .x value for each host). For example:
server.1=[server1-hostname]:2888:3888
server.2=[server2-hostname]:2888:3888
server.3=[server3-hostname]:2888:3888clientPort
: Enter the listening port for client connections.
- Save zoo.cfg.
- Start the ZooKeeper server:
> /zookeeper/bin ./zkServer.sh start
Tip: You can check this log file for any errors /zookeeper
/bin/zookeeper.out
- Start the ZooKeeper client, which switches to the ZooKeeper prompt:
> ./zkCli.sh
- Type
quit
to exit the client. The ZooKeeper configuration is now complete. - Configure the zookeeper : servers property of the Nuance Resource Manager service to point to the IP address and port of each ZooKeeper host.
Note: The list of ZooKeeper addresses must match the list of ZooKeeper hosts for Resource Manager to successfully connect to them.
Windows procedure
Repeat these steps on every Zookeeper host:
- Make a copy of the provided configuration file \zookeeper\conf\zoo_sample.cfg
- Rename the copied file. For example: zoo.cfg
- Create a data directory, using a name of your choosing, in the installation directory. For example: C:\zookeeper\zookeeperDataDir
- Edit these settings in zoo.cfg:
dataDir
: Enter the path to your data directory. For example:dataDir=C:\zookeeper\zookeeperDataDir
server.1
: Enter the hostname of your ZooKeeper host. For example:server.1=zookeeper-hostname:2888:3888
Note: If you have more than one ZooKeeper host, edit the zoo.cfg on each host and add
server.x
settings (incrementing the server .x value for each host). For example:
server.1=[server1-hostname]:2888:3888
server.2=[server2-hostname]:2888:3888
server.3=[server3-hostname]:2888:3888clientPort
: Enter the listening port for client connections.
- Save zoo.cfg.
- Open the Environment Variables dialog.
- Click New, under System Variables, and add the following variable, where the value is the path to your ZooKeeper directory:
ZOOKEEPER_HOME = C:\zookeeper
- Select Path, under System Variables, click Edit and add the following value to the list:
%ZOOKEEPER_HOME%\bin;
- Open a command prompt.
- Type
zkServer.cmd
to start the ZooKeeper server and do not close the command prompt, which stops the ZooKeeper server.Note: The command prompt window must remain open for the ZooKeeper server to stay active.
- Configure the zookeeper : servers property of the Nuance Resource Manager service to point to the IP address and port of each ZooKeeper host.
Note: The list of ZooKeeper addresses must match the list of ZooKeeper hosts for Resource Manager to successfully connect to them.
Configuring authentication
Authentication is not enabled between ZooKeeper and Resource Manager by default. This opens a security risk if you host multiple customers on your network because code running on any server can query and modify nodes registered with ZooKeeper (including Resource Manager). For example, there's a risk of redirection of a customer's voice data towards fraudulent Dragon Voice instances.
Note: In the following procedure, follow your standard operating procedures to stop and start services and edit their properties. In other words, use Management Station (if using Management Station at your site) or use scripts or command line operations to affect these changes.
To enable authentication to ZooKeeper :
-
Stop the Dragon Voice engines: Krypton, NLE, and NTpE and wait a short time for Resource Manager to remove their corresponding entries from ZooKeeper. (Use
zkCli.sh
orzkCli.bat
to confirm nodes KRYPTON, NLE and NTPE are empty.) -
Stop all Resource Manager services.
-
Use the ZooKeeper command line client to delete the ZooKeeper NRM nodes. Run these commands in
zkCli.sh
orzkCli.bat:
delete /RM
delete /Engines/KRYPTON
delete /Engines/NLE
delete /Engines/NTPE
delete /Engines
-
Add the following ZooKeeper properties to the Resource Manager service configuration. Specify any values for username and authenticationcode, and use the same values if you run a secondary Resource Manager. (If running services without Management Station, add these properties to the ZooKeeper section of every User-nrmxx.yaml file.)
authUser: 'username'
authCode: 'authenticationcode'
Note: The username and authenticationcode are case sensitive.
Example configuration in the ZooKeeper section of a User-nrmxx.yaml file:
zookeeper:
servers:
- 'hostname:port'
authUser: 'nuance'
authCode: 'mypassword' - Start Resource Manager.
- Start the Dragon Voice engines.
To inspect NRM nodes in the future (after authentication is enabled), you must run the following command in the ZooKeeper command line client. Substitute the configured values for authUser and authCode:
addauth digest authUser:authCode