Elixir Ambience Installation Guide

Transcription

1 Elixir Ambience Installation Guide Release Elixir Technology Pte Ltd

2 Elixir Ambience Installation Guide: Release Elixir Technology Pte Ltd Published 2013 Copyright 2013 Elixir Technology Pte Ltd All rights reserved. Solaris, Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. Microsoft and Windows are trademarks of Microsoft Corporation.

3 Table of Contents 1. Introduction... 1 Pre-installation Instructions... 1 Software Requirements... 1 Hardware Requirements... 1 Preparations Installing Elixir Ambience... 3 Before Beginning... 3 For Linux... 3 Preparations... 3 Install Elixir Ambience on Linux... 4 Uninstall Elixir Ambience from Linux... 5 For Windows... 5 Install Elixir Ambience on Windows... 5 Uninstall Elixir Ambience from Windows... 6 For OSX... 6 Preparations... 6 Install Elixir Ambience on OSX... 7 Uninstall Elixir Ambience from OSX... 8 Get Started... 8 For Linux... 8 For Windows... 8 For OSX... 9 Login Ambience Dream Install Ambience Dream Get Started Login Set Up ZooKeeper Cluster Set Up Foxx Domain for LDAP Integration For Linux Preparations Install Ambience on Linux Uninstall Ambience from Linux Configure the Foxx Domain Configure the Foxx Domain with LDAP Authentication For Windows Get Started Login iii

4 List of Tables 2.1. /.elixirtech directories and permission owners Executable files on Linux /.elixirtech directories and permission owners Executable files on OSX Default Usernames and Passwords Default Usernames and Passwords /.elixirtech directories and permission owners Usernames and Passwords iv

5 Chapter 1 Introduction This book will walk you through Ambience installation scenarios, which covers the following contents: Pre-installation instructions: This helps you get well prepared before installing Ambience on your system, including software and hardware requirements, as well as basic configurations. Install Standalone Ambience: This illustrates how to install the standalone version of Ambience, and how to configure the eno domain. Ambience Dream: This describes how to get Ambience Dream working, which concentrates the complete Ambience experience in one zip package. Set Up ZooKeeper Cluster: This shows how to run a cluster of ZooKeeper nodes instead of standalone mode for high availability systems. Set Up Foxx Domain for LDAP Integration: This describes how to configure foxx domain if you wish to integrate Ambience via LDAP. Pre-installation Instructions Software Requirements The following software must be installed before getting started: Operating System: 32-bit or 64-bit Microsoft Windows, Linux, OSX and more. For Server and Designer: Oracle Java Platform Standard Edition 7. Either the Java Runtime Edition (JRE) or Java Development Kit (JDK) may be used. For Client: For full functionality, please choose a browser that supports both HTML5 and JavaScript. Hardware Requirements For Server and Designer: These can be installed on any 32-bit or 64-bit computing system, which is able to run Oracle Java Platform Standard Edition 7. RAM: The amount of RAM required depends on expected usage. A minimum RAM of 4GB is recommended for lightweight use. Free disk space: Prepare at least 2GB of free space on the hard disk drive. Preparations Update the IP address To get well prepared for an installation, manually update the IP address in /etc/hosts, or in \windows\system32\drivers\etc\hosts. Otherwise, you might receive an error message during installation, 1

6 Introduction saying Unable to connect to ZooKeeper domain eno. Incorrect IP address in /etc/hosts, or in \windows\system32\drivers\etc\hosts, might force you to abort the current process, uninstall Ambience and start all over again. 2

7 Chapter 2 Installing Elixir Ambience You can install Elixir Ambience on any computer running Oracle Java 7 or later. There is enhanced support for Debian (Linux) systems, Microsoft Windows and OSX machines. In the following discussion we will demonstrate the configuration of a single domain called "eno". The eno domain uses an internal authentication system so it requires no additional third-party components and hence no external configuration. Before Beginning Please install the appropriate Oracle Java runtime (or development environment) for your computer. You may choose either 64-bit or 32-bit versions depending on your hardware - Elixir Ambience will work fine with either kind. To ensure Java is correctly installed, open a command prompt and type java -version to check that the correct version of Java is available. A common problem is to have multiple versions of Java installed and the operating system finds the wrong one by default. This is because new versions of Java seldom automatically remove previous editions. For Linux Preparations Before installing Elixir Ambience on Linux, be sure to set up the ZooKeeper properties using either approach: ZooKeeper Properties Approach The ZooKeeper Properties Approach is more secure as it ties the ability to run services to a particular user account. Create three /.elixirtech directories and set permission owners as shown in the table below. Table 2.1. /.elixirtech directories and permission owners Directory /root/.elixirtech /home/elixir/.elixirtech /home/<user>/.elixirtech Permission Owner root elixir <user> In the /root/.elixirtech directory, create the zookeeper.properties file by copying the following contents into it. Fill in your host machine name and domain names. Leave the default ZooKeeper port as 2181 unless there is a clash with another service. The timeout indicates the heartbeat in milliseconds of the ZooKeeper cluster. If you need to configure a cluster, add more hosts here: 3

8 Installing Elixir Ambience hosts=<machine-name>:2181 timeout=5000 domain.eno=<key> Copy the zookeeper.properties file into the other directories as shown in the table. The three copies of zookeeper.properties should contain exactly the same contents. Once the contents change, you should modify the three copies. Note If you need to add more domains, follow the syntax below. <name> should only include letters and numbers, while <key> can include any characters. Domain name and key must be set before the domain is created, otherwise the domain is not accessible. Once set, the key cannot be changed. If a new key is needed, you need to export the contents of the domain using the old key, configure a new domain with a new key and import the contents with the new key in place. domain.<name>=<key> System Preferences Approach The System Preferences Approach is simpler as it sets the values for all users. Using this approach, you need to maintain only one copy of file. Although this approach makes editing easier, it is not as secure as the ZooKeeper Properties Approach. Open the install.sh file with Text Editor. Uncomment the following contents to use system preferences instead of zookeeper.properties. Please note that you need to run as an administrator with "sudo" commands to alter the values: #sudo./elx-zookeeper-init.sh --hosts "$<host-name>:2181" --timeout 5000 #sudo./elx-zookeeper-init.sh --add $<domain> <domain-name> #./elx-zookeeper-init.sh --display If there is a zookeeper.properties file present for a particular user account, it will be used instead of any system preferences. Install Elixir Ambience on Linux To install Ambience on Linux, complete the following steps: 1. Open the Terminal window. Change to the directory that contains the install.sh file. 2. Type the following command lines to change the mode of the install.sh file to be executable: chmod +x install.sh 3. Type the following command lines to run the install.sh file. The installation process start:./install.sh 4. Look out for any error messages which might occur if existing services use the default ports that Elixir Ambience needs. Install will create a new "elixir" user which will be used to run all services. Services will automatically start each time the computer is switched on. 5. Obtain and add any necessary JDBC drivers to the /var/elixir/lib folder. 4

9 Installing Elixir Ambience 6. If you have added new jars to the lib folder, run./stop.sh and then./start.sh for them to be included in the restarted environment. Elixir Ambience is successfully installed. Note If you receive an error message during installation, saying Unable to connect to ZooKeeper domain eno, you might have to manually update IP address in the /etc/hosts file. Uninstall Elixir Ambience from Linux To uninstall Ambience from Linux, complete the following steps: 1. Open the Terminal window. Change to the directory that contains the uninstall.sh file. 2. Type the following command line to change the mode of the uninstall.sh file to be executable: chmod +x uninstall.sh 3. Type the following command line to run the uninstall.sh file:./uninstall.sh Elixir Ambience is successfully uninstalled. On Linux operating system, you can also run the following files: Table 2.2. Executable files on Linux File Description reinstall.sh This file uninstalls and then reinstalls the program. User configurations and repository contents are preserved. This script is useful to upgrade your installation when new versions are available. start.sh stop.sh wipe.sh For Windows This file starts all the services. This file stops all the services. This file wipes all zookeeper and repository contents. All user configuration will be deleted. You should only use this script after running uninstall. Install Elixir Ambience on Windows To install Ambience on a 32-bit or 64-bit Windows operating system, complete the following steps: 1. Define a system variable ELIXIR_HOME, which points to the installation directory. You can use any folder except those under \Program Files or \User. C:\ElixirAmbience is a common choice. 2. Click Start > Command Prompt. The Command Prompt window opens. Type the following command lines to create the <user-home>\.elixirtech and C:\.elixirtech directories. Fill in your <user-home> directory to continue: cd <user-home> md.elixirtech 5

10 Installing Elixir Ambience cd C:\ md.elixirtech 3. Set up the zookeeper.properties file in the <user-home>\.elixirtech directory. The following contents show an example. Fill in your host machine name and domain names. Leave the default ZooKeeper port as 2181 unless there is a clash with another service. The timeout indicates the heartbeat in milliseconds of the ZooKeeper cluster. If you need to configure a cluster, add more hosts here: hosts=<machine-name>:2181 timeout=5000 domain.eno=<key> 4. Put a copy of the zookeeper.properties file in the C:\.elixirtech directory. 5. Open a command prompt and navigate to the folder holding install32.bat (for 32-bit) or install.bat (for 64-bit) file. Run one of these two batch files as appropriate. Running from a command prompt is preferred because any errors will remain visible if the installer halts unexpectedly. If there are messages asking if you will allow the Elixir programs to access your computer, click Allow to proceed. Note If you receive the Address not supported by protocol family: connect error message, click Start > All Programs > Accessories. Right-click Notepad and select Run as administrator. In the Notepad window, open the %SystemRoot%\system32\drivers\etc\hosts file, and explicitly name your computer. Fill your host machine name and IP address into the following contents and run the installation again localhost <IP-address> <machine-name> Ambience is successfully installed. Uninstall Elixir Ambience from Windows For OSX To uninstall Ambience from a Windows operating system, complete the following steps: 1. Double-click the uninstall32.bat (for 32-bit) or uninstall.bat (for 64-bit) file. The Command Prompt window opens and after the script completes will be automatically closed. 2. If there are messages asking if you will allow the Elixir programs to access your computer, click Allow to proceed. Ambience is successfully uninstalled. Preparations Before installing Elixir Ambience on OSX, be sure to set up the ZooKeeper properties: Create two /.elixirtech directories and set permission owners as shown in the table below. 6

11 Installing Elixir Ambience Table 2.3. /.elixirtech directories and permission owners Directory /home/elixir/.elixirtech /home/<user>/.elixirtech Permission Owner elixir <user> In both /.elixirtech directories, create the zookeeper.properties file by copying the following contents into it. Fill in your host machine name and domain names. Leave the default ZooKeeper port as 2181 unless there is a clash with another service. The timeout indicates the heartbeat in milliseconds of the ZooKeeper cluster. If you need to configure a cluster, add more hosts here: hosts=<machine-name>:2181 timeout=5000 domain.eno=<key> Both copies of zookeeper.properties should contain exactly the same contents. Once the contents change, you should modify both copies. Note If you need to add more domains, follow the syntax below. <name> should only include letters and numbers, while <key> can include any characters. Domain name and key must be set before the domain is created, otherwise the domain is not accessible. Once set, the key cannot be changed. If a new key is needed, you need to export the contents of the domain using the old key, configure a new domain with a new key and import the contents with the new key in place. domain.<name>=<key> Install Elixir Ambience on OSX To install Ambience on OSX, complete the following steps: 1. Open the Terminal window. Change to the directory that contains the install.sh file. 2. Type the following command lines to make the scripts in this directory executable: chmod +x install.sh 3. Type the following command lines to run the install.sh file. The installation process start: sudo./install.sh 4. Look out for any error messages which might occur if existing services use the default ports that Elixir Ambience needs. Services will automatically start each time the computer is switched on. 5. Obtain and add any necessary JDBC drivers to the /var/elixir/lib folder. 6. If you have added new jars to the lib folder, run sudo./stop.sh and then sudo./start.sh for them to be included in the restarted environment. Elixir Ambience is successfully installed. Note If you receive an error message during installation, saying Unable to connect to ZooKeeper domain eno, you might have to manually update IP address in the /etc/hosts file. 7

12 Installing Elixir Ambience Uninstall Elixir Ambience from OSX To uninstall Ambience from OSX, complete the following steps: 1. Export any repository contents that you wish to keep. 2. Open the Terminal window. Change to the directory that contains the uninstall.sh file. 3. Type the following command line to change the mode of the uninstall.sh file to be executable: chmod +x uninstall.sh 4. Type the following command line to run the uninstall.sh file: sudo./uninstall.sh This will stop all services and delete the program files. User files will still remain in case you with to reinstall or upgrade. 5. To remove all user files as well, run sudo./wipe.sh after running the uninstall.sh file. Elixir Ambience is successfully uninstalled. On OSX operating system, you can also run the following files: Table 2.4. Executable files on OSX File Description reinstall.sh This file uninstalls and then reinstalls the program. User configurations and repository contents are preserved. This script is useful to upgrade your installation when new versions are available. start.sh stop.sh wipe.sh Get Started For Linux This file starts all the services. This file stops all the services. This file wipes all zookeeper and repository contents. All user configuration will be deleted. You should only use this script after running uninstall. To start Domain Manager, Repertoire and Repository GUI on Linux, open the /opt/elixir/desktop/ directory and double-click the icons. These icons can be added to menus and desktop panels for a quick start. Alternatively, you can start the programs with the following command lines: /opt/elixir/domainman/elx-domainman.sh /opt/elixir/repertoire/elx-repertoire.sh /opt/elixir/repository-gui/elx-repository-gui.sh For Windows To start Domain Manager on Windows (32-bit or 64-bit), open the %ELIXIR_HOME%\opt\elixir\domainman\ directory and double-click the elx-domainman-32.exe or elx-domainman-64.exe file. 8

13 Installing Elixir Ambience For OSX Login To start Repertoire on Windows, open the %ELIXIR_HOME%\opt\elixir\repertoire\ directory and double-click the elx-repertoire-32.exe or elx-repertoire-64.exe file. To start Repository GUI on Windows, open the %ELIXIR_HOME%\opt\elixir\repository-gui\ directory and double-click the elx-repository-gui-32.exe or elx-repository-64.exe file. For a quick start, you can drag a shortcut of the.exe files to the desktop. After the installation, Domain Manager, Repertoire and Repository GUI are available in the /opt/elixir/desktop/ directory. You can start the programs with the following command lines: /opt/elixir/domainman/elx-domainman.sh /opt/elixir/repertoire/elx-repertoire.sh /opt/elixir/repository-gui/elx-repository-gui.sh When you are trying to log into Ambience Domain Manager, Designer, Repository GUI, or Web Interface, you have to enter the correct server name, port name, domain name, username and password when prompted. Server name: Please enter the machine name or exact IP address, and avoid using localhost here. Port number: Please enter Domain name: Use eno. Username and password: The default usernames and passwords are shown in the following table, which can be changed to your own. Please note that if you forget the altered values, they cannot be recovered. Table 2.5. Default Usernames and Passwords Program Domain Username Password Domain Manager eno domadmin da Designer eno admin sa Repository GUI eno admin sa Web Interface eno admin sa 9

14 Chapter 3 Ambience Dream Ambience Dream contains the complete Ambience experience. The installation of Ambience Dream is simple and straightforward on a clean machine, and the supported operating systems include Debian, Windows and OSX. Ambience Dream is easy to use and saves your time and efforts, without the need of running any services or setting up any user accounts. Install Ambience Dream Ambience Dream installation starts with unzipping the elx-dream-install.zip file, which resides in the /dream folder. Read on for more detailed instructions. 1. Decompress /dream/elx-dream-install.zip in to a folder on your machine. It is recommended to avoid using the Program Files folder on Windows, because this folder requires more restrictive permissions. Note If Ambience has not been installed on your machine, skip the optional steps below. 2. Optional: If Ambience is already running on your machine, edit /.elixirtech/zookeeper.properties by adding the following line: domain.dream=tangerine You can use any password (tangerine is our choice). If you don't have a zookeeper.properties file, no action is required, because it will be created for you. 3. Optional: If Ambience services are running, please stop the services before you proceed. This will prevent zookeeper conflicts as the standalone version includes its own zookeeper. 4. Change the directory (cd) to the /bin directory and run init.sh or init.bat, according to the operating system. This will install the zookeeper default properties (including license) from tmp/zk, and then install the standard filesystems (ElixirSamples and so on) from tmp/dacapo. The domain for the Dream solution is dream. If you choose to use the Dream solution, use dream for a domain wherever you are prompted. The tmp/ folder is no longer used after initialization. You have the option to delete the tmp/ folder. You can also keep this folder if you wish to reset later. 5. After the init.sh or init.bat file finishes running, Ambience Dream is successfully installed. Get Started When you complete the installation of Ambience Dream, run startserver.sh or startserver.bat to start all of Ambience in a single JVM. There is only one Job Engine available in Ambience Dream, which cannot be altered. 10

15 Ambience Dream Login After startserver.sh or startserver.bat finishes loading, you can also run startdesigner or startdomainman (.sh or.bat) to access Designer or Domain Manager. In order to view Ambience Dream Web Interface (hereinafter referred to as "Web Interface"), visit the following URL: Note The Web Interface uses a different port number 8087, instead of All services run within the same JVM, therefore no other ports are in use (other than audit and zookeeper on 8066 and 2181 respectively). Ambience Dream supports the same functionalities with the Standalone Ambience, except that the functionalities are being limited to a single Job Engine. When you are trying to log into Ambience Domain Manager, Designer, or Web Interface, you have to enter the correct server name, port number, domain name, username and password when prompted. Server name: Please enter localhost. Port number: Please enter Domain name: Use dream for a domain wherever you are prompted. Username and password: The default usernames and passwords are shown in the following table, which can be changed to your own. Please note that if you forget the altered values, they cannot be recovered. Table 3.1. Default Usernames and Passwords Program Domain Username Password Domain Manager dream domadmin da Designer dream admin sa Web Interface dream admin sa 11

16 Chapter 4 Set Up ZooKeeper Cluster The elx-zookeeper-cluster package is available in the Ambience installation files. This is an alternate package to use, when you need to run a cluster of ZooKeeper nodes instead of standalone mode for high availability systems. It is recommended to run at least three ZooKeeper nodes on three separate machines to meet the high availability requirements. If there are sufficient resources, it is recommended to run five ZooKeeper nodes, which allows one node to be taken down for planned maintenance without affecting the availability. Note The cluster needs to be stopped and reconfigured. It is currently a limitation of ZooKeeper that new nodes cannot be added to a running cluster. You can install either elx-zookeeper or elx-zookeeper-cluster. If you install both packages, neither will work, because the two packages contain many files in common. Both packages install a service called elx-zookeeper. Therefore, there is a single service name to use when starting or stopping the service, no matter if the system is clustered or standalone. The elx-zookeeper-cluster package has three key differences from elx-zookeeper: 1. The service does not start automatically upon install, which provides more time for manual configuration. 2. The ZooKeeper configuration file contains an example of the cluster configuration, which needs to be edited. 3. The ZooKeeper class entry point in /etc/init.d/elx-zookeeper is QuorumPeerMain, so that the node knows to look for other members of the cluster and elect a leader. In the following example, three machines called VM2, VM3, and VM4 are configured to automate the creation of a ZooKeeper cluster. These machines have Java installed and SSH certificates, so that files could be transferred without repeated entry of passwords. The following script called cloud-zk.sh can automate the process: #!/bin/bash set -o nounset sudo echo "cloud-zk" "$1" mkdir tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ dist/elx-arch_2.5-1_all.deb tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ dist/elx-zookeeper-cluster_2.5-1_all.deb tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ cloud-zoo.cfg tmp sudo dpkg --install tmp/elx-arch_2.5-1_all.deb sudo dpkg --install tmp/elx-zookeeper-cluster_2.5-1_all.deb echo "$1" sudo tee /var/elixir/zookeeper/myid sudo cp tmp/cloud-zoo.cfg /etc/elixir/zookeeper/zoo.cfg sudo service elx-zookeeper start 12

17 Set Up ZooKeeper Cluster sleep 10 echo ruok nc echo stat nc The following ZooKeeper configuration file called cloud-zoo.cfg will be installed on each of the nodes: # The number of milliseconds of each tick ticktime=2000 # The number of ticks that the initial # synchronization phase can take initlimit=10 # The number of ticks that can pass between # sending a request and getting an acknowledgement synclimit=5 # the directory where the snapshot is stored. datadir=/var/elixir/zookeeper # the port at which the clients will connect clientport=2181 #original default is 10, changed to 50 to allow more services to run on a single machine (change to 0 for no limit) maxclientcnxns=50 server.1=vm2:2888:3888 server.2=vm3:2888:3888 server.3=vm4:2888:3888 The only difference between cloud-zoo.cfg and zoo.cfg is the the three lines at the bottom, which define the names of the three servers in the cluster. Note The zoo.cfg file is located in /etc/elixir/zookeeper/. The following script is first copied from the main machine knockshinnie in this example to each node in the cluster: scp cloud-zk.sh VM2:/home/jon scp cloud-zk.sh VM3:/home/jon scp cloud-zk.sh VM4:/home/jon Then run the script on each machine, with a different identifier 1, 2, 3. For example, run the following script with the identifier 1 on VM2:./cloud-zk.sh 1 Be sure to use the number as defined in the cloud-zoo.cfg for each server. A breakdown of the script follows. This tells bash to fail if a variable is undefined for example, if you forget to specify an identifier. set -o nounset The following script echos the configuration using sudo, which means that if any password is needed, it will be prompted right at the start (without this, the script might pause later waiting for a password). sudo echo "cloud-zk" "$1" The following script makes tmp directory and copy the three essential files across. Be sure to alter the paths for your machine. mkdir tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ 13

18 Set Up ZooKeeper Cluster dist/elx-arch_2.5-1_all.deb tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ dist/elx-zookeeper-cluster_2.5-1_all.deb tmp scp knockshinnie:/home/jon/code/develop/ambience/system/debian/ cloud-zoo.cfg tmp The following script installs the two debian files. Make sure elx-zookeeper has not been installed to avoid conflict. sudo dpkg --install tmp/elx-arch_2.5-1_all.deb sudo dpkg --install tmp/elx-zookeeper-cluster_2.5-1_all.deb This writes the identifier, e.g. 1, 2, 3 into the myid file for ZooKeeper to read: echo "$1" sudo tee /var/elixir/zookeeper/myid The following script copies cloud-zoo.cfg over the default zoo.cfg: sudo cp tmp/cloud-zoo.cfg /etc/elixir/zookeeper/zoo.cfg The following script starts the service. The service name is elx-zookeeper, same as the name in the standalone Ambience. sudo service elx-zookeeper start It takes a while for the ZooKeeper to start. You need to check whether it is running OK. sleep 10 echo ruok nc echo stat nc When the script is run on the first machine, it will likely answer, This ZooKeeper instance is not currently serving requests. It is because the first machine is waiting for another member of the cluster to start. When you start the second machine, it will report that it is either a leader or a follower (depending on which one wins the vote). When you start the third machine, it will likely report that it is a follower. You can re-run these status checks at any time to verify the cluster is running, even from a different machine if the ports are not blocked by firewalls: telnet VM Trying Connected to VM2. Escape character is '^]'. ruok imokconnection closed by foreign host. The response to ruok is imok, as shown on the last line. The stat command returns more information, as shown in the following. Note The node count is the number of data nodes in the ZooKeeper store, not the number of ZooKeeper nodes. 14

19 Set Up ZooKeeper Cluster telnet VM Trying Connected to VM2. Escape character is '^]'. stat Zookeeper version: , built on 02/23/ :27 GMT Clients: / :48891[0](queued=0,recved=1,sent=0) Latency min/avg/max: 0/0/0 Received: 4 Sent: 3 Outstanding: 0 Zxid: 0x0 Mode: follower Node count: 4 Connection closed by foreign host. Edit the zookeeper.properties file to make it know about the cluster. There may be several copies of this file, under.elixirtech/ in your home directory, elixir home directory and root home directory. They all need to include the cluster information: hosts=vm2:2181,vm3:2181,vm4: rest unchanged Proceed to add the additional services you need and install data into your ZooKeeper cluster. 15

20 Chapter 5 Set Up Foxx Domain for LDAP Integration When you have explored the eno domain, you may wish to integrate Ambience more tightly with your existing infrastructure, for example to share the same user identities and groups with other tools through LDAP or Active Directory. To demonstrate this integration, we will set up a new domain called foxx which will integrate with an existing LDAP service. In the following we will emphasize on the configuration of foxx domain. The foxx domain is completely distinct from the eno domain. The foxx domain adopts LDAP authentication system, which requires connecting to an LDAP server and setting up the user group. For Linux In this section, we will focus on how to set up Foxx Domain on the Linux operating system. Preparations Before installing Ambience on Linux, be sure to set up the ZooKeeper properties using either approach: ZooKeeper Properties Approach The ZooKeeper Properties Approach is more secure as it ties the ability to run services to a particular user account. Create three /.elixirtech directories and set permission owners as shown in the table below. Table 5.1. /.elixirtech directories and permission owners Directory /root/.elixirtech /home/elixir/.elixirtech /home/<user>/.elixirtech Permission Owner root elixir <user> In the /root/.elixirtech directory, create the zookeeper.properties file by copying the following contents into it. Fill in your host machine name and domain names. Leave the default ZooKeeper port as 2181 unless there is a clash with another service. The timeout indicates the heartbeat in milliseconds of the ZooKeeper cluster. If you need to configure a cluster, add more hosts here: hosts=<machine-name>:2181 timeout=5000 domain.foxx=<key> Copy the zookeeper.properties file into the other directories as shown in the table. The three copies of zookeeper.properties should contain exactly the same contents. Once the contents change, you should modify the three copies. 16

21 Note If you need to add more domains, follow the syntax below. <name> should only include letters and numbers, while <key> can include any characters. Domain name and key must be set before the domain is created, otherwise the domain is not accessible. Once set, the key cannot be changed. If a new key is needed, you need to export the contents of the domain using the old key, configure a new domain with a new key and import the contents with the new key in place. domain.<name>=<key> System Preferences Approach The System Preferences Approach is simpler as it sets the values for all users. Using this approach, you need to maintain only one copy of file. Although this approach makes editing easier, it is not as secure as the ZooKeeper Properties Approach. Open the install.sh file with Text Editor. Uncomment the following contents to use system preferences instead of zookeeper.properties. Please note that you need to run as an administrator with "sudo" commands to alter the values: #sudo./elx-zookeeper-init.sh --hosts "$<host-name>:2181" --timeout 5000 #sudo./elx-zookeeper-init.sh --add $<domain> <domain-name> #./elx-zookeeper-init.sh --display If there is a zookeeper.properties file present for a particular user account, it will be used instead of any system preferences. Install Ambience on Linux To install Ambience on Linux, complete the following steps: 1. Open the Terminal window. Change to the directory that contains the install.sh and foxx-install.sh files. 2. Type the following command lines to change the mode of the install.sh and foxx-install.sh files to be executable: chmod +x install.sh chmod +x foxx-install.sh Set Up Foxx Domain for LDAP Integration 3. Type the following command lines to run the install.sh and foxx-install.sh files. The installation process will get started:./install.sh./foxx-install.sh 4. Look out for any error messages which might occur if existing services use the default ports that Elixir Ambience needs. Install will create a new "elixir" user which will be used to run all services. Services will automatically start each time the computer is switched on. 5. Obtain and add any necessary JDBC drivers to the /var/elixir/lib folder. 6. If you have added new jars to the lib folder, run./stop.sh and then./start.sh for them to be included in the restarted environment. Ambience is successfully installed. 17

22 Note If you receive an error message during installation, saying Unable to connect to ZooKeeper domain foxx, you might have to manually update IP address in the /etc/hosts file. Uninstall Ambience from Linux The uninstallation of Ambience with foxx domain is quite similar with the uninstallation of Ambience with eno domain. If you wish to uninstall Ambience after setting up foxx domain, refer to the section called Uninstall Elixir Ambience from Linux. Configure the Foxx Domain Set Up Foxx Domain for LDAP Integration Configuring the foxx domain follows the same steps with configuring the eno domain, where the domain name eno should be replaced with foxx in each case. There are a few additional changes required, where the domain name is included in some configuration files and needs editing after the installation. Procman: Each Procman service supports multiple domains. You need to specify which domains will be handled by editing the file /etc/elixir/procman/domains.xml. This file contains the following information by default: <domains> <domain name="eno" hostname="/host/default" clone="false"/> </domains> You need to add an additional line for the foxx domain: <domains> <domain name="eno" hostname="/host/default" clone="false"/> <domain name="foxx" hostname="/host/default" clone="false"/> </domains> The host names can be either the same or different, because they are in separate domain trees and won't clash. After this change is made, Procman will manage job engines defined under /host/default for the foxx domain as well. Procman will automatically apply this change, and restarting the service is not required. However, if you remove a domain from the configuration file, the Procman service needs a restart. Scheduler: The Scheduler service also supports multiple domains. You need to specify which domains will be handled by editing the file /etc/elixir/scheduler/domains.xml. This file contains the following information by default: <domains> <domain name="eno" module="/module/scheduler"/> </domains> You need to add an additional line for the foxx domain: <domains> <domain name="eno" module="/module/scheduler"/> <domain name="foxx" module="/module/scheduler"/> </domains> Configure the Foxx Domain with LDAP Authentication This section demonstrates how to configure the foxx domain with LDAP authentication. Before getting started, be sure to meet the following prerequisites: 18

23 You have a working domain foxx A LDAP server is running The user group has been set up Set Up Foxx Domain for LDAP Integration 1. Change the login realm of the domain. Use the Domain Manager to edit the realm value on path, /foxx/module/identity/realm, on the domain tree. Use the Edit Content dialog to change the realm node value from "default" to "ldap". 2. Modify the LoginModule configuration to setup a LDAP server binding. Edit jaas-login.conf file located in /etc/elixir/identity for a Linux installation. Uncomment or add the below section to jass-login.config: ldap { com.elixirtech.v2.authldap.ldaploginmodule required configpath="/etc/elixir/identity/ldap.xml" debug="true"; }; 3. Change the configpath to point to the ldap server binding configuration file. For foxx domain, the path is "/etc/elixir/identity/ldap.foxx.xml". This file has the pre-configured setting to bind to an Apache Directory server but you will need to modify the host location. Here is an example of an Active Directory server (Windows Server 2008) configuration (as in ldap.active-directory.xml) and a sample start and stop script (as in apacheds) for the Apache Directory server. You can use sysv-rc-conf to configure the run level on Ubuntu. 4. You can allow user to change password on Ambience user portal page by uncommenting two entries in "/elixir/identity/web.xml". They are servlet and servlet-mapping for usergroupldap-user as <servlet> <servlet-name>usergroupldap-user</servlet-name> <servlet-class>com.elixirtech.v2.authldap.web.userservlet </servlet-class> </servlet> and <servlet-mapping> <servlet-name>usergroupldap-user</servlet-name> <url-pattern>/usergroupldap/user/*</url-pattern> </servlet-mapping> 5. Update the zookeeper node "/url/id/changepassword" to a new URL, following the syntax " Here is an URL example, " 6. Update the entry in ldap.foxx.xml to indicate the ldap attribute that is used for password change. <user dn="ou=user,o=elite" filter="cn=*" return-attribute="uid"> <!-- password attribute option allow password change --> <option name="password-attribute" value="userpassword"/> For Windows Active Directory, you have to set the ldap bind to use ssl otherwise the access to the LDAP server entries is read only (as in ldap.active-directory.ssl.xml). 19

24 Set Up Foxx Domain for LDAP Integration For Windows If you wish to set up Foxx Domain on Windows, you have to modify the install.bat or install32.bat file before running the Ambience installation. Open intall.bat or install32.bat with a Text Editor and modify the DOMAIN= definition by replacing the default "eno" with "foxx". The installation of Ambience with foxx domain on Windows is similar with the installation of Ambience with eno domain. Refer to the section called Install Elixir Ambience on Windows for more information. The difference is in the zookeeper.properties file. Please be sure to modify the zookeeper.properties file to change domain.eno to domain.foxx and filling into a different key. The following contents show an example. Fill in your host machine name and domain names. Leave the default ZooKeeper port as 2181 unless there is a clash with another service. The timeout indicates the heartbeat in milliseconds of the ZooKeeper cluster. If you need to configure a cluster, add more hosts here: hosts=<machine-name>:2181 timeout=5000 domain.foxx=<key> To uninstall Ambience after setting up foxx domain, refer to the section called Uninstall Elixir Ambience from Windows for more details. Get Started Login After the setup of foxx domain is complete, start exploring Ambience Domain Manger, Designer, Repository GUI, or Web Interface by referring to the section called Get Started. When you are trying to log into Ambience Domain Manager, Designer, Repository GUI, or Web Interface, you have to enter the correct server name, port name, domain name, username and password when prompted. Server name: Please enter the machine name or exact IP address, and avoid using localhost here. Port number: Please enter Domain name: Use foxx. Username and password: The default usernames and passwords are shown in the following table, which can be changed to your own. Please note that if you forget the altered values, they cannot be recovered. Table 5.2. Usernames and Passwords Program Domain Manager Designer Repository GUI Web Interface Username domadmin admin admin admin Password da sa sa sa 20