Blame - install.html - incubator-asterixdb-site

<p>This is a quickstart guide for getting AsterixDB running in a distributed environment. This guide also introduces the AsterixDB installer (nicknamed <i><i>Managix</i></i>) 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 <i><i>Linux</i></i> or <i><i>MacOS X</i></i>.</p></div>

218

219

<h2><a name="PrerequisitesForInstallingAsterixDB" id="PrerequisitesForInstallingAsterixDB">Prerequisites for Installing AsterixDB</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Prerequisites_for_Installing_AsterixDB_Back_to_TOC"></a></h2>

<p>Prerequisite:</p>

<ul>

<li><a class="externalLink" href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK>=7</a> (Otherwise known as JDK>=1.7).</li>

225

</ul>

226

<p>To know the version of Java installed on your system, execute the following:</p>

227

228

229

<pre> $ java -version

230

</pre></div>

231

<p>If your version is at least 1.7.0_x, similar to the output shown below, you are good to proceed.</p>

232

233

234

<pre> java version "1.7.0_13"

235

Java(TM) SE Runtime Environment (build 1.7.0_13-b20)

236

Java HotSpot(TM) 64-Bit Server VM (build 23.7-b01, mixed mode)

237

</pre></div>

238

<p>If you need to upgrade or install java, please follow the instructions below.</p>

<ul>

<li>

<p>For Linux: <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/webnotes/install/linux/linux-jdk.html">JDK 7 Linux Install</a> JDK would be installed at a path under /usr/lib/jvm/jdk-version .</p></li>

244

245

<li>

246

<p>For Mac: <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/webnotes/install/mac/mac-jdk.html">JDK 7 Mac Install</a> JDK would be installed at /Library/Java/JavaVirtualMachines/jdk-version/Contents/Home .</p></li>

247

</ul>

248

<p>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. Modify your ~/.bash_profile (or ~/.bashrc) and define JAVA_HOME accordingly. After the modification, execute the following:</p>

249

250

251

<pre> $ java -version

252

</pre></div>

253

<p>If the version information you obtain does not show 1.7, you need to update the PATH variable. To do so, execute the following:</p>

254

255

256

<pre> $ echo "PATH=$JAVA_HOME/bin:$PATH" >> ~/.bash_profile (or ~/.bashrc)

257

$ source ~/.bash_profile (or ~/.bashrc)

258

</pre></div></div>

259

260

<h2><a name="Section1SingleMachineAsterixDBInstallation" id="Section1SingleMachineAsterixDBInstallation">Section 1: Single-Machine AsterixDB installation</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Section_1:_Single-Machine_AsterixDB_installation_Back_to_TOC"></a></h2>

261

<p>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.</p>

262

263

<h3>Configuring Environment<a name="Configuring_Environment"></a></h3>

264

<p>Ensure that JAVA_HOME variable is defined and points to the the java installation directory on your machine. To verify, execute the following:</p>

265

266

267

<pre> $ echo $JAVA_HOME

268

</pre></div>

269

<p>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.</p>

270

271

272

<pre> export JAVA_HOME=<Path to Java installation directory>

273

</pre></div>

274

<p>After you have edited ~/.bash_profile (or ~/.bashrc), execute the following to make the changes effective in current shell:</p>

275

276

277

<pre> $ source /home/joe/.bash_profile (or /home/joe/.bashrc)

278

</pre></div>

279

<p>Before proceeding, verify that JAVA_HOME is defined by executing the following:</p>

280

281

282

<pre> $ echo $JAVA_HOME

283

</pre></div></div>

284

285

<h3>Configuring SSH<a name="Configuring_SSH"></a></h3>

286

<p>If SSH is not enabled on your system, please follow the instruction below to enable/install it or else skip to the section <a href="#Configuring_Password-less_SSH">Configuring Password-less SSH</a>.</p>

287

288

<h4>Enabling SSH on Mac<a name="Enabling_SSH_on_Mac"></a></h4>

289

<p>The Apple Mac OS X operating system has SSH installed by default but the SSH daemon is not enabled. This means you can’t login remotely or do remote copies until you enable it. To enable it, go to ‘System Preferences’. Under ‘Internet & Networking’ there is a ‘Sharing’ icon. Run that. In the list that appears, check the ‘Remote Login’ option. Also check the “All users” radio button for “Allow access for”. This starts the SSH daemon immediately and you can remotely login using your username. The ‘Sharing’ window shows at the bottom the name and IP address to use. You can also find this out using ‘whoami’ and ‘ifconfig’ from the Terminal application.</p></div>

290

291

<h4>Enabling SSH on Linux<a name="Enabling_SSH_on_Linux"></a></h4>

292

293

294

<pre> sudo apt-get install openssh-server

295

</pre></div>

296

<p>Assumming that you have enabled SSH on your system, let us proceed.</p></div>

297

298

<h4>Configuring Password-less SSH<a name="Configuring_Password-less_SSH"></a></h4>

299

<p>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:</p>

300

301

302

<pre> $ ssh 127.0.0.1

303

</pre></div>

304

<p>If you get an output similar to one shown below, type “yes” and press enter.</p>

305

306

307

<pre> The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.

308

RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.

309

Are you sure you want to continue connecting (yes/no)?

310

</pre></div>

311

<p>If you are not prompted for a password, that is if you get an output similar to one shown below, it signifies that you already have password-less SSH configured. </p>

312

313

314

<pre> $ ssh 127.0.0.1

315

Last login: Sat Mar 23 22:52:49 2013

316

</pre></div>

317

<p>[Important: Password-less SSH requires the use of a (public,private) key-pair. The key-pair is located as a pair of files under $HOME/.ssh directory. It is required that the (public,private) key-pair files have default names (id_rsa.pub, id_rsa) respectively. If you are using different names, please rename the files to use the default names]</p>

318

<p>Skip to the next section <a href="#Configuring_Managix">Configuring Managix</a>.</p>

319

<p>You are here because you were prompted for a password. You need to configure password-less SSH.<br />We shall generate a (public,private) key-pair as id_rsa.pub and id_rsa respectively. If $HOME/.ssh already contains a (public,private) key-pair, please ensure the files are renamed before proceeding. Follow the instructions below.</p>

320

321

322

<pre> $ ssh-keygen -t rsa -P ""

323

Generating public/private rsa key pair.

324

Enter file in which to save the key (/home/joe/.ssh/id_rsa):

325

[Important: Please ensure that we use the default value, so simply press enter]

326

</pre></div>

327

<p>If a key already exists, you should get an output similar to what is shown below. Press ‘y’ to overwrite the existing key. It is required to use the default name. If you wish to not overwrite a pre-existing key, ensure that the pre-existing key is saved with a different name.</p>

328

329

330

<pre> /home/joe/.ssh/id_rsa already exists.

331

Overwrite (y/n)?

332

</pre></div>

333

<p>You should see an output similar to one shown below:</p>

334

335

336

<pre> The key fingerprint is:

337

4d:b0:30:14:45:cc:99:86:15:48:17:0b:39:a0:05:ca joe@joe-machine

338

The key's randomart image is:

+--[ RSA 2048]----+

| ..o+B@O= |

|.. o ==*+ |

|.E. oo . |

| o |

| S . |

| |

| |

| |

| |

+-----------------+

</pre></div>

<p>Note: for Linux users, you may not get an image representation of the key, but this is not an error. Next, execute the following:</p>

352

353

354

<pre> $ cat $HOME/.ssh/id_rsa.pub >> $HOME/.ssh/authorized_keys

355

$ chmod 700 $HOME/.ssh/authorized_keys

356

</pre></div>

357

<p>We shall now retry SSH without password.</p>

358

359

360

<pre> $ ssh 127.0.0.1

361

</pre></div>

362

<p>You may see an output similar to one shown below:</p>

363

364

365

<pre> The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.

366

RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.

367

Are you sure you want to continue connecting (yes/no)?

368

</pre></div>

369

<p>Type ‘yes’ and press the enter key. You should see an output similar to one shown below:</p>

370

371

372

<pre> Warning: Permanently added '127.0.0.1' (RSA) to the list of known hosts.

373

Last login: Thu Mar 28 12:27:10 2013

374

</pre></div>

375

<p>You should now be able to log in without being prompted for a password or a response.</p>

<pre> ssh 127.0.0.1

Last login: Sat Mar 23 22:54:40 2013

380

</pre></div>

381

<p>Execute ‘exit’ to close the session.</p>

<pre> $ exit

logout

Connection to 127.0.0.1 closed.

387

</pre></div></div></div>

388

389

<h3>Configuring Managix<a name="Configuring_Managix"></a></h3>

390

<p>You will need the AsterixDB installer (a.k.a. Managix). Download Managix from <a class="externalLink" href="http://asterixdb.ics.uci.edu/download.html">here</a>; this includes the bits for Managix as well as AsterixDB.</p>

391

<p>To be able to create an AsterixDB instance and manage its lifecycle, the Managix requires you to configure a set of configuration files namely:</p>

<ul>

<li><tt>conf/managix-conf.xml</tt>: A configuration XML file that contains configuration settings for Managix.</li>

396

397

<li>A configuration XML file that describes the nodes in the cluster, e.g., <tt>clusters/local/local.xml</tt>.</li>

398

</ul>

399

<p>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:</p>

400

401

402

<pre> /home/joe/asterix-mgmt> $ managix configure

403

</pre></div>

404

<p>Let us do a sample run to validate the set of configuration files auto-generated by Managix.</p>

405

406

407

<pre> /home/joe/asterix-mgmt> $ managix validate

408

INFO: Environment [OK]

409

INFO: Managix Configuration [OK]

410

411

412

/home/joe/asterix-mgmt> $ managix validate -c clusters/local/local.xml

413

INFO: Environment [OK]

414

INFO: Cluster configuration [OK]

415

</pre></div></div>

416

417

<h3>Creating an AsterixDB instance<a name="Creating_an_AsterixDB_instance"></a></h3>

418

<p>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 <tt>create</tt> command. The usage description for the <tt>create</tt> command can be obtained by executing the following:</p>

419

420

421

<pre> $ managix help -cmd create

422

Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,

423

indicating its availability for executing statements/queries.

424

Usage arguments/options:

425

-n Name of the AsterixDB instance.

426

-c Path to the cluster configuration file

427

</pre></div>

428

<p>We shall now use the <tt>create</tt> 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.</p>

429

430

431

<pre> $ managix create -n my_asterix -c clusters/local/local.xml

432

</pre></div>

433

<p>A sample output of the above command is shown below:</p>

434

435

436

<pre> INFO: Name:my_asterix

437

Created:Thu Mar 07 11:14:13 PST 2013

438

Web-Url:http://127.0.0.1:19001

439

State:ACTIVE

440

</pre></div>

441

<p>The third line above shows the web-url <a class="externalLink" href="http://127.0.0.1:19001">http://127.0.0.1:19001</a> 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.</p>

442

<p>Type in the following “Hello World” query in the box:</p>

443

444

445

<pre> let $message := 'Hello World!'

446

return $message

447

</pre></div>

448

<p>Press the “Run” button. If the query result shows on the output box, then Congratulations! You have successfully created an AsterixDB instance!</p></div></div>

449

450

<h2><a name="Section2SingleMachineAsterixDBInstallationAdvanced" id="Section2SingleMachineAsterixDBInstallationAdvanced">Section 2: Single-Machine AsterixDB installation (Advanced)</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Section_2:_Single-Machine_AsterixDB_installation_Advanced_Back_to_TOC"></a></h2>

451

<p>We assume that you have successfully completed the single-machine AsterixDB installation by following the instructions above in section <a href="#Section_1:_Single-Machine_AsterixDB_installation">AsterixDB installation</a>. 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.</p>

452

453

<h3>AsterixDB Runtime<a name="AsterixDB_Runtime"></a></h3>

454

<p>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.</p>

455

456

<h4>AsterixDB Runtime Configuration<a name="AsterixDB_Runtime_Configuration"></a></h4>

457

<p>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 <tt>configure</tt> 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:</p>

<name>local</name>

<java_home>/usr/lib/jvm/jdk1.7.0</java_home>

464

<log_dir>/home/joe/asterix-mgmt/clusters/local/working_dir/logs</log_dir>

465

<txn_log_dir>/home/joe/asterix-mgmt/clusters/local/working_dir/logs</txn_log_dir>

466

<iodevices>/home/joe/asterix-mgmt/clusters/local/working_dir</iodevices>

467

<store>storage</store>

468

<working_dir>

469

<dir>/home/joe/asterix-mgmt/clusters/local/working_dir</dir>

</working_dir>

<master_node>

<id>master</id>

<client_ip>127.0.0.1</client_ip>

475

<cluster_ip>127.0.0.1</cluster_ip>

476

<client_port>1098</client_port>

477

<cluster_port>1099</cluster_port>

478

<http_port>8888</http_port>

</master_node>

<node>

<cluster_ip>127.0.0.1</cluster_ip>

</node>

</cluster>

</pre></div>

<p>We shall next explain the components of the cluster configuration XML file.</p></div>

487

488

<h4>(1) Defining nodes in AsterixDB runtime<a name="a1_Defining_nodes_in_AsterixDB_runtime"></a></h4>

489

<p>The single-machine AsterixDB instance configuration that is auto-generated by Managix (using the <tt>configure</tt> 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.</p>

<id>master</id>

<client_ip>127.0.0.1</client_ip>

495

<cluster_ip>127.0.0.1</cluster_ip>

496

<client_port>1098</client_port>

497

<cluster_port>1099</cluster_port>

498

<http_port>8888</http_port>

</master_node>

<node>

<cluster_ip>127.0.0.1</cluster_ip>

503

</node>

504

</pre></div>

505

<p>The following is a description of the different elements in the cluster configuration xml file.</p>

<td>Property</td>

<td>Description</td>

</tr>

<td>A unique id for a node.</td>

</tr>

<td>cluster_ip</td>

<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>

<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>

<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>

<td>cluster_port</td>

547

548

<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>

<td>Provided for the master node. This is the http port used by the Cluster Controller (CC) service. </td>

</tr>

</table></div>

<h4>(2) Properties associated with a worker node (NC) in AsterixDB<a name="a2_Properties_associated_with_a_worker_node_NC_in_AsterixDB"></a></h4>

561

<p>The following is a list of properties associated with each worker node in an AsterixDB configuration.</p>

<td>Property</td>

<td>Description</td>

</tr>

<td>Java installation directory at each node.</td>

</tr>

<td>A directory where the worker node JVM may write logs.</td>

</tr>

<td>A directory where the worker node writes transaction logs.</td>

</tr>

<td>iodevices</td>

<td>Comma separated list of IO Device mount points.</td>

</tr>

<td>store</td>

<td>A data directory (under each iodevice) that AsterixDB uses to store data belonging to dataset(s).</td>

605

</tr>

606

</table>

607

<p>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.</p></div>

608

609

<h4>(3) Working directory of an AsterixDB instance<a name="a3_Working_directory_of_an_AsterixDB_instance"></a></h4>

610

<p>Next we explain the following setting in the file $MANAGIX_HOME/clusters/local/local.xml.</p>

<dir>/Users/joe/asterix-mgmt/clusters/local/working_dir</dir>

</working_dir>

</pre></div>

<p>Managix associates a working directory with an AsterixDB instance and uses this directory for transferring binaries to each node. If there is 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 <tt>true</tt>.</p></div></div>

619

620

<h3>Managix Configuration<a name="Managix_Configuration"></a></h3>

621

<p>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 <tt>$MANAGIX_HOME/conf/managix-conf.xml</tt> that has Zookeeper running on the localhost (127.0.0.1) :</p>

<homeDir>/home/joe/asterix/.installer/zookeeper</homeDir>

</servers>

</zookeeper>

</configuration>

</pre></div>

<p>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.</p></div></div>

636

637

<h2><a name="Section3InstallingAsterixDBOnAClusterOfMultipleMachines" id="Section3InstallingAsterixDBOnAClusterOfMultipleMachines">Section 3: Installing AsterixDB on a Cluster of Multiple Machines</a><font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Section_3:_Installing_AsterixDB_on_a_Cluster_of_Multiple_MachinesBack_to_TOC"></a></h2>

638

<p>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:</p>

Till Westmann

0817a3f

2015-06-03 21:08:18 -0700

[diff] [blame^]

639

Ian Maxon

ed124d8

2015-05-29 18:44:11 -0700

[diff] [blame]

640

<p>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.</p>

641

<p>Next we describe how to set up AsterixDB in this cluster, assuming no Managix has been installed on these machines.</p>

642

643

<h3>Step (1): Configure SSH<a name="Step_1:_Configure_SSH"></a></h3>

644

<p>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.</p>

645

<p>On the master machine, do the following:</p>

646

647

648

<pre> machineA> ssh 127.0.0.1

649

</pre></div>

650

<p>If you get an output similar to one shown below, type “yes” and press enter.</p>

651

652

653

<pre> The authenticity of host '127.0.0.1 (127.0.0.1)' can't be established.

654

RSA key fingerprint is aa:7b:51:90:74:39:c4:f6:28:a2:9d:47:c2:8d:33:31.

655

Are you sure you want to continue connecting (yes/no)?

656

</pre></div>

657

<p>If you are not prompted for a password, that is if you get an output similar to one shown below, it signifies that you already have password-less SSH configured. </p>

658

659

660

<pre> $ ssh 127.0.0.1

661

Last login: Sat Mar 23 22:52:49 2013

662

</pre></div>

663

<p>[Important: Password-less SSH requires the use of a (public,private) key-pair. The key-pair is located as a pair of files under $HOME/.ssh directory. It is required that the (public,private) key-pair files have default names (id_rsa.pub, id_rsa) respectively. If you are using different names, please rename the files to use the default names]</p>

664

<p>If you are prompted for a password, execute the following</p>

665

666

667

<pre> machineA> ssh-keygen -t rsa -P ""

668

machineA> cat $HOME/.ssh/id_rsa.pub >> $HOME/.ssh/authorized_keys

669

machineA> chmod 700 $HOME/.ssh/authorized_keys

670

</pre></div>

671

<p>If $HOME is not on the NFS, copy the id_rsa.pub to the directory ~/.ssh (login with the same account) on each machine, and then do the following on each machine. (Notice that this step is not needed if the folder “.ssh” is on the NFS and can be accessed by all the nodes.)</p>

<pre> cd ~/.ssh

cat id_rsa.pub >> authorized_keys

676

chmod 700 $HOME/.ssh/authorized_keys

677

</pre></div>

678

<p>Then run the following step again and type “yes” if prompted:</p>

679

680

681

<pre> machineA> ssh 127.0.0.1

682

</pre></div></div>

683

684

<h3>Step (2): Define the AsterixDB cluster<a name="Step_2:_Define_the_AsterixDB_cluster"></a></h3>

685

<p>We first log into the master machine as the user “joe”. On this machine, download Managix from <a class="externalLink" href="http://asterixdb.ics.uci.edu/download.html">here</a> (save as above), then do the following steps similar to the single-machine case described above:</p>

<pre> machineA> cd ~

machineA> mkdir asterix-mgmt

690

machineA> cd asterix-mgmt

691

machineA> unzip <path to the Managix zip bundle>

692

</pre></div>

693

<p>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.</p>

694

<p>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:</p>

695

696

697

<pre> machineA> mkdir asterix-mgmt/rainbow_cluster

698

</pre></div>

699

<p>For this cluster we create a configuration file <tt>$MANAGIX_HOME/rainbow_cluster/rainbow.xml</tt>. The following is a sample file with explanation of the properties:</p>

705

<name>rainbow</name>

706

707

708

709

710

<!-- The working directory of Managix. It is recommended for the working

711

directory to be on a network file system (NFS) that can accessed by

712

all machines.

713

Managix creates the directory if it it doesn't exist. -->

714

<working_dir>

715

<dir>/home/joe/managix-workingDir</dir>

</working_dir>

<!-- Directory for Asterix to store worker logs information for each machine.

720

Needs to be on the local file system of each machine.

721

Managix creates the directory if it doesn't exist.

722

This property can be overriden for a node by redefining at the node level. -->

723

<log_dir>/mnt/joe/logs</log_dir>

724

725

<!-- Directory for Asterix to store transaction log information for each machine.

726

Needs to be on the local file system of each machine.

727

Managix creates the directory if it doesn't exist.

728

This property can be overriden for a node by redefining at the node level. -->

729

<txn_log_dir>/mnt/joe/txn_logs</txn_log_dir>

730

731

<!-- Mount point of an iodevice. Use a comma separated list for a machine that

732

has multiple iodevices (disks).

733

This property can be overriden for a node by redefining at the node level. -->

734

735

736

737

<store>storage</store>

738

739

740

<java_home>/usr/lib/jvm/jdk1.7.0</java_home>

741

742

743

<master_node>

744

<id>master</id>

745

<client_ip>128.195.52.177</client_ip>

746

<cluster_ip>192.168.100.0</cluster_ip>

747

<client_port>1098</client_port>

748

<cluster_port>1099</cluster_port>

749

<http_port>8888</http_port>

750

</master_node>

751

752

753

<node>

754

<id>nodeB</id>

755

<cluster_ip>192.168.100.1</cluster_ip>

756

</node>

757

758

759

<node>

760

<id>nodeC</id>

761

<cluster_ip>192.168.100.2</cluster_ip>

</node>

</cluster>

</pre></div>

<p>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.</p>

766

<p>Once we have formed the cluster XML file, we can validate the configuration by doing the following:</p>

767

768

769

<pre> managix validate -c rainbow_cluster/rainbow.xml

770

</pre></div>

771

<p>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</p>

772

773

774

<pre> The authenticity of host '192.168.100.1 (192.168.100.1)' can't be established.

775

RSA key fingerprint is 89:80:31:1f:be:51:16:d7:2b:f5:e0:b3:2c:bd:83:94.

776

Are you sure you want to continue connecting (yes/no)?

777

</pre></div>

778

<p>and this output may be repeated for each node in the cluster. Answer “yes” each time.</p>

779

<p>If the final output contains the following lines (possibly separated by the RSA prompts mentione above):</p>

780

781

782

<pre> INFO: Environment [OK]

783

INFO: Cluster configuration [OK]

784

</pre></div>

785

<p>it means that the XML configuration file is correct!</p></div>

786

787

<h3>Step (3): Configuring Managix<a name="Step_3:_Configuring_Managix"></a></h3>

788

<p>Managix uses a configuration XML file at <tt>$MANAGIX_HOME/conf/managix-conf.xml</tt> to configure its own properties, such as its Zookeeper service. We can use the <tt>configure</tt> command to auto-generate this configuration file:</p>

789

790

791

<pre> machineA> managix configure

792

</pre></div>

793

<p>We use the <tt>validate</tt> command to validate the Managix configuration. To do so, execute the following.</p>

794

795

796

<pre> machineA> managix validate

797

INFO: Environment [OK]

798

INFO: Managix Configuration [OK]

799

</pre></div>

800

<p>Note that the <tt>configure</tt> 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.</p></div>

801

802

<h3>Step (4): Creating an AsterixDB instance<a name="Step_4:_Creating_an_AsterixDB_instance"></a></h3>

803

<p>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 <tt>create</tt> command. The usage description for the <tt>create</tt> command can be obtained by executing the following:</p>

804

805

806

<pre> machineA> managix help -cmd create

807

808

Creates an AsterixDB instance with a specified name. Post creation, the instance is in ACTIVE state,

809

indicating its availability for executing statements/queries.

810

Usage arguments/options:

811

-n Name of the AsterixDB instance.

812

-c Path to the cluster configuration file

813

</pre></div>

814

<p>We shall now use the <tt>create</tt> 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.</p>

815

816

817

<pre> machineA> managix create -n rainbow_asterix -c clusters/rainbow.xml

818

</pre></div>

819

<p>If the response message does not have warning, then Congratulations! You have successfully installed AsterixDB on this cluster of machines!</p>

820

<p>Please refer to the section <a href="#Section_4:_Managing_the_Lifecycle_of_an_AsterixDB_Instance">Managing the Lifecycle of an AsterixDB Instance</a> 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.</p></div></div>

821

822

<h2><a name="Section4ManagingTheLifecycleOfAnAsterixDBInstance" id="Section4ManagingTheLifecycleOfAnAsterixDBInstance">Section 4: Managing the Lifecycle of an AsterixDB Instance</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Section_4:_Managing_the_Lifecycle_of_an_AsterixDB_Instance_Back_to_TOC"></a></h2>

823

<p>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:</p>

824

825

826

<h4>Managix Commands<a name="Managix_Commands"></a></h4>

<td>Command</td>

<td>Description</td></tr>

833

834

835

<td><a href="#Creating_an_AsterixDB_instance">create</a></td>

836

<td>Creates a new asterix instance.</td></tr>

837

838

839

<td><a href="#Describe_Command">describe</a></td>

840

<td>Describes an existing asterix instance.</td></tr>

<td>Stops an asterix instance that is in the ACTIVE state.</td></tr>

845

846

847

<td><a href="#Start_Command">start</a></td>

848

<td>Starts an AsterixDB instance.</td></tr>

849

850

851

<td><a href="#Backup_Command">backup</a></td>

852

<td>Creates a backup for an existing AsterixDB instance.</td></tr>

853

854

855

<td><a href="#Restore_Command">restore</a></td>

856

<td>Restores an AsterixDB instance.</td></tr>

857

858

859

<td><a href="#Delete_Command">delete</a></td>

860

<td>Deletes an AsterixDB instance.</td></tr>

861

862

863

<td><a href="#Configuring_Managix">validate</a></td>

864

<td>Validates the installer/cluster configuration.</td></tr>

865

866

867

<td><a href="#Configuring_Managix">configure</a></td>

868

<td>Auto generates a configuration for an AsterixDB instance.</td></tr>

<td>Produces a zip archive containing log files from each node in an AsterixDB instance.</td></tr>

873

874

875

<td><a href="#Shutdown_Command">shutdown</a></td>

876

<td>Shuts down the installer service.</td></tr>

877

</table>

878

<p>You may obtain the above listing by simply executing ‘managix’ :</p>

<pre> $ managix

</pre></div>

<p>We already talked about <tt>create</tt> and <tt>validate</tt> 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.</p>

884

885

<h5>Describe Command<a name="Describe_Command"></a></h5>

886

<p>The <tt>describe</tt> command provides information about an AsterixDB instance. The usage can be looked up by executing the following:</p>

887

888

889

<pre> $ managix help -cmd describe

890

891

Provides information about an AsterixDB instance.

892

The following options are available:

893

[-n] Name of the AsterixDB instance.

894

[-admin] Provides a detailed description

895

</pre></div>

896

<p>The brackets indicate optional flags.</p>

897

<p>The output of the <tt>describe</tt> command when used without the <tt>admin</tt> flag contains minimal information and is similar to the output of the <tt>create</tt> command. Let us try running the describe command in “admin” mode.</p>

898

899

900

<pre> $ managix describe -n my_asterix -admin

901

INFO: Name:my_asterix

902

Created:Thu Mar 07 19:07:00 PST 2013

903

Web-Url:http://127.0.0.1:19001

904

State:ACTIVE

905

Master node:master:127.0.0.1

906

node1:127.0.0.1

907

908

Asterix version:0.0.5

909

Asterix Configuration

910

output_dir = /tmp/asterix_output/

911

Metadata Node:node1

912

Processes

913

NC at 127.0.0.1 [ 22195 ]

914

CC at 127.0.0.1 [ 22161 ]

915

916

Asterix Configuration

917

nc.java.opts :-Xmx1024m

918

cc.java.opts :-Xmx1024m

919

storage.buffercache.pagesize :32768

920

storage.buffercache.size :33554432

921

storage.buffercache.maxopenfiles :214748364

922

storage.memorycomponent.pagesize :32768

923

storage.memorycomponent.numpages :1024

924

storage.memorycomponent.globalbudget :536870192

925

storage.lsm.mergethreshold :3

926

storage.lsm.bloomfilter.falsepositiverate:0.01

927

txn.log.buffer.numpages :8

928

txn.log.buffer.pagesize :131072

929

txn.log.partitionsize :2147483648

930

txn.log.disksectorsize :4096

931

txn.log.groupcommitinterval :1

932

txn.log.checkpoint.lsnthreshold :67108864

933

txn.log.checkpoint.pollfrequency :120

934

txn.log.checkpoint.history :0

935

txn.lock.escalationthreshold :1000

936

txn.lock.shrinktimer :5000

937

txn.lock.timeout.waitthreshold :60000

938

txn.lock.timeout.sweepthreshold :10000

939

compiler.sortmemory :33554432

940

compiler.joinmemory :33554432

941

compiler.framesize :32768

web.port :19001

api.port :19002

log.level :INFO

</pre></div>

<p>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.</p></div>

947

948

<h5>Stop Command<a name="Stop_Command"></a></h5>

949

<p>The <tt>stop</tt> 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.</p>

950

951

952

<pre> $ managix help -cmd stop

953

954

Shuts an AsterixDB instance that is in ACTIVE state. After executing the stop command, the AsterixDB instance transits

955

to the INACTIVE state, indicating that it is no longer available for executing queries.

956

957

Available arguments/options

958

-n name of the AsterixDB instance.

959

</pre></div>

960

<p>To stop the AsterixDB instance.</p>

961

962

963

<pre> $ managix stop -n my_asterix

964

INFO: Stopped AsterixDB instance: my_asterix

965

966

967

$ managix describe -n my_asterix

968

INFO: Name: my_asterix

969

Created:Thu Mar 07 19:07:00 PST 2013

970

Web-Url:http://127.0.0.1:19001

971

State:INACTIVE (Fri Mar 08 09:49:00 PST 2013)

972

</pre></div></div>

973

974

<h5>Start Command<a name="Start_Command"></a></h5>

975

<p>The <tt>start</tt> command starts an AsterixDB instance that is in the INACTIVE state. The usage can be looked up by executing the following:</p>

976

977

978

<pre> $ managix help -cmd start

979

980

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.

981

982

Available arguments/options

983

-n name of the AsterixDB instance.

984

</pre></div>

985

<p>Let us now start the AsterixDB instance.</p>

986

987

988

<pre> $ managix start -n my_asterix

989

INFO: Name:my_asterix

990

Created:Thu Mar 07 19:07:00 PST 2013

991

Web-Url:http://127.0.0.1:19001

992

State:ACTIVE (Fri Mar 08 09:49:00 PST 2013)

993

</pre></div></div>

994

995

<h5>Backup Command<a name="Backup_Command"></a></h5>

996

<p>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 <tt>$MANAGIX_HOME/conf/managix-conf.xml</tt>.</p>

997

<p><i>Configuring backup on the local file system</i></p>

998

<p>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 <tt>$MANAGIX_HOME/conf/managix-conf.xml</tt>.</p>

<backupDir>Provide path to the backup directory here</backupDir>

1003

</backup>

1004

</pre></div>

1005

<p>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 <tt>stop</tt> command, as shown below:</p>

1006

1007

1008

<pre> $ managix stop -n my_asterix

1009

INFO: Stopped AsterixDB instance: my_asterix

1010

</pre></div>

1011

<p>We can now take the backup by executing the following:</p>

1012

1013

1014

<pre> $ managix backup -n my_asterix

1015

INFO: my_asterix backed up 0_Fri Mar 08 16:16:34 PST 2013 (LOCAL)

1016

</pre></div>

1017

<p><i>Configuring backup on an HDFS instance</i></p>

1018

<p>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.</p>

<backupDir>Provide path to the backup directory here</backupDir>

<hdfs>

</hdfs>

</backup>

</pre></div>

<p>A sample output when a backup is taken on an HDFS is shown below:</p>

1030

1031

1032

<pre> $ managix backup -n my_asterix

1033

INFO: my_asterix backed up 1_Fri Mar 08 17:10:38 PST 2013 (HDFS)

1034

</pre></div>

1035

<p>Each time we take a backup, we are provided with a unique id (a monotonically increasing value starting with 0). This id is required when we need to restore from a previously taken backup. Information about all available backup snapshots can be obtained by using the <tt>describe</tt> command in the admin mode, as shown below:</p>

1036

1037

1038

<pre> $ managix describe -n my_asterix -admin

1039

INFO: Name:my_asterix

1040

Created:Fri Mar 08 15:11:12 PST 2013

1041

Web-Url:http://127.0.0.1:19001

1042

State:INACTIVE (Fri Mar 08 16:14:20 PST 2013)

1043

Master node:master:127.0.0.1

1044

node1:127.0.0.1

1045

1046

Backup:0 created at Fri Mar 08 16:16:34 PST 2013 (LOCAL)

1047

Backup:1 created at Fri Mar 08 17:10:38 PST 2013 (HDFS)

1048

1049

Asterix version:0.0.5

1050

Asterix Configuration

Metadata Node:node1

Processes

</pre></div>

<p>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.</p></div>

1055

1056

<h5>Restore Command<a name="Restore_Command"></a></h5>

1057

<p>The <tt>restore</tt> command allows you to restore an AsterixDB instance’s data from a previously taken backup. The usage description can be obtained as follows:</p>

1058

1059

1060

<pre> $ managix help -cmd restore

1061

1062

Restores an AsterixDB instance's data from a previously taken backup.

1063

Available arguments/options

1064

1065

-n name of the AsterixDB instance

1066

-b id of the backup snapshot

1067

</pre></div>

1068

<p>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.</p>

1069

1070

1071

<pre> $ managix restore -n my_asterix -b 0

1072

INFO: AsterixDB instance: my_asterix has been restored from backup

1073

</pre></div>

1074

<p>You can start the AsterixDB instance by using the start command.</p></div>

1075

1076

<h5>Log Command<a name="Log_Command"></a></h5>

1077

<p>The <tt>log</tt> 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. </p>

1078

1079

1080

<pre> $ managix help -cmd log

1081

1082

Creates a zip archive containing log files corresponding to each worker node (NC) and the master (CC) for an AsterixDB instance

1083

1084

Available arguments/options

1085

-n name of the AsterixDB instance.

1086

-d destination directory for producing the zip archive. Defaults to $MANAGIX_HOME/logdump.

1087

</pre></div>

1088

<p>The following is an example showing the use of the log command. </p>

1089

1090

1091

<pre> $ managix log -n my_asterix -d /Users/joe/logdump

1092

INFO: Log zip archive created at /Users/joe/logdump/log_Thu_Jun_06_00:53:51_PDT_2013.zip

1093

</pre></div></div>

1094

1095

<h5>Delete Command<a name="Delete_Command"></a></h5>

1096

<p>As the name suggests, the <tt>delete</tt> command permanently removes an AsterixDB instance by cleaning up all associated data/artifacts. The usage can be looked up by executing the following:</p>

1097

1098

1099

<pre> $ managix help -cmd delete

1100

Permanently deletes an AsterixDB instance. The instance must be in the INACTIVE state.

1101

1102

Available arguments/options

1103

-n name of the AsterixDB instance.

1104

1105

1106

$ managix delete -n my_asterix

1107

INFO: AsterixDB instance my_asterix deleted.

1108

</pre></div></div>

1109

1110

<h5>Shutdown Command<a name="Shutdown_Command"></a></h5>

1111

<p>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 <tt>shutdown</tt> command.</p>

1112

1113

1114

<pre> $ managix shutdown

1115

</pre></div></div>

1116

1117

<h5>Help Command<a name="Help_Command"></a></h5>

1118

<p>The <tt>help</tt> command provides a usage description of a Managix command.</p>

1119

1120

1121

<pre> $ managix help -cmd <command name>

1122

</pre></div>

1123

<p>As an example, for looking up the help for the <tt>configure</tt> command, execute the following</p>

1124

1125

1126

<pre> $ managix help -cmd configure

1127

1128

Auto-generates the AsterixDB installer configruation settings and AsterixDB cluster

1129

configuration settings for a single node setup.

1130

</pre></div></div></div></div></div>

1131

1132

<h2><a name="Section5FAQ" id="Section5FAQ">Section 5: Frequently Asked Questions</a> <font size="4"><a href="#toc">[Back to TOC]</a></font><a name="Section_5:_Frequently_Asked_Questions_Back_to_TOC"></a></h2>

<h5>Question<a name="Question"></a></h5>

1137

<p>What happens if a machine acting as a node in the Asterix cluster becomes unreachable for some reason (network partition/machine failure) ?</p></div>

1138

1139

<h5>Answer<a name="Answer"></a></h5>

1140

<p>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. </p>

1141

1142

1143

<pre> $ $MANAGIX_HOME/bin/managix describe -n <name of the AsterixDB instance>-admin

1144

</pre></div>

1145

<p>Above command will show the state of AsterixDB instance and list the set of nodes that have left the cluster. </p>

1146

<p>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. </p>

1147

<p>1) Get rid of the Asterix processes running on the nodes in the cluster:-</p>

1148

1149

1150

<pre> managix stop -n my_asterix

1151

</pre></div>

1152

<p>The processes associated with the instance are terminated and the instance moves to the INACTIVE state.</p>

1153

<p>2) Start the AsterixDB instance using the start command.</p>

1154

1155

1156

<pre> managix start -n <name of your AsterixDB instance>

1157

</pre></div></div>

1158

1159

<h5>Question<a name="Question"></a></h5>

1160

<p>Do I need to create all the directories/paths I put into the cluster configuration XML ?</p></div>

1161

1162

<h5>Answer<a name="Answer"></a></h5>

1163

<p>Managix will create a path if it is not existing. It does so using the user account mentioned in the cluster configuration xml. Please ensure that the user account has appropriate permissions for creating the missing paths. </p></div>

1164

1165

<h5>Question<a name="Question"></a></h5>

1166

<p>Should MANAGIX_HOME be on the network file system (NFS) ?</p></div>

1167

1168

<h5>Answer<a name="Answer"></a></h5>

1169

<p>It is recommended that MANAGIX_HOME is not on the NFS. Managix produces artifacts/logs on disk which are not required to be shared. As such an overhead in creating the artifacts/logs on the NFS should be avoided.</p></div>

1170

1171

<h5>Question<a name="Question"></a></h5>

1172

<p>How do we change the underlying code (apply a code patch) for an ‘active’ asterix instance?</p></div>

1173

1174

<h5>Answer<a name="Answer"></a></h5>

1175

<p>At times, end-user (particularly asterix developer) may run into the need to altering the underlying code that is being run by an asterix instance. In the current version of managix, this can be achieved as follows:-</p>

1176

<p>Assume that you have an ‘active’ instance by the name a1 that is running version v1 of asterix. You have a revised version of asterix - v2 that fixes some bug(s).</p>

1177

<p>To upgrade asterix from v1 to v2:-</p>

1178

<p>step 1) managix stop -n a1</p>

1179

<p>step 2) managix shutdown</p>

1180

<p>step 3) copy asterix-server zip (version v2) to asterix/</p>

1181

<p>step 4) managix start -n a1</p>

1182

<p>a1 now is running on version v2.</p>

1183

<p>Limitations:-</p>

1184

<p>a) Obviously this wont work in a situation where v2 has made a change that is incompatible with earlier version, such altering schema.</p>

1185

<p>b) A change in asterix zip applies to all existing instances (after a restart) and subsequent instances that user creates.</p></div></div></div></div>

</div>

</div>

</div>

<hr/>