polished install page
diff --git a/asterix-doc/src/site/markdown/install.md b/asterix-doc/src/site/markdown/install.md
index 570a896..10ce4cf 100644
--- a/asterix-doc/src/site/markdown/install.md
+++ b/asterix-doc/src/site/markdown/install.md
@@ -1,7 +1,7 @@
# Introduction #
-This is a quickstart guide for getting ASTERIX running in a distributed environment. This guide also introduces the ASTERIX installer (nicknamed _*Managix*_) and describes how it can be used to create/manage an ASTERIX instance. By following the simple steps described in this guide, you will get a running instance of ASTERIX. You shall be able to use ASTERIX from its Web interface and manage its lifecycle using Managix. This document assumes that you are running some version of _*Linux*_ or _*MacOS X*_.
+This is a quickstart guide for getting AsterixDB running in a distributed environment. This guide also introduces the AsterixDB installer (nicknamed _*Managix*_) and describes how it can be used to create and manage an AsterixDB instance. By following the simple steps described in this guide, you will get a running instance of AsterixDB. You shall be able to use AsterixDB from its Web interface and manage its lifecycle using Managix. This document assumes that you are running some version of _*Linux*_ or _*MacOS X*_.
-## Prerequisites for Installing ASTERIX ##
+## Prerequisites for Installing AsterixDB ##
Prerequisite:
* [JDK7](http://www.oracle.com/technetwork/java/javase/downloads/index.html) (Otherwise known as JDK 1.7).
@@ -25,7 +25,7 @@
* For Mac: [JDK 7 Mac Install](http://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-jdk.html)
JDK would be installed at /Library/Java/JavaVirtualMachines/jdk-version/Contents/Home .
-The java installation directory is referred as JAVA_HOME. Since we upgraded/installed Java, we need to ensure JAVA_HOME points to the installation directory of JDK 7. Modify your ~/.bash_profile (or ~/.bashrc) and define JAVA_HOME accordingly. After modifying, execute the following:
+The java installation directory is referred as JAVA_HOME. Since we upgraded/installed Java, we need to ensure JAVA_HOME points to the installation directory of JDK 7. Modify your ~/.bash_profile (or ~/.bashrc) and define JAVA_HOME accordingly. After the modification, execute the following:
$ java -version
@@ -37,26 +37,26 @@
$ source ~/.bash_profile (or ~/.bashrc)
-## Section 1: Single-Machine ASTERIX installation ##
-We assume a user Joe with a home directory as /home/joe. Please note that on a Mac, the home directory for user Joe would be /Users/joe.
+## Section 1: Single-Machine AsterixDB installation ##
+We assume a user called "Joe" with a home directory as /home/joe. On a Mac, the home directory for user Joe would be /Users/joe.
### Configuring Environment ###
-Ensure that JAVA_HOME variable is defined and points to the the java installation directory on your machine. To verify, execute the following.
+Ensure that JAVA_HOME variable is defined and points to the the java installation directory on your machine. To verify, execute the following:
$ echo $JAVA_HOME
-If you do not see any output, JAVA_HOME is not defined. We need to add the following line to your profile located at /home/joe/.bash_profile or /home/joe/.bashrc, whichever you are using. If you do not have any of these files, create a ~/.bash_profile.
+If you do not see any output, JAVA_HOME is not defined. We need to add the following line to your profile located at /home/joe/.bash_profile or /home/joe/.bashrc, whichever you are using. If you do not have any of these files, create a ~/.bash_profile file.
export JAVA_HOME=<Path to Java installation directory>
-After you have edited ~/.bash_profile (or ~/.bashrc), execute the following to make the changes effective in current shell.
+After you have edited ~/.bash_profile (or ~/.bashrc), execute the following to make the changes effective in current shell:
$ source /home/joe/.bash_profile (or /home/joe/.bashrc)
-Before proceeding, verify that JAVA_HOME is defined by executing the following.
+Before proceeding, verify that JAVA_HOME is defined by executing the following:
$ echo $JAVA_HOME
@@ -75,7 +75,7 @@
#### Configuring Password-less SSH ####
-For our single-machine setup of ASTERIX, we need to configure password-less SSH access to localhost. We assume that you are on the machine where you want to install ASTERIX. To verify if you already have password-less SSH configured, execute the following.
+For our single-machine setup of AsterixDB, we need to configure password-less SSH access to localhost. We assume that you are on the machine where you want to install AsterixDB. To verify if you already have password-less SSH configured, execute the following:
$ ssh 127.0.0.1
@@ -93,7 +93,7 @@
$ ssh 127.0.0.1
Last login: Sat Mar 23 22:52:49 2013
-You are here because you were prompted for a password. You need to configure password less SSH. Follow the instructions below.
+You are here because you were prompted for a password. You need to configure password less SSH. Follow the instructions below:
$ ssh-keygen -t rsa -P ""
@@ -106,7 +106,7 @@
/home/joe/.ssh/id_rsa already exists.
Overwrite (y/n)?
-You should see an output similar to one shown below.
+You should see an output similar to one shown below:
The key fingerprint is:
@@ -134,14 +134,14 @@
$ ssh 127.0.0.1
-You may see an output similar to one shown below.
+You may see an output similar to one shown below:
The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.
- RSA key fingerprint is��aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.
+ RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.
Are you sure you want to continue connecting (yes/no)?
-Type 'yes' and press the enter key. You should see an output similar to one shown below.
+Type 'yes' and press the enter key. You should see an output similar to one shown below:
Warning: Permanently added '127.0.0.1' (RSA) to the list of known hosts.
@@ -161,9 +161,9 @@
Connection to 127.0.0.1 closed.
### Configuring Managix ###
-You will need the ASTERIX installer (a.k.a Managix). Download Managix from [here](https://asterixdb.googlecode.com/files/asterix-installer-0.0.5-binary-assembly.zip); this includes the bits for Managix as well as ASTERIX.
+You will need the AsterixDB installer (a.k.a. Managix). Download Managix from [here](https://asterixdb.googlecode.com/files/asterix-installer-0.0.5-binary-assembly.zip); this includes the bits for Managix as well as AsterixDB.
-Unzip the Managix zip bundle to an appropriate location. You may create a sub-directory: asterix-mgmt (short for asterix-management) under your home directory. We shall refer to this location as MANAGIX_HOME.
+Unzip the Managix zip bundle to an appropriate location. You may create a sub-directory called "asterix-mgmt" (short for asterix-management) under your home directory. We shall refer to this location as MANAGIX_HOME.
$ cd ~
@@ -173,7 +173,7 @@
/home/joe/asterix-mgmt> $ export MANAGIX_HOME=`pwd`
/home/joe/asterix-mgmt> $ export PATH=$PATH:$MANAGIX_HOME/bin
-It is recommended that you add $MANAGIX_HOME/bin to your PATH variable in your bash profile . This can be done by executing the following.
+It is recommended that you add $MANAGIX_HOME/bin to your PATH variable in your bash profile . This step can be done by executing the following.
currentDir=`pwd`
@@ -182,12 +182,12 @@
Above, use ~/.bashrc instead of ~/.bash_profile if you are using ~/.bashrc .
-To be able to create an ASTERIX instance and manage its lifecycle, the Managix requires you to configure a set of configuration files namely:
+To be able to create an AsterixDB instance and manage its lifecycle, the Managix requires you to configure a set of configuration files namely:
* `conf/managix-conf.xml`: A configuration XML file that contains configuration settings for Managix.
* A configuration XML file that describes the nodes in the cluster, e.g., `$MANAGIX_HOME/clusters/local/local.xml`.
-Since we intend to run ASTERIX on a single node, Managix can auto-configure itself and populate the above mentioned configuration files. To auto-configure Managix, execute the following in the MANAGIX_HOME directory:
+Since we intend to run AsterixDB on a single node, Managix can auto-configure itself and populate the above configuration files. To auto-configure Managix, execute the following in the MANAGIX_HOME directory:
/home/joe/asterix-mgmt> $ managix configure
@@ -204,18 +204,18 @@
INFO: Environment [OK]
INFO: Cluster configuration [OK]
-### Creating an ASTERIX instance ###
-Now that we have configured Managix, we shall next create an ASTERIX instance. An ASTERIX instance is identified by a unique name and is created using the `create` command. The usage description for the `create` command can be obtained by executing the following.
+### Creating an AsterixDB instance ###
+Now that we have configured Managix, we shall next create an AsterixDB instance. An AsterixDB instance is identified by a unique name and is created using the `create` command. The usage description for the `create` command can be obtained by executing the following:
$ managix help -cmd create
- Creates an ASTERIX instance with a specified name. Post creation, the instance is in ACTIVE state,
+ Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,
indicating its availability for executing statements/queries.
Usage arguments/options:
- -n Name of the ASTERIX instance.
+ -n Name of the AsterixDB instance.
-c Path to the cluster configuration file
-We shall now use the create command to create an ASTERIX instance by the name "my_asterix". In doing so, we shall use the cluster configuration file that was auto-generated by managix.
+We shall now use the `create` command to create an AsterixDB instance by the name "my_asterix". In doing so, we shall use the cluster configuration file that was auto-generated by Managix.
$ managix create -n my_asterix -c $MANAGIX_HOME/clusters/local/local.xml
@@ -228,7 +228,7 @@
Web-Url:http://127.0.0.1:19001
State:ACTIVE
-The third line above shows the web-url http://127.0.0.1:19001 for ASTERIX's web-interface. The ASTERIX instance is in the 'ACTIVE' state indicating that you may access the web-interface by navigating to the web-url.
+The third line above shows the web-url http://127.0.0.1:19001 for an AsterixDB's web interface. The AsterixDB instance is in the 'ACTIVE' state, indicating that you may access the web interface by navigating to the web url.
Type in the following "Hello World" query in the box:
@@ -236,16 +236,16 @@
let $message := 'Hello World!'
return $message
-Press the "Run" button. If the query result shows on the output box, then Congratulations! You have successfully created an ASTERIX instance!
+Press the "Run" button. If the query result shows on the output box, then Congratulations! You have successfully created an AsterixDB instance!
-## Section 2: Single-Machine ASTERIX installation (Advanced) ##
-We assume that you have successfully completed the single-machine ASTERIX installation by following the instructions above in section [ASTERIX installation](#Section_1:_Single-Machine_ASTERIX_installation). In this section, we shall cover advanced topics related to ASTERIX configuration. Before we proceed, it is imperative to go through some preliminary concepts related to ASTERIX runtime.
+## Section 2: Single-Machine AsterixDB installation (Advanced) ##
+We assume that you have successfully completed the single-machine AsterixDB installation by following the instructions above in section [AsterixDB installation](#Section_1:_Single-Machine_AsterixDB_installation). In this section, we shall cover advanced topics related to AsterixDB configuration. Before we proceed, it is imperative to go through some preliminary concepts related to AsterixDB runtime.
-### ASTERIX Runtime ###
-An ASTERIX runtime comprises of a ''master node'' and a set of ''worker nodes'', each identified by a unique id. The master node runs a ''Cluster Controller'' service (a.k.a. ''CC''), while each worker node runs a ''Node Controller'' service (a.k.a. ''NC''). Please note that a node in an ASTERIX cluster is a logical concept in the sense that multiple nodes may map to a single physical machine, which is the case for a single-machine ASTERIX installation. This association or mapping between an ASTERIX node and a physical machine is captured in a cluster configuration XML file. In addition, the XML file contains properties and parameters associated with each node.
+### AsterixDB Runtime ###
+An AsterixDB runtime comprises of a ''master node'' and a set of ''worker nodes'', each identified by a unique id. The master node runs a ''Cluster Controller'' service (a.k.a. ''CC''), while each worker node runs a ''Node Controller'' service (a.k.a. ''NC''). Please note that a node in an AsterixDB cluster is a logical concept in the sense that multiple nodes may map to a single physical machine, which is the case for a single-machine AsterixDB installation. This association or mapping between an AsterixDB node and a physical machine is captured in a cluster configuration XML file. In addition, the XML file contains properties and parameters associated with each node.
-#### ASTERIX Runtime Configuration ####
-As observed earlier, Managix can auto-configure itself for a single-machine setup. As part of auto-configuration, Managix generated the cluster XML file. Let us understand the components of the generated cluster XML file. If you have configured Managix (via the "configure" command), you can find a similar cluster XML file as $MANAGIX_HOME/clusters/local/local.xml. The following is a sample XML file generated on a Ubuntu (Linux) setup:
+#### AsterixDB Runtime Configuration ####
+As observed earlier, Managix can auto-configure itself for a single-machine setup. As part of auto-configuration, Managix generated the cluster XML file. Let us understand the components of the generated cluster XML file. If you have configured Managix (via the `configure` command), you can find a similar cluster XML file as $MANAGIX_HOME/clusters/local/local.xml. The following is a sample XML file generated on a Ubuntu (Linux) setup:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -276,8 +276,8 @@
We shall next explain the components of the cluster configuration XML file.
-#### (1) Defining nodes in ASTERIX runtime ####
-The single-machine ASTERIX 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 ASTERIX installation.
+#### (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.
<master-node>
@@ -311,25 +311,25 @@
</tr>
<tr>
<td>client-ip</td>
- <td>Provided for the master node. This IP should be reachable from clients that want to connect with ASTERIX via its web interface.</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>Provided for the master node. This is the port at which the Cluster Controller (CC) service listens for connections from clients .</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>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>
+ <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>
<td>http-port</td>
- <td>Provided for the master node. This is http port used by the Cluster Controller (CC) service </td>
+ <td>Provided for the master node. This is the http port used by the Cluster Controller (CC) service. </td>
</tr>
</table>
-#### (2) Properties associated with a worker node (NC) in ASTERIX ####
-The following is a list of properties associated with each worker node in an ASTERIX configuration.
+#### (2) Properties associated with a worker node (NC) in AsterixDB ####
+The following is a list of properties associated with each worker node in an AsterixDB configuration.
<table>
<tr>
@@ -342,11 +342,11 @@
</tr>
<tr>
<td>log_dir</td>
- <td>A directory where worker node JVM may write logs.</td>
+ <td>A directory where the worker node JVM may write logs.</td>
</tr>
<tr>
<td>txn_log_dir</td>
- <td>A directory where worker node writes transaction logs.</td>
+ <td>A directory where the worker node writes transaction logs.</td>
</tr>
<tr>
<td>iodevices</td>
@@ -354,13 +354,13 @@
</tr>
<tr>
<td>store</td>
- <td>A data directory that ASTERIX uses to store data belonging to dataset(s).</td>
+ <td>A data directory that AsterixDB uses to store data belonging to dataset(s).</td>
</tr>
</table>
-All the above properties can be defined at the global level or a local level. In the former case, these properties apply to all the nodes in an ASTERIX configuration. In the latter case, these properties apply only to the node(s) under which they are defined. A property defined at the local level overrides the definition at the global level.
+All the above properties can be defined at the global level or a local level. In the former case, these properties apply to all the nodes in an AsterixDB configuration. In the latter case, these properties apply only to the node(s) under which they are defined. A property defined at the local level overrides the definition at the global level.
-#### (3) Working directory of an ASTERIX instance ####
+#### (3) Working directory of an AsterixDB instance ####
Next we explain the following setting in the file $MANAGIX_HOME/clusters/local/local.xml.
@@ -370,10 +370,10 @@
</workingDir>
-Managix associates a working directory with an ASTERIX instance and uses this directory for transferring binaries to each node. If there exists a directory that is readable by each node, Managix can use it to place binaries that can be accessed and used by all the nodes in the ASTERIX set up. A network file system (NFS) provides such a functionality for a cluster of physical machines such that a path on NFS is accessible from each machine in the cluster. In the single-machine set up described above, all nodes correspond to a single physical machine. Each path on the local file system is accessible to all the nodes in the ASTERIX setup and the boolean value for NFS above is thus set to `true`.
+Managix associates a working directory with an AsterixDB instance and uses this directory for transferring binaries to each node. If there exists a directory that is readable by each node, Managix can use it to place binaries that can be accessed and used by all the nodes in the AsterixDB set up. A network file system (NFS) provides such a functionality for a cluster of physical machines so that a path on NFS is accessible from each machine in the cluster. In the single-machine set up described above, all nodes correspond to a single physical machine. Each path on the local file system is accessible to all the nodes in the AsterixDB setup and the boolean value for NFS above is thus set to `true`.
### Managix Configuration ###
-Managix allows creation and management of multiple ASTERIX instances and uses Zookeeper as its back-end database to keep track of information related to each instance. We need to provide a set of one or more hosts that Managix can use to run a Zookeeper instance. Zookeeper runs as a daemon process on each of the specified hosts. At each host, Zookeeper stores data under the Zookeeper home directory specified as part of the configuration. The following is an example configuration `$MANAGIX_HOME/conf/managix-conf.xml` that has Zookeeper running on the localhost (127.0.0.1) :
+Managix allows creation and management of multiple AsterixDB instances and uses Zookeeper as its back-end database to keep track of information related to each instance. We need to provide a set of one or more hosts that Managix can use to run a Zookeeper instance. Zookeeper runs as a daemon process on each of the specified hosts. At each host, Zookeeper stores data under the Zookeeper home directory specified as part of the configuration. The following is an example configuration `$MANAGIX_HOME/conf/managix-conf.xml` that has Zookeeper running on the localhost (127.0.0.1) :
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -387,18 +387,18 @@
</zookeeper>
</configuration>
-It is possible to have a single host for Zookeeper. A larger number of hosts would use Zookeeper's replication and fault-tolerance feature such that a failure of a host running Zookeeper would not result in loss of information about existing ASTERIX instances.
+It is possible to have a single host for Zookeeper. A larger number of hosts would use Zookeeper's replication and fault-tolerance feature such that a failure of a host running Zookeeper would not result in loss of information about existing AsterixDB instances.
-## Section 3: Installing ASTERIX on a Cluster of Multiple Machines ##
-We assume that you have read the two sections above on single-machine ASTERIX setup. Next we explain how to install ASTERIX in a cluster of multiple machines. As an example, we assume we want to setup ASTERIX on a cluster of three machines, in which we use one machine (called machine A) as the master node and two other machines (called machine B and machine C) as the worker nodes, as shown in the following diagram:
+## Section 3: Installing AsterixDB on a Cluster of Multiple Machines ##
+We assume that you have read the two sections above on single-machine AsterixDB setup. Next we explain how to install AsterixDB in a cluster of multiple machines. As an example, we assume we want to setup AsterixDB on a cluster of three machines, in which we use one machine (called machine A) as the master node and two other machines (called machine B and machine C) as the worker nodes, as shown in the following diagram:
Notice that each machine has a ''cluster-ip'' address, which is used by these machines for their intra-cluster communication. Meanwhile, the master machine also has a ''client-ip'' address, using which an end-user outside the cluster can communicate with this machine. The reason we differentiate between these two types of IP addresses is that we can have a cluster of machines using a private network. In this case they have internal ip addresses that cannot be used outside the network. In the case all the machines are on a public network, the "client-ip" and "cluster-ip" of the master machine can share the same address.
-Next we describe how to set up ASTERIX in this cluster, assuming no Managix has been installed on these machines.
+Next we describe how to set up AsterixDB in this cluster, assuming no Managix has been installed on these machines.
-### Step (1): Define the ASTERIX cluster ###
+### Step (1): Define the AsterixDB cluster ###
We first log into the master machine as the user "joe". On this machine, download Managix from [here](https://asterixdb.googlecode.com/files/asterix-installer-0.0.5-binary-assembly.zip) (save as above), then do the following steps similar to the single-machine case described above:
@@ -410,10 +410,10 @@
machineA> export MANAGIX_HOME=`pwd`
machineA> export PATH=$PATH:$MANAGIX_HOME/bin
-Note:- It is recommended that MAANGIX_HOME is not located on a network file system (NFS). Managi creates artifacts/logs that are not required to be shared. Any overhead
+Note that it is recommended that MAANGIX_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 ASTERIX 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:
+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
@@ -495,7 +495,7 @@
machineA> ssh 127.0.0.1
-If you are prompted for a password, execute the following
+If you are prompted for a password, execute the following:
machineA> ssh-keygen -t rsa -P ""
@@ -516,13 +516,13 @@
### Step (3): Configuring Managix ###
-Managix is using 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:
+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:
machineA> managix configure
-We use the validate command to validate managix configuration. To do so, execute the following.
+We use the `validate` command to validate the Managix configuration. To do so, execute the following.
machineA> managix validate
INFO: Environment [OK]
@@ -531,49 +531,49 @@
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.
-### Step (4): Creating an ASTERIX instance ###
+### Step (4): Creating an AsterixDB instance ###
-Now that we have configured Managix, we shall next create an ASTERIX instance. An ASTERIX instance is identified by a unique name and is created using the create command. The usage description for the create command can be obtained by executing the following:
+Now that we have configured Managix, we shall next create an AsterixDB instance, which is identified by a unique name and is created using the `create` command. The usage description for the `create` command can be obtained by executing the following:
machineA> managix help -cmd create
- Creates an ASTERIX instance with a specified name. Post creation, the instance is in ACTIVE state,
+ Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,
indicating its availability for executing statements/queries.
Usage arguments/options:
- -n Name of the ASTERIX instance.
+ -n Name of the AsterixDB instance.
-c Path to the cluster configuration file
-We shall now use the `create` command to create an ASTERIX instance called "rainbow_asterix". In doing so, we shall use the cluster configuration file that was auto-generated by Managix.
+We shall now use the `create` command to create an AsterixDB instance called "rainbow_asterix". In doing so, we shall use the cluster configuration file that was auto-generated by Managix.
machineA> managix create -n rainbow_asterix -c $MANAGIX_HOME/clusters/rainbow/rainbow.xml
-If the response message does not have warning, then Congratulations! You have successfully installed Asterix on this cluster of machines!
+If the response message does not have warning, then Congratulations! You have successfully installed AsterixDB on this cluster of machines!
-Please refer to the section [Managing the Lifecycle of an ASTERIX Instance](#Section_4:_Managing_the_Lifecycle_of_an_ASTERIX_Instance) for a detailed description on the set of available commands/operations that let you manage the lifecycle of an ASTERIX instance. Note that the output of the commands varies with the cluster definition and may not apply to the cluster specification you built above.
+Please refer to the section [Managing the Lifecycle of an AsterixDB Instance](#Section_4:_Managing_the_Lifecycle_of_an_AsterixDB_Instance) for a detailed description on the set of available commands/operations that let you manage the lifecycle of an AsterixDB instance. Note that the output of the commands varies with the cluster definition and may not apply to the cluster specification you built above.
-## Section 4: Managing the Lifecycle of an ASTERIX Instance ##
+## Section 4: Managing the Lifecycle of an AsterixDB Instance ##
-Now that we have an ASTERIX instance running, let us use Managix to manage the instance's lifecycle. Managix provides the following set of commands/operations:
+Now that we have an AsterixDB instance running, let us use Managix to manage the instance's lifecycle. Managix provides the following set of commands/operations:
#### Managix Commands ####
<table>
<tr><td>Command</td> <td>Description</td></tr>
-<tr><td><a href="#Creating_an_ASTERIX_instance">create</a></td> <td>Creates a new asterix instance.</td></tr>
+<tr><td><a href="#Creating_an_AsterixDB_instance">create</a></td> <td>Creates a new asterix instance.</td></tr>
<tr><td><a href="#Describe_Command" >describe</a></td> <td>Describes an existing asterix instance.</td></tr>
<tr><td><a href="#Stop_Command" >stop</a></td> <td>Stops an asterix instance that is in the ACTIVE state.</td></tr>
-<tr><td><a href="#Start_Command" >start</a></td> <td>Starts an Asterix instance.</td></tr>
-<tr><td><a href="#Backup_Command" >backup</a></td> <td>Creates a backup for an existing Asterix instance.</td></tr>
-<tr><td><a href="#Restore_Command" >restore</a></td> <td>Restores an Asterix instance.</td></tr>
-<tr><td><a href="#Delete_Command" >delete</a></td> <td>Deletes an Asterix instance.</td></tr>
+<tr><td><a href="#Start_Command" >start</a></td> <td>Starts an AsterixDB instance.</td></tr>
+<tr><td><a href="#Backup_Command" >backup</a></td> <td>Creates a backup for an existing AsterixDB instance.</td></tr>
+<tr><td><a href="#Restore_Command" >restore</a></td> <td>Restores an AsterixDB instance.</td></tr>
+<tr><td><a href="#Delete_Command" >delete</a></td> <td>Deletes an AsterixDB instance.</td></tr>
<tr><td><a href="#Configuring_Managix" >validate</a></td> <td>Validates the installer/cluster configuration.</td></tr>
-<tr><td><a href="#Configuring_Managix" >configure</a></td><td>Auto generate configuration for an Asterix instance.</td></tr>
-<tr><td><a href="#Log_Command" >log</a></td><td>Produce a zip archive containing log files from each node in an Asterix instance.</td></tr>
-<tr><td><a href="#Shutdown_Command" >shutdown</a></td> <td>Shutdown the installer service.</td></tr>
+<tr><td><a href="#Configuring_Managix" >configure</a></td><td>Auto generates a configuration for an AsterixDB instance.</td></tr>
+<tr><td><a href="#Log_Command" >log</a></td><td>Produces a zip archive containing log files from each node in an AsterixDB instance.</td></tr>
+<tr><td><a href="#Shutdown_Command" >shutdown</a></td> <td>Shuts down the installer service.</td></tr>
</table>
You may obtain the above listing by simply executing 'managix' :
@@ -581,22 +581,22 @@
$ managix
-We already talked about create and validate commands. We shall next explain the rest of the commands listed above. We also provide sample output messages of these commands assuming we are running an ASTERIX instance on a single machine.
+We already talked about `create` and `validate` commands. We shall next explain the rest of the commands listed above. We also provide sample output messages of these commands assuming we are running an AsterixDB instance on a single machine.
##### Describe Command #####
-The `describe` command provides information about an ASTERIX instance. The usage can be looked up by executing the following:
+The `describe` command provides information about an AsterixDB instance. The usage can be looked up by executing the following:
$ managix help -cmd describe
- Provides information about an ASTERIX instance.
+ Provides information about an AsterixDB instance.
The following options are available:
- [-n] Name of the ASTERIX instance.
+ [-n] Name of the AsterixDB instance.
[-admin] Provides a detailed description
The brackets indicate optional flags.
-The output of the `describe` command when used without the `admin` flag contains minimal information and is similar to the output of the create command. Let us try running the describe command in "admin" mode.
+The output of the `describe` command when used without the `admin` flag contains minimal information and is similar to the output of the `create` command. Let us try running the describe command in "admin" mode.
$ managix describe -n my_asterix -admin
@@ -648,22 +648,22 @@
As seen above, the instance 'my_asterix' is configured such that all processes running at the localhost (127.0.0.1). The process id for each process (JVM) is shown next to it.
##### Stop Command #####
-The `stop` command can be used for shutting down an ASTERIX instance. After that, the instance is unavailable for executing queries. The usage can be looked up by executing the following.
+The `stop` command can be used for shutting down an AsterixDB instance. After that, the instance is unavailable for executing queries. The usage can be looked up by executing the following.
$ managix help -cmd stop
- Shuts an ASTERIX instance that is in ACTIVE state. After executing the stop command, the ASTERIX instance transits
+ Shuts an AsterixDB instance that is in ACTIVE state. After executing the stop command, the AsterixDB instance transits
to the INACTIVE state, indicating that it is no longer available for executing queries.
Available arguments/options
- -n name of the ASTERIX instance.
+ -n name of the AsterixDB instance.
-To stop the ASTERIX instance.
+To stop the AsterixDB instance.
$ managix stop -n my_asterix
- INFO: Stopped Asterix instance: my_asterix
+ INFO: Stopped AsterixDB instance: my_asterix
$ managix describe -n my_asterix
@@ -674,17 +674,17 @@
##### Start Command #####
-The `start` command starts an ASTERIX instance that is in the INACTIVE state. The usage can be looked up by executing the following:
+The `start` command starts an AsterixDB instance that is in the INACTIVE state. The usage can be looked up by executing the following:
$ managix help -cmd start
- Starts an ASTERIX instance that is in INACTIVE state. After executing the start command, the ASTERIX instance transits to the ACTIVE state, indicating that it is now available for executing statements/queries.
+ Starts an AsterixDB instance that is in INACTIVE state. After executing the start command, the AsterixDB instance transits to the ACTIVE state, indicating that it is now available for executing statements/queries.
Available arguments/options
- -n name of the ASTERIX instance.
+ -n name of the AsterixDB instance.
-Let us now start the ASTERIX instance.
+Let us now start the AsterixDB instance.
$ managix start -n my_asterix
@@ -696,22 +696,22 @@
##### Backup Command #####
-The backup command allows you to take a backup of the data stored with an ASTERIX instance. The backup can be taken on the local file system or on an HDFS instance. In either case, the snapshots are stored under a backup directory. You need to make sure the backup directory has appropriate read/write permissions. Configuring settings for backup can be found inside the Managix's configuration file located at `$MANAGIX_HOME/conf/managix-conf.xml`.
+The backup command allows you to take a backup of the data stored with an AsterixDB instance. The backup can be taken on the local file system or on an HDFS instance. In either case, the snapshots are stored under a backup directory. You need to make sure the backup directory has appropriate read/write permissions. Configuring settings for backup can be found inside the Managix's configuration file located at `$MANAGIX_HOME/conf/managix-conf.xml`.
*Configuring backup on the local file system*
-We need to provide path to a backup directory on the local file system. The backup directory can be configured be editing the Managix configuration XML, found at `$MANAGIX_HOME/conf/managix-conf.xml`.
+We need to provide a path to a backup directory on the local file system. The backup directory can be configured be editing the Managix configuration XML, found at `$MANAGIX_HOME/conf/managix-conf.xml`.
<backup>
<backupDir>Provide path to the backup directory here</backupDir>
</backup>
-Prior to taking a backup of an ASTERIX instance, it is required for the instance to be in the INACTIVE state. We do so by using the `stop` command, as shown below:
+Prior to taking a backup of an AsterixDB instance, it is required for the instance to be in the INACTIVE state. We do so by using the `stop` command, as shown below:
$ managix stop -n my_asterix
- INFO: Stopped Asterix instance: my_asterix
+ INFO: Stopped AsterixDB instance: my_asterix
We can now take the backup by executing the following:
@@ -722,7 +722,7 @@
*Configuring backup on an HDFS instance*
-To configure a backups to be taken on an HDFS instance, we need to provide required information about the running HDFS instance. This information includes the HDFS version and the HDFS url. Simply edit the Managix configuration file and provide the required information.
+To configure a backup to be taken on an HDFS instance, we need to provide required information about the running HDFS instance. This information includes the HDFS version and the HDFS url. Simply edit the Managix configuration file and provide the required information.
<backup>
@@ -760,41 +760,41 @@
Processes
-The above output shows the available backup identified by it's id (0). We shall next describe the method for restoring an ASTERIX instance from a backup snapshot.
+The above output shows the available backup identified by it's id (0). We shall next describe the method for restoring an AsterixDB instance from a backup snapshot.
##### Restore Command #####
-The `restore` command allows you to restore an ASTERIX instance's data from a previously taken backup. The usage description can be obtained as follows:
+The `restore` command allows you to restore an AsterixDB instance's data from a previously taken backup. The usage description can be obtained as follows:
$ managix help -cmd restore
- Restores an ASTERIX instance's data from a previously taken backup.
+ Restores an AsterixDB instance's data from a previously taken backup.
Available arguments/options
- -n name of the ASTERIX instance
+ -n name of the AsterixDB instance
-b id of the backup snapshot
-The following command restores our ASTERIX instance from the backup snapshot identified by the id (0). Prior to restoring an instance from a backup, it is required that the instance is in the INACTIVE state.
+The following command restores our AsterixDB instance from the backup snapshot identified by the id (0). Prior to restoring an instance from a backup, it is required that the instance is in the INACTIVE state.
$ managix restore -n my_asterix -b 0
- INFO: Asterix instance: my_asterix has been restored from backup
+ INFO: AsterixDB instance: my_asterix has been restored from backup
-You can start the ASTERIX instance by using the start command.
+You can start the AsterixDB instance by using the start command.
##### Log Command #####
-The `log` command allows you to collect the log files coresponding to each node of an Asterix instance into a zip archive.
+The `log` command allows you to collect the log files coresponding to each node of an AsterixDB instance into a zip archive.
The zip archive is produced on the local file system of the machine running managix.
$ managix help -cmd log
- Creates a zip archive containing log files corresponding to each worker node (NC) and the master (CC) for an ASTERIX instance
+ Creates a zip archive containing log files corresponding to each worker node (NC) and the master (CC) for an AsterixDB instance
Available arguments/options
- -n name of the ASTERIX instance.
+ -n name of the AsterixDB instance.
-d destination directory for producing the tar ball (defaults to) /Users/ramang/asterix-installer
The following is an example showing the use of the log command.
@@ -804,22 +804,22 @@
##### Delete Command #####
-As the name suggests, the `delete` command permanently removes an ASTERIX instance by cleaning up all associated data/artifacts. The usage can be looked up by executing the following:
+As the name suggests, the `delete` command permanently removes an AsterixDB instance by cleaning up all associated data/artifacts. The usage can be looked up by executing the following:
$ managix help -cmd delete
- Permanently deletes an ASTERIX instance. The instance must be in the INACTIVE state.
+ Permanently deletes an AsterixDB instance. The instance must be in the INACTIVE state.
Available arguments/options
- -n name of the ASTERIX instance.
+ -n name of the AsterixDB instance.
$ managix delete -n my_asterix
- INFO: Asterix instance my_asterix deleted.
+ INFO: AsterixDB instance my_asterix deleted.
##### Shutdown Command #####
-Managix uses Zookeeper service for storing all information about created ASTERIX instances. The Zookeeper service runs in the background and can be shut down using the `shutdown` command.
+Managix uses Zookeeper service for storing all information about created AsterixDB instances. The Zookeeper service runs in the background and can be shut down using the `shutdown` command.
$ managix shutdown
@@ -836,7 +836,7 @@
$ managix help -cmd configure
- Auto-generates the ASTERIX installer configruation settings and ASTERIX cluster
+ Auto-generates the AsterixDB installer configruation settings and AsterixDB cluster
configuration settings for a single node setup.
@@ -847,12 +847,12 @@
What happens if a machine acting as a node in the Asterix cluster becomes unreachable for some reason (network partition/machine failure) ?
*Answer*
-When a node leaves the Asterix cluster, the Asterix instance transits to an 'UNUSABLE' state, indicating that it is no longer
+When a node leaves the Asterix cluster, the AsterixDB instance transits to an 'UNUSABLE' state, indicating that it is no longer
available for serving queries. To know which set of node(s) left the cluster, run the describe command with -admin flag.
- $ $MANAGIX_HOME/bin/managix describe -n <name of the Asterix instance>-admin
+ $ $MANAGIX_HOME/bin/managix describe -n <name of the AsterixDB instance>-admin
-Above command will show the state of Asterix instance and list the set of nodes that have left the cluster.
+Above command will show the state of AsterixDB instance and list the set of nodes that have left the cluster.
The failed node must be brought back to re-join the cluster. Once done, you may bring back the
instance to an 'ACTIVE' state by executing the following sequence.
@@ -864,9 +864,9 @@
The processes associated with the instance are terminated and the instance moves to the INACTIVE state.
-2) Start the Asterix instance using the start command.
+2) Start the AsterixDB instance using the start command.
- $MANAGIX_HOME/bin/managix start -n <name of your ASTERIX instance>
+ $MANAGIX_HOME/bin/managix start -n <name of your AsterixDB instance>
*Question*