Issue 705: Installation documentation
Fix errors in installer.md. Reorganize and expand installer.md
slightly. Add check for txn_log_dir to 'managix validate -c'.
Change-Id: Ib3396425c372c4970b86a792678e26f2e37b3630
Reviewed-on: http://fulliautomatix.ics.uci.edu:8443/154
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Reviewed-by: Ian Maxon <imaxon@uci.edu>
diff --git a/asterix-doc/src/site/markdown/install.md b/asterix-doc/src/site/markdown/install.md
index 0b0d364..bcc63f4 100644
--- a/asterix-doc/src/site/markdown/install.md
+++ b/asterix-doc/src/site/markdown/install.md
@@ -286,8 +286,8 @@
</working_dir>
<master_node>
<id>master</id>
- <client-ip>127.0.0.1</client-ip>
- <cluster-ip>127.0.0.1</cluster-ip>
+ <client_ip>127.0.0.1</client_ip>
+ <cluster_ip>127.0.0.1</cluster_ip>
<client_port>1098</client_port>
<cluster_port>1099</cluster_port>
<http_port>8888</http_port>
@@ -301,13 +301,13 @@
We shall next explain the components of the cluster configuration XML file.
#### (1) Defining nodes in AsterixDB runtime ####
-The single-machine AsterixDB instance configuration that is auto-generated by Managix (using the `configure` command) involves a master node (CC) and a worker node (NC). Each node is assigned a unique id and provided with an ip address (called ''cluster-ip'') that maps a node to a physical machine. The following snippet from the above XML file captures the master/worker nodes in our AsterixDB installation.
+The single-machine AsterixDB instance configuration that is auto-generated by Managix (using the `configure` command) involves a master node (CC) and a worker node (NC). Each node is assigned a unique id and provided with an ip address (called ''cluster_ip'') that maps a node to a physical machine. The following snippet from the above XML file captures the master/worker nodes in our AsterixDB installation.
<master_node>
<id>master</id>
- <client-ip>127.0.0.1</client-ip>
- <cluster-ip>127.0.0.1</cluster-ip>
+ <client_ip>127.0.0.1</client_ip>
+ <cluster_ip>127.0.0.1</cluster_ip>
<client_port>1098</client_port>
<cluster_port>1099</cluster_port>
<http_port>8888</http_port>
@@ -334,15 +334,15 @@
<td>IP address of the machine to which a node maps to. This address is used for all internal communication between the nodes.</td>
</tr>
<tr>
- <td>client-ip</td>
+ <td>client_ip</td>
<td>Provided for the master node. This IP should be reachable from clients that want to connect with AsterixDB via its web interface.</td>
</tr>
<tr>
- <td>client-port</td>
+ <td>client_port</td>
<td>Provided for the master node. This is the port at which the Cluster Controller (CC) service listens for connections from clients.</td>
</tr>
<tr>
- <td>cluster-port</td>
+ <td>cluster_port</td>
<td>Provided for the master node. This is the port used by the Cluster Controller (CC) service to listen for connections from Node Controllers (NCs). </td>
</tr>
<tr>
@@ -422,99 +422,9 @@
Next we describe how to set up AsterixDB in this cluster, assuming no Managix has been installed on these machines.
-### Step (1): Define the AsterixDB cluster ###
+### Step (1): Configure SSH ###
-We first log into the master machine as the user "joe". On this machine, download Managix from [here](http://asterixdb.ics.uci.edu/download/0.8.3/asterix-installer-0.8.3-binary-assembly.zip) (save as above), then do the following steps similar to the single-machine case described above:
-
-
- machineA> cd ~
- machineA> mkdir asterix-mgmt
- machineA> cd asterix-mgmt
- machineA> unzip <path to the Managix zip bundle>
- machineA> export MANAGIX_HOME=`pwd`
- machineA> export PATH=$PATH:$MANAGIX_HOME/bin
-
-Note that it is recommended that MANAGIX_HOME is not located on a network file system (NFS). Managix creates artifacts/logs that are not required to be shared. Any overhead
-associated with creating artifacts/logs on the NFS should be avoided.
-
-We also need an AsterixDB configuration XML file for the cluster. We give the name to the cluster, say, "rainbow". We create a folder for the configuration of this cluster:
-
-
- machineA> mkdir $MANAGIX_HOME/rainbow_cluster
-
-
-For this cluster we create a configuration file `$MANAGIX_HOME/rainbow_cluster/rainbow.xml`. The following is a sample file with explanation of the properties:
-
- <cluster xmlns="cluster">
-
- <!-- Name of the cluster -->
- <name>rainbow</name>
-
- <!-- username, which should be valid for all the three machines -->
- <username>joe</username>
-
- <!-- The working directory of Managix. It is recommended for the working
- directory to be on a network file system (NFS) that can accessed by
- all machines.
- Managix creates the directory if it it doesn't exist. -->
- <working_dir>
- <dir>/home/joe/managix-workingDir</dir>
- <NFS>true</NFS>
- </working_dir>
-
- <!-- Directory for Asterix to store log information for each machine.
- Needs to be on the local file system of each machine.
- Managix creates the directory if it doesn't exist.
- This property can be overriden for a node by redefining at the node level. -->
- <logdir>/mnt/joe/logs</logdir>
-
- <!-- Mount point of an iodevice. Use a comma separated list for a machine that
- has multiple iodevices (disks).
- This property can be overriden for a node by redefining at the node level. -->
- <iodevices>/mnt/joe</iodevices>
-
- <!-- Path on each iodevice where Asterix will store its data -->
- <store>storage</store>
-
- <!-- Java home for each machine -->
- <java_home>/usr/lib/jvm/jdk1.7.0</java_home>
-
- <!-- IP addresses of the master machine A -->
- <master_node>
- <id>master</id>
- <client_ip>128.195.52.177</client_ip>
- <cluster_ip>192.168.100.0</cluster_ip>
- <client_port>1098</client_port>
- <cluster_port>1099</cluster_port>
- <http_port>8888</http_port>
- </master_node>
-
- <!-- IP address(es) of machine B -->
- <node>
- <id>nodeB</id>
- <cluster_ip>192.168.100.1</cluster_ip>
- </node>
-
- <!-- IP address(es) of machine C -->
- <node>
- <id>nodeC</id>
- <cluster_ip>192.168.100.2</cluster_ip>
- </node>
- </cluster>
-
-
-As stated before, each of the above properties can be defined at the cluster level, in which case it applies to all the nodes in the system. Each property can also be defined at a node level.
-
-Once we have formed the cluster XML file, we can validate the configuration by doing the following:
-
- managix validate -c $MANAGIX_HOME/rainbow_cluster/rainbow.xml
-
-
-If the return message says "OK", it means that the XML configuration file is set properly.
-
-### Step (2): Configure SSH ###
-
-The next steps of setting up SSH are similar to those in the single-machine setup case. We assume we have a common user account called "joe" on each machine in the cluster.
+The steps of setting up SSH are similar to those in the single-machine setup case. We assume we have a common user account called "joe" on each machine in the cluster.
On the master machine, do the following:
@@ -562,6 +472,114 @@
machineA> ssh 127.0.0.1
+### Step (2): Define the AsterixDB cluster ###
+
+We first log into the master machine as the user "joe". On this machine, download Managix from [here](http://asterixdb.ics.uci.edu/download/0.8.3/asterix-installer-0.8.3-binary-assembly.zip) (save as above), then do the following steps similar to the single-machine case described above:
+
+
+ machineA> cd ~
+ machineA> mkdir asterix-mgmt
+ machineA> cd asterix-mgmt
+ machineA> unzip <path to the Managix zip bundle>
+ machineA> export MANAGIX_HOME=`pwd`
+ machineA> export PATH=$PATH:$MANAGIX_HOME/bin
+
+Note that it is recommended that MANAGIX_HOME is not located on a network file system (NFS). Managix creates artifacts/logs that are not required to be shared. Any overhead
+associated with creating artifacts/logs on the NFS should be avoided.
+
+We also need an AsterixDB configuration XML file for the cluster. We give the name to the cluster, say, "rainbow". We create a folder for the configuration of this cluster:
+
+
+ machineA> mkdir $MANAGIX_HOME/rainbow_cluster
+
+
+For this cluster we create a configuration file `$MANAGIX_HOME/rainbow_cluster/rainbow.xml`. The following is a sample file with explanation of the properties:
+
+ <cluster xmlns="cluster">
+
+ <!-- Name of the cluster -->
+ <name>rainbow</name>
+
+ <!-- username, which should be valid for all the three machines -->
+ <username>joe</username>
+
+ <!-- The working directory of Managix. It is recommended for the working
+ directory to be on a network file system (NFS) that can accessed by
+ all machines.
+ Managix creates the directory if it it doesn't exist. -->
+ <working_dir>
+ <dir>/home/joe/managix-workingDir</dir>
+ <NFS>true</NFS>
+ </working_dir>
+
+ <!-- Directory for Asterix to store worker logs information for each machine.
+ Needs to be on the local file system of each machine.
+ Managix creates the directory if it doesn't exist.
+ This property can be overriden for a node by redefining at the node level. -->
+ <log_dir>/mnt/joe/logs</log_dir>
+
+ <!-- Directory for Asterix to store transaction log information for each machine.
+ Needs to be on the local file system of each machine.
+ Managix creates the directory if it doesn't exist.
+ This property can be overriden for a node by redefining at the node level. -->
+ <txn_log_dir>/mnt/joe/txn_logs</txn_log_dir>
+
+ <!-- Mount point of an iodevice. Use a comma separated list for a machine that
+ has multiple iodevices (disks).
+ This property can be overriden for a node by redefining at the node level. -->
+ <iodevices>/mnt/joe</iodevices>
+
+ <!-- Path on each iodevice where Asterix will store its data -->
+ <store>storage</store>
+
+ <!-- Java home for each machine -->
+ <java_home>/usr/lib/jvm/jdk1.7.0</java_home>
+
+ <!-- IP addresses of the master machine A -->
+ <master_node>
+ <id>master</id>
+ <client_ip>128.195.52.177</client_ip>
+ <cluster_ip>192.168.100.0</cluster_ip>
+ <client_port>1098</client_port>
+ <cluster_port>1099</cluster_port>
+ <http_port>8888</http_port>
+ </master_node>
+
+ <!-- IP address(es) of machine B -->
+ <node>
+ <id>nodeB</id>
+ <cluster_ip>192.168.100.1</cluster_ip>
+ </node>
+
+ <!-- IP address(es) of machine C -->
+ <node>
+ <id>nodeC</id>
+ <cluster_ip>192.168.100.2</cluster_ip>
+ </node>
+ </cluster>
+
+
+As stated before, each of the above properties can be defined at the cluster level, in which case it applies to all the nodes in the system. Each property can also be defined at a node level.
+
+Once we have formed the cluster XML file, we can validate the configuration by doing the following:
+
+ managix validate -c $MANAGIX_HOME/rainbow_cluster/rainbow.xml
+
+This will verify the contents of the file, and also attempt to ssh to each node in the cluster to ensure that password-less SSH is configured correctly. You may see output like
+
+ The authenticity of host '192.168.100.1 (192.168.100.1)' can't be established.
+ RSA key fingerprint is 89:80:31:1f:be:51:16:d7:2b:f5:e0:b3:2c:bd:83:94.
+ Are you sure you want to continue connecting (yes/no)?
+
+and this output may be repeated for each node in the cluster. Answer "yes" each time.
+
+If the final output contains the following lines (possibly separated by the RSA prompts mentione above):
+
+ INFO: Environment [OK]
+ INFO: Cluster configuration [OK]
+
+it means that the XML configuration file is correct!
+
### Step (3): Configuring Managix ###
Managix uses a configuration XML file at `$MANAGIX_HOME/conf/managix-conf.xml` to configure its own properties, such as its Zookeeper service. We can use the `configure` command to auto-generate this configuration file:
@@ -577,7 +595,7 @@
INFO: Managix Configuration [OK]
-Note that the `configure` command also generates a cluster configuration XML file at $MANAGIX_HOME/conf/clusters/local.xml. This file is not needed in the case of a cluster of machines.
+Note that the `configure` command also generates a cluster configuration XML file at $MANAGIX_HOME/clusters/local/local.xml. This file is not needed in the case of a cluster of machines.
### Step (4): Creating an AsterixDB instance ###
diff --git a/asterix-installer/src/main/java/edu/uci/ics/asterix/installer/command/ValidateCommand.java b/asterix-installer/src/main/java/edu/uci/ics/asterix/installer/command/ValidateCommand.java
index 5035028..a7c53ea 100644
--- a/asterix-installer/src/main/java/edu/uci/ics/asterix/installer/command/ValidateCommand.java
+++ b/asterix-installer/src/main/java/edu/uci/ics/asterix/installer/command/ValidateCommand.java
@@ -188,6 +188,13 @@
}
}
+ if (node.getTxnLogDir() == null || node.getTxnLogDir().length() == 0) {
+ if (cluster.getTxnLogDir() == null || cluster.getTxnLogDir().length() == 0) {
+ valid = false;
+ LOGGER.fatal("txn_log_dir not defined at cluster/node level for node: " + node.getId() + ERROR);
+ }
+ }
+
if (node.getStore() == null || node.getStore().length() == 0) {
if (!cluster.getMasterNode().getId().equals(node.getId())
&& (cluster.getStore() == null || cluster.getStore().length() == 0)) {