installation & operation

Quick Start

Install

You need a 64-bit Linux machine to install Citrusleaf. Obtain the rpm packages from the download site corresponding to the version of Linux you are running. First, add a new user with id citrusleaf:

$ sudo /usr/sbin/useradd citrusleaf

Once the user is created, untar the downloaded tgz file and attach to the directory created:

$ # Replace the strings 2.0.23.24 and el5 with the actual version of the packages downloaded
$ tar -xzf citrusleaf-2.0.23.24-el5.tgz
$ cd citrusleaf-2.0.23.24-el5/

Now follow the simple installation instructions provided below for the distribution of Linux you are using:

Centos 5

Execute the following commands to install the Citrusleaf server and tools. Note that the Citrusleaf tools depend on the python-ctypes package.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo rpm -i python-ctypes-1.0.2-2.el5.x86_64.rpm
$ sudo rpm -i libcitrusleaf-python-2.0.23.24-1.el5.x86_64.rpm
$ sudo rpm -i citrusleaf-tools-2.0.23.24-1.el5.x86_64.rpm
$ sudo rpm -i citrusleaf-trial-server-2.0.23.24-1.el5.x86_64.rpm

Proceed to the next section, Start Server.

Fedora 8

Execute the following commands to install the Citrusleaf server and tools.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo rpm -i libcitrusleaf-python-2.0.23.24-1.Fedora8.x86_64.rpm
$ sudo rpm -i citrusleaf-tools-2.0.23.24-1.Fedora8.x86_64.rpm
$ sudo rpm -i citrusleaf-trial-server-2.0.23.24-1.Fedora8.x86_64.rpm

Proceed to the next section, Start Server.

Fedora 9

Execute the following commands to install the Citrusleaf server and tools.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo rpm -i libcitrusleaf-python-2.0.23.24-1.fc9.x86_64.rpm
$ sudo rpm -i citrusleaf-tools-2.0.23.24-1.fc9.x86_64.rpm
$ sudo rpm -i citrusleaf-trial-server-2.0.23.24-1.fc9.x86_64.rpm

Proceed to the next section, Start Server.

Fedora 12

Execute the following commands to install the Citrusleaf server and tools.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo rpm -i libcitrusleaf-python-2.0.23.24-1.fc12.x86_64.rpm
$ sudo rpm -i citrusleaf-tools-2.0.23.24-1.fc12.x86_64.rpm
$ sudo rpm -i citrusleaf-trial-server-2.0.23.24-1.fc12.x86_64.rpm

Proceed to the next section, Start Server.

Fedora 13

Execute the following commands to install the Citrusleaf server and tools.

$ # Replace the string 2.0.23.25 with the actual version of the packages downloaded
$ sudo rpm -i libcitrusleaf-python-2.0.23.25-1.Fedora13.x86_64.rpm
$ sudo rpm -i citrusleaf-tools-2.0.23.25-1.Fedora13.x86_64.rpm
$ sudo rpm -i citrusleaf-trial-server-2.0.23.25-1.Fedora13.x86_64.rpm

Proceed to the next section, Start Server.

Ubuntu 9.04

Execute the following commands to install the Citrusleaf server and tools. There is no separate tools package for Ubuntu.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo dpkg -i citrusleaf-trial-server-2.0.23.24-1-x86_64.deb

Proceed to the next section, Start Server.

Ubuntu 10.04

Execute the following commands to install the Citrusleaf server and tools. There is no separate tools package for Ubuntu.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo dpkg -i citrusleaf-trial-server-2.0.23.24-1.ubuntu10.04.1.x86_64.deb

Proceed to the next section, Start Server.

Debian 5

Execute the following commands to install the Citrusleaf server and tools. There is no separate tools package for Ubuntu.

$ # Replace the string 2.0.23.24 with the actual version of the packages downloaded
$ sudo dpkg -i citrusleaf-trial-server-2.0.23.24-1.debian.5.0.8.x86_64.deb

Proceed to the next section, Start Server.

Start Server

If you are using the Citrusleaf free trial version, add the trial account key to the 'service' section of the Citrusleaf configuration file, /etc/citrusleaf/citrusleaf.conf. Please refer to your trial grant email for the trial account key and instructions. Customers using the production version can skip this step.

Start the Citrusleaf server as follows:

$ sudo /etc/init.d/citrusleaf start
Starting citrusleaf:                              [  OK  ] 

If you are using the default installation, make sure that user citrusleaf has been created. Otherwise, the server will not start. Once the server has started, you can check the log to see that the service is ready, as follows:

$ sudo grep cake /var/log/citrusleaf.log 
Feb 25 2011 01:36:56: INFO (as): (base/as.c:336) service ready: soon there will be cake!

You can also continuously view the Citrusleaf log as follows:

$ sudo tail -f /var/log/citrusleaf.log 

You can now use the command line interface and test the installation. This is explained in the next section, Verify Installation.

You can shut down the Citrusleaf server as follows:

$ sudo /etc/init.d/citrusleaf stop
Stopping citrusleaf:                                       [  OK  ]

Verify Installation

Let us use the command line interface tool in Python (installed as /usr/bin/cli) to manipulate the data in our Citrusleaf instance. First, let us start by creating a new object with the key "Citrusleaf" in the "test" namespace that is part of the default configuration and adding three fields, "name", "address" and "email":

$ cli -h 127.0.0.1 -n test -o set -k Citrusleaf -b name -v "Citrusleaf, Inc."
succeeded: key= Citrusleaf  set=   bin= name  value= Citrusleaf, Inc.
$ cli -h 127.0.0.1 -n test -o set -k Citrusleaf -b address -v "444 Castro Street, Suite 703, Mountain View, CA 94041"
succeeded: key= Citrusleaf  set=   bin= address  value= 444 Castro Street, Suite 703, Mountain View, CA 94041
$ cli -h 127.0.0.1 -n test -o set -k Citrusleaf -b email -v "info@citrusleaf.net"
succeeded: key= Citrusleaf  set=   bin= email  value= info@citrusleaf.net

Let us retrieve the record back and make sure it looks right:

cli -h 127.0.0.1 -n test -o get -k Citrusleaf
{'email': 'info@citrusleaf.net', 'name': 'Citrusleaf, Inc.', 'address': '444 Castro Street, Suite 703, Mountain View, CA 94041'}

Let us now delete the record and verify that it is deleted:

$ cli -h 127.0.0.1 -n test -o delete -k Citrusleaf
delete succeeded: key= Citrusleaf  set=
$ cli -h 127.0.0.1 -n test -o get -k Citrusleaf
no data retrieved

Setup a Cluster

Now that you have Citrusleaf up and running as a single node cluster, you can add additional nodes to the cluster as follows:

To verify cluster size, you can check the server log (the location of the log is specified in the configuration file). The server will print the cluster size in the log file every few seconds. Here is a sample log line from one of the servers that is part of a 4 node cluster:

Mar 26 2011 19:34:49: INFO (info): (base/thr_info.c:1542)  
        migrates in progress ( 0 , 0 ) ::: ClusterSize 4 ::: objects 341545376

You can add more servers to the cluster by repeatedly following the above procedure. Please visit the Configuration Section to learn more about how to configure a Citrusleaf cluster to suit your needs. Also, please visit the Client APIs Section for example code on supported languages.

Command Line Tool

As seen above, cli takes several command-line arguments. You can get the usage information of the command line tool as follows

$ cli --usage
cli: 
Usage: ascli [OPTIONS]...
Execute a command against an Aerospike cluster.
  -t, --target             a cluster node to query (host:port)
                           default: 127.0.0.1:3000
  -h, --host               host of the cluster node to query
                           default: 127.0.0.1
  -p, --port               port of the cluster node to query
                           default: 3000
  -o, --operand            the operand: get, set, delete
                           default: get
  -n  --namespace          the namespace to operate on
                           default: test
  -s  --set                the set the key belongs in
                           default: ""
  -k, --key                key - must be set, no default
  -b, --bin                bin
                           default: ""
  -v, --value              value
  --verbose                make the request verbose

          for usage, --usage

Note that Citrusleaf is not intended to be used through a command line tool. The inefficiencies of creating a new connection pool for every transaction would be overwhelming. Instead, it is expected that the application will integrate with Citrusleaf's client libraries that are described in the Client APIs Section.