To create a column family, you also use the CLI or the API. Here are the options available when creating a column family:

Here’s an example:

[default@Keyspace1] create column family MyRadCF with 
column_type='Standard' and comparator='UTF8Type' and rows_cached=40000
3ae948aa-ae14-11df-a254-e700f669bcfc

The cassandra.yaml file in the conf directory appears to be the replacement for storage-conf.xml, the configuration file from version 0.6 and earlier. But this YAML file is intended only for users upgrading their config files from XML to YAML. Instead, use the Thrift API calls prefixed with system_ to configure your keyspaces and column families, as shown previously.

If you do have an existing storage-conf.xml file from using version 0.6, you will first need to convert it to YAML using the bin/config-converter tool, which can generate a cassandra.yaml file from a storage-conf.xml. There is an operation exposed through JMX in the org.apache.cassandra.service.StorageServiceMBean called loadSchemaFromYAML, which you can invoke to force Cassandra to load your schema changes from the cassandra.yaml file in your seed node. New nodes in your cluster will get schema updates as they are started. The seed node is not special here. You can run this method against any one node (though running it against more than one node is not recommended), and all nodes will receive the schema changes and gossip about changes to the schema. This is a one-time operation that stores the definition in Cassandra’s system keyspace, and you don’t want to modify the YAML file after running this. For any subsequent changes, you’ll need to use the API or CLI. This operation will be deprecated once the transition is complete.

Although it’s simple enough for testing to just use the defaults, let’s examine how to configure the replica placement strategy, replication factor, and end point snitch. These settings are configurable within a keyspace, so that different keyspaces can have different settings for each.

Simple Strategy is the new name for Rack-Unaware Strategy.

The strategy used by default in the configuration file is org.apache.cassandra.locator.RackUnawareStrategy. This strategy only overrides the calculateNaturalEndpoints method from the abstract parent implementation. This strategy places replicas in a single data center, in a manner that is not aware of their placement on a data center rack. This means that the implementation is theoretically fast, but not if the next node that has the given key is in a different rack than others. This is shown in Figure 6-1.

Figure 6-1. The Simple Strategy places replicas in a single data center, without respect to topology

What’s happening here is that the next N nodes on the ring are chosen to hold replicas, and the strategy has no notion of data centers. A second data center is shown in the diagram to highlight the fact that the strategy is unaware of it.

The second strategy for replica placement that Cassandra provides out of the box is org.apache.cassandra.locator.RackAwareStrategy, now called Old Network Topology Strategy. It’s mainly used to distribute data across different racks in the same data center. Like RackUnawareStrategy, this strategy only overrides the calculateNaturalEndpoints method from the abstract parent implementation. This class, as the original name suggests, is indeed aware of the placement in data center racks.

Say you have two data centers, DC1 and DC2, and a set of Cassandra servers. This strategy will place some replicas in DC1, putting each in a different available rack. It will also ensure that another replica is placed in DC2. The Rack-Aware Strategy is specifically for when you have nodes in the same Cassandra cluster spread over two data centers and you are using a replication factor of 3. This strategy is depicted in Figure 6-2.

Use this strategy when you want to ensure higher availability at the potential cost of some additional latency while the third node in the alternate data center is contacted. There is no point in using Rack-Aware Strategy if you are only running Cassandra in a single data center. Cassandra is optimized for running in different data centers, however, and taking advantage of its high availability may be an important consideration for you. If your Cassandra cluster does span multiple data centers, consider using this strategy.

Figure 6-2. The Old Network Topology Strategy places the second replica in a different data center and others on different racks in the same data center

If you use the Rack-Aware Strategy, you must also use the Rack-Aware Snitch. Snitches are described in Snitches.

This strategy, included with the 0.7 release of Cassandra, allows you to specify more evenly than the RackAwareStrategy how replicas should be placed across data centers. To use it, you supply parameters in which you indicate the desired replication strategy for each data center. This file is read and executed by the org.apache.cassandra.locator.DataCenterShardStrategy class, so the implementation is somewhat flexible. The data center shard strategy is depicted in Figure 6-3.

This strategy used to employ a file called datacenter.properties. But as of 0.7, this metadata is attached directly to the keyspace and strategy as a map of configuration options.

Figure 6-3. The Network Topology Strategy places some replicas in another data center and the remainder in other racks in the first data center, as specified

The replication factor is not a setting that is intended to be changed on a live cluster and should be determined ahead of time. But as your application grows and you need to add nodes, you can increase the replication factor. There are some simple guidelines to follow when you do this. First, keep in mind that you’ll have to restart the nodes after a simple increase in the replication factor value. A repair will then be performed after you restart the nodes, as Cassandra will have to redistribute some data in order to account for the increased replication factor. For as long as the repair takes, it is possible that some clients will receive a notice that data does not exist if they connect to a replica that doesn’t have the data yet.

A faster way of increasing the replication factor from 1 to 2 is to use the node tool. First, execute a drain on the original node to ensure that all the data is flushed to the SSTables. Then, stop that node so it doesn’t accept any more writes. Next, copy the datafiles from your keyspaces (the files under the directory that is your value for the DataFileDirectory element in the config). Make sure not to copy the values in the internal Cassandra keyspace. Paste those datafiles to the new node. Change the settings in the configuration of both nodes so that the replication factor is set to 2. Make sure that autobootstrap is set to false in both nodes. Then, restart both nodes and run node tool repair. These steps will ensure that clients will not have to endure the potential of false empty reads for as long.

To illustrate this, I have three nodes with IP addresses ending in 1.5, 1.7, and 1.8, and their replication factor is set to 1. I will connect to node 1.5 and perform a write to a column that hasn’t previously existed anywhere:

cassandra> connect 192.168.1.5/9160                  
Connected to: "TDG Cluster" on 192.168.1.5/9160
cassandra> set Keyspace1.Standard2['mykey']['rf']='1'       
Value inserted.

Now I shut down node 1.5 and connect to the other node, 1.7, and try to get the value I just set:

cassandra> connect 192.168.1.7/9160              
Connected to: "TDG Cluster" on 192.168.1.7/9160
cassandra> get Keyspace1.Standard2['mykey']['rf']
Exception null

Because my replication factor was 1, the value was written only to the 1.5 node, so when I lost that node, the other node in the cluster didn’t have the value. No client will be able to read the value of the rf column until 1.5 comes back online.

But let’s see the effect of updating the replication factor. We change it from 1 to 2 in the 1.5 and 1.7 nodes and restart. Let’s insert a new value to our rf column on node 1.7:

cassandra> connect 192.168.1.7/9160              
Connected to: "TDG Cluster" on 192.168.1.7/9160
cassandra> get Keyspace1.Standard2['mykey']['rf']    
Exception null
cassandra> set Keyspace1.Standard2['mykey']['rf']='2'
Value inserted.

The Exception null response in the preceding example proves that the value didn’t exist on node 1.7 beforehand. Now we shut down node 1.7 and connect to 1.5, and we see the value because it was replicated to 1.5 on our write to 1.7, due to our replication factor:

cassandra> connect 192.168.1.5/9160              
Connected to: "TDG Cluster" on 192.168.1.5/9160
cassandra> get Keyspace1.Standard2['mykey']['rf']
=> (column=rf, value=2, timestamp=1279491483449000)

As a general guideline, you can anticipate that your write throughput capacity will be the number of nodes divided by your replication factor. So in a 10-node cluster that typically does 10,000 writes per second with a replication factor of 1, if you increase the replication factor to 2, you can expect to do around 5,000 writes per second.

The random partitioner is implemented by org.apache.cassandra.dht.RandomPartitioner and is Cassandra’s default. It uses a BigIntegerToken with an MD5 hash applied to it to determine where to place the keys on the node ring. This has the advantage of spreading your keys evenly across your cluster, because the distribution is random. It has the disadvantage of causing inefficient range queries, because keys within a specified range might be placed in a variety of disparate locations in the ring, and key range queries will return data in an essentially random order.

The order-preserving partitioner is implemented by org.apache.cassandra.dht.OrderPreservingPartitioner, which implements IPartitioner<StringToken>. Using this type of partitioner, the token is a UTF-8 string, based on a key. Rows are therefore stored by key order, aligning the physical structure of the data with your sort order. Configuring your column family to use order-preserving partitioning (OPP) allows you to perform range slices.

It’s worth noting that OPP isn’t more efficient for range queries than random partitioning—it just provides ordering. It has the disadvantage of creating a ring that is potentially very lopsided, because real-world data typically is not written to evenly. As an example, consider the value assigned to letters in a Scrabble game. Q and Z are rarely used, so they get a high value. With OPP, you’ll likely eventually end up with lots of data on some nodes and much less data on other nodes. The nodes on which lots of data is stored, making the ring lopsided, are often referred to as “hot spots.” Because of the ordering aspect, users are commonly attracted to OPP early on. However, using OPP means that your operations team will need to manually rebalance nodes periodically using Nodetool’s loadbalance or move operations.

If you want to perform range queries from your clients, you must use an order-preserving partitioner or a collating order-preserving partitioner.

This partitioner orders keys according to a United States English locale (EN_US). Like OPP, it requires that the keys are UTF-8 strings. Although its name might imply that it extends the OPP, it doesn’t. Instead, this class extends AbstractByteOrderedPartitioner. This partitioner is rarely employed, as its usefulness is limited.

New for 0.7, the team added ByteOrderedPartitioner, which is an order-preserving partitioner that treats the data as raw bytes, instead of converting them to strings the way the order-preserving partitioner and collating order-preserving partitioner do. If you need an order-preserving partitioner that doesn’t validate your keys as being strings, BOP is recommended for the performance improvement.

By default, Cassandra uses org.apache.cassandra.locator.EndPointSnitch. It operates by simply comparing different octets in the IP addresses of each node. If two hosts have the same value in the second octet of their IP addresses, then they are determined to be in the same data center. If two hosts have the same value in the third octet of their IP addresses, then they are determined to be in the same rack. “Determined to be” really means that Cassandra has to guess based on an assumption of how your servers are located in different VLANs or subnets.

You configure which endpoint snitch implementation to use by updating the value for the <EndPointSnitch> element in the configuration file. The other choice is the PropertyFileSnitch.

The org.apache.cassandra.locator.PropertyFileSnitch used to be in contrib, but was moved into the main code base in 0.7. This snitch allows you more control when using a Rack-Aware Strategy by specifying node locations in a standard key/value properties file called cassandra-rack.properties.

This snitch was contributed by Digg, which uses Cassandra and regularly contributes to its development. This snitch helps Cassandra know for certain if two IPs are in the same data center or on the same rack—because you tell it that they are. This is perhaps most useful if you move servers a lot, as operations often need to, or if you have inherited an unwieldy IP scheme.

The default configuration of cassandra-rack.properties looks like this:

# Cassandra Node IP=Data Center:Rack
10.0.0.10=DC1:RAC1
10.0.0.11=DC1:RAC1
10.0.0.12=DC1:RAC2

10.20.114.10=DC2:RAC1
10.20.114.11=DC2:RAC1
10.20.114.15=DC2:RAC2

# default for unknown nodes
default=DC1:r1

Here we see that there are two data centers, each with two racks. Cassandra can determine an even distribution with good performance.

Update the values in this file to record each node in your cluster to specify which rack contains the node with that IP and which data center it’s in. Although this may seem difficult to maintain if you expect to add or remove nodes with some frequency, remember that it’s one alternative, and it trades away a little flexibility and ease of maintenance in order to give you more control and better runtime performance, as Cassandra doesn’t have to figure out where nodes are. Instead, you just tell it where they are.

Cassandra clusters are given names in order to prevent machines in one cluster from joining another that you don’t want them to be a part of. The name of the default cluster in the config file is “Test Cluster”. You can change the name of the cluster by updating the <ClusterName> element—just make sure that you have done this on all nodes that you want to participate in this cluster.

The configuration file has an element that is set to false by default. Say that you have been running a cluster or a single node and added data to it, and now you want to introduce more nodes to the cluster. You can do this using the autobootstrap element. I have a single Cassandra server running on an IP ending in 1.5, as shown by NodeTool:

$ bin/nodetool -h 192.168.1.5 ring
Address       Status     Load        Range                                    Ring
192.168.1.5   Up         433.43 MB   126804671661649450065809810549633334036  |<--|

This server has its own address as a seed. We leave autobootstrap set to false, because this node is acting as a seed. If you want to add a new seed node, then you should autobootstrap it first, and then change it to a seed afterward. For node B to use node A as a seed, node B needs to reference node A as its seed in its configuration file. But node A does not have to declare itself as a seed.

Now I’d like to add another node to share the load. This node’s address ends in 1.7. First, make sure that the nodes in the cluster all have the same name and the same keyspace definitions so that the new node can accept data. Edit the config file on the second node to indicate that the first one will act as the seed. Then, set autobootstrap to true.

When the second node is started up, it immediately recognizes the first node, but then sleeps for 90 seconds to allow time for nodes to gossip information about how much data they are storing locally. It then gets the bootstrap token from the first node, so it knows what section of the data it should accept. The bootstrap token is a token that splits the load of the most-loaded node in half. Again, the second node sleeps for 30 seconds and then starts bootstrapping.

 INFO 11:45:43,652 Starting up server gossip
 INFO 11:45:43,886 Joining: getting load information
 INFO 11:45:43,901 Sleeping 90000 ms to wait for load information...
 INFO 11:45:45,742 Node /192.168.1.5 is now part of the cluster
 INFO 11:45:46,818 InetAddress /192.168.1.5 is now UP
 INFO 11:45:46,818 Started hinted handoff for endPoint /192.168.1.5
 INFO 11:45:46,865 Finished hinted handoff of 0 rows to endpoint /192.168.1.5
 INFO 11:47:13,913 Joining: getting bootstrap token
 INFO 11:47:16,004 New token will be 41707658470746813056713124104091156313 to a
ssume load from /192.168.1.5
 INFO 11:47:16,019 Joining: sleeping 30000 ms for pending range setup
 INFO 11:47:46,034 Bootstrapping

Depending on how much data you have, you could see your new node in this state for some time. You can use Nodetool’s streams command to watch the data being transferred for bootstrap. Watching the logfile is a good way to determine that the node is finished bootstrapping, but to watch for progress while it’s happening, use nodetool streams. Eventually, the new node will accept the load from the first node, and you’ll see a successful indication that the new node has started up:

 INFO 11:52:29,361 Sampling index for /var/lib/cassandra/dataKeyspace1Standard
1-1-Data.db
 INFO 11:52:34,073 Streaming added /var/lib/cassandra/dataKeyspace1Standard1-1
-Data.db
 INFO 11:52:34,088 Bootstrap/move completed! Now serving reads.
 INFO 11:52:34,354 Binding thrift service to /192.168.1.7:9160
 INFO 11:52:34,432 Cassandra starting up...

As you can see, it took around four minutes to transfer data.

During bootstrapping, the first (seed) node at 1.5 looks like this:

 INFO 11:48:12,955 Sending a stream initiate message to /192.168.1.7 ...
 INFO 11:48:12,955 Waiting for transfer to /192.168.1.7 to complete
 INFO 11:52:28,903 Done with transfer to /192.168.1.7

Now we can run node tool again to make sure that everything is set up properly:

$ bin/nodetool -h 192.168.1.5 ring
Address       Status     Load        Range                                    Ring
                                     126804671661649450065809810549633334036  
192.168.1.7   Up         229.56 MB   41707658470746813056713124104091156313   |<--|
192.168.1.5   Up         459.26 MB   126804671661649450065809810549633334036  |-->|

Cassandra has automatically bootstrapped the 1.7 node by sending it half of the data from the previous node (1.5). So now we have a two-node cluster. To ensure that it works, let’s add a value to the 1.5 node:

cassandra> connect 192.168.1.5/9160
Connected to: "TDG Cluster" on 192.168.1.5/9160
cassandra> set Keyspace1.Standard2['mykey']['col0']='value0'
Value inserted.

Now let’s open a second CLI client and read that value from the 1.7 node:

cassandra> connect 192.168.1.7/9160
Connected to: "TDG Cluster" on 192.168.1.7/9160
cassandra> get Keyspace1.Standard2['mykey']['col0']
=> (column=col0, value=value0, timestamp=1278878907805000

You can repeat these steps to add additional nodes to your cluster.

If there’s something wrong with one of the nodes in your cluster (perhaps it’s offline, but Cassandra is not sure), you may see a question mark when you run node tool:

$ bin/nodetool -h 192.168.1.5 ring
Address       Status     Load        Range                                      Ring
                                     112711146095673746066359353163476425700  
192.168.1.5   Up         459.26 MB   27647275353297313886547808446514704912     |<--|
192.168.1.7   ?          229.53 MB   112711146095673746066359353163476425700    |-->|

Cassandra allows you to specify multiple seed nodes. A seed node is used as a contact point for other nodes, so Cassandra can learn the topology of the cluster, that is, what hosts have what ranges.

By default, the configuration file will have only a single seed entry:

seeds:
    - 127.0.0.1

To add more seed nodes to your ring, just add another seed element. We can set two servers to be seeds just by indicating the IP address or hostname of this node and then adding our second instance:

seeds:
    - 192.168.1.5
    - 192.168.1.7

Next, we need to update the listen address for this machine so it’s not just on loopback. Listen address is how nodes identify each other, and it’s used for all internal communication.

listen_address: 192.168.1.5

Finally, we need to change the address on which our RPC client will broadcast because this is how other nodes will see this one. By default, the configuration file will have an rpc_address entry that uses localhost. We’ll change this value to the actual IP address of each machine:

rpc_address: 192.168.1.5

The rpc_address setting is used only for connections made directly from clients to Cassandra nodes.

Now you can restart Cassandra and start the installations on the other machines. If you have successfully added multiple nodes to your cluster, you will see output similar to this (yours might be a little less verbose, as I’m showing debug-level output here):

 INFO 15:45:15,629 Starting up server gossip
 INFO 15:45:15,677 Binding thrift service to /192.168.1.5:9160
 INFO 15:45:15,681 Cassandra starting up...
DEBUG 15:45:16,636 GC for ParNew: 13 ms, 12879912 reclaimed leaving 11233080 used; 
max is 1177812992
DEBUG 15:45:16,647 attempting to connect to /192.168.1.7
DEBUG 15:45:17,638 Disseminating load info ...
 INFO 15:45:19,744 Node /192.168.1.7 is now part of the cluster
DEBUG 15:45:19,746 Node /192.168.1.7 state normal, token 
41654880048427970483049687892424207188
DEBUG 15:45:19,746 No bootstrapping or leaving nodes -> empty pending ranges 
for Keyspace1
 INFO 15:45:20,789 InetAddress /192.168.1.7 is now UP
DEBUG 15:45:20,789 Started hinted handoff for endPoint /192.168.1.7
DEBUG 15:45:20,800 Finished hinted handoff for endpoint /192.168.1.7
DEBUG 15:46:17,638 Disseminating load info ...

This output shows that I have two nodes in my cluster: the node I just started, which is listening on 192.168.1.5, and the node that was already up and running, which is listening on 192.168.1.7.

There are two files included in the config directory: access.properties and passwd.properties. The access file uses a key/value pair to specify which users are allowed access to which keyspaces, specified by a comma-separated list. The example provided looks like this:

Keyspace1=jsmith,Elvis Presley,dilbert

This indicates that there are three users allowed to access Keyspace1, and spaces are allowed in the usernames.

The file passwd.properties must contain a list of these users and specify the password for each of them. Here is the example passwd.properties file:

jsmith=havebadpass
Elvis Presley=graceland4evar
dilbert=nomoovertime

Note that because the user Elvis Presley has a space in his username, a backslash must be used to escape the space.

To use the Simple Authenticator, replace the value for the authenticator element in cassandra.yaml. Change it from org.apache.cassandra.auth.AllowAllAuthenticator to the name of the implementing class that requires a login: org.apache.cassandra.auth.SimpleAuthenticator.

If you haven’t configured the authentication files properly, you’ll see an error like this:

ERROR 10:44:27,928 Fatal error: When using org.apache.cassandra.auth.SimpleAuth
enticator
access.properties and passwd.properties properties must be defined.

That’s because there is one more step: we have to tell Cassandra the location of the access and passwords files, using the bin/cassandra.in.sh include script. We pass the file locations to the JVM by pasting the following code at the bottom of this file. My include file now looks like the snippet here, indicating the full path to the files:

JVM_OPTS="
        -Dpasswd.properties=/home/eben/books/cassandra/dist/
apache-cassandra-0.7.0-beta1/
conf/passwd.properties
        -Daccess.properties=/home/eben/books/cassandra/dist/
apache-cassandra-0.7.0-beta1/
conf/access.properties" 

If you have specified an incorrect location or name for either of these files, the server log will let you know:

ERROR 11:13:55,755 Internal error processing login
java.lang.RuntimeException: Authentication table file given by property 
passwd.properties 
could not be found: /somebadpath/my.properties (No such file or directory)

Now we can log into the command-line interface with a username and password combination:

[default@unknown] connect localhost/9160
Connected to: "Test Cluster" on localhost/9160
[default@unknown] use Keyspace1 jsmith 'havebadpass'
Authenticated to keyspace: Keyspace1
[jsmith@Keyspace1] 

If you enter an incorrect password, the CLI tells you:

[default@unknown] use Keyspace1 jsmith 'havebadpassfdfdfd'
Exception during authentication to the cassandra node: verify keyspace exists, 
and you are using correct credentials.

If you enter a username that doesn’t exist or try to authenticate to a keyspace that the user doesn’t have access to, you’ll see something like this:

[default@unknown] use Keyspace1 dude 'dude'
Login failure. Did you specify 'keyspace', 'username' and 'password'?
[default@unknown] 

Somewhat confusingly, if you just try to use a keyspace that you don’t have access to, you’ll see an authentication message, but then you won’t be able to perform operations. In the following example, we switch to a keyspace that requires authentication. The CLI appears to let us do that, but then we can’t read a column:

[default@Keyspace1] get Standard1['user123']['name']
Your credentials are not sufficient to perform READONLY operations
[default@Keyspace1]

Assuming we have set the 'name' value for this user, if we supply the proper credentials, we can perform the operation:

[default@Keyspace1] use Keyspace1 eben 'pass'
Authenticated to keyspace: Keyspace1
[eben@Keyspace1] get Standard1['user123']['name']
=> (column=6e616d65, value=bootsy, timestamp=1284316537496000)
[eben@Keyspace1] 

We can also specify the username and password combination when we connect on the CLI:

eben@morpheus:~/books/cassandra/dist/apache-cassandra-0.7.0-beta1$ 
  bin/cassandra-cli --host localhost --port 9160 
  --username jsmith --password havebadpass --keyspace Keyspace1

Connected to: "Test Cluster" on localhost/9160
Welcome to cassandra CLI.

Type 'help' or '?' for help. Type 'quit' or 'exit' to quit.
[jsmith@Keyspace1] get Standard1['user123']['name']
=> (column=6e616d65, value=bootsy, timestamp=1284316537496000)
[jsmith@Keyspace1] 

Executing a query now returns us a result.

If you have set up authentication on your keyspace, your client application code will need to log in. You can use Example 6-2 as a guide.

package com.cassandraguide.config;

import java.util.HashMap;
import java.util.Map;

import org.apache.cassandra.thrift.AccessLevel;
import org.apache.cassandra.thrift.AuthenticationRequest;
import org.apache.cassandra.thrift.Cassandra;
import org.apache.thrift.protocol.TBinaryProtocol;
import org.apache.thrift.protocol.TProtocol;
import org.apache.thrift.transport.TFramedTransport;
import org.apache.thrift.transport.TSocket;
import org.apache.thrift.transport.TTransport;

/**
 * How to connect if you've set up SimpleAuthenticator
 */
public class AuthExample {

	public static void main(String[] args) throws Exception {
		
		TTransport tr = new TSocket("localhost", 9160);
		TFramedTransport tf = new TFramedTransport(tr);
		TProtocol proto = new TBinaryProtocol(tf);
		Cassandra.Client client = new Cassandra.Client(proto);
		tr.open();
		
		AuthenticationRequest authRequest = new AuthenticationRequest();
		Map<String, String> credentials = new HashMap<String, String>();
		credentials.put("username", "jsmith");
		credentials.put("password", "havebadpass");
		authRequest.setCredentials(credentials);
		
		client.set_keyspace("Keyspace1");
		
		AccessLevel access = client.login(authRequest);
		System.out.println("ACCESS LEVEL: " + access);
		tr.close();
	}
}

In this case, the program just prints out FULL because that’s this user’s access level.

There are a couple of things to note here. First, the credentials map uses username and password as keys; it’s not username as the key and password as the value. Second, you need to call set_keyspace separately, to indicate what keyspace you’re trying to authenticate to.

The SimpleAuthenticator class has two modes for specifying passwords: plain text and MD5 encrypted. So far, we’ve used the default, plain text. Let’s look at how to improve security a bit by using MD5. MD5 is a cryptographical algorithm that stands for “Message-Digest algorithm version 5” (the “5” indicates an improvement in strength over version 4). It’s a widely used one-way hash function that generates a 128-bit hash value from an input. It’s also worth noting that MD5 is not going to be radically secure for you; it’s just a little harder to break in.

You enable MD5 in the cassandra.in.sh file by passing the passwd.mode switch to the JVM:

JVM_OPTS=" 
        -da 
//other stuff...
        -Dpasswd.mode=MD5"

Now if you try to authenticate using an unencrypted password, you’ll see an error like this:

Exception during authentication to the cassandra node, verify you are using correct 
credentials.

You can use a variety of tools to generate an MD5-encrypted version of the plain-text username and password as a one-way hash. Here’s a short Python program to create an MD5 hash from a plain string:

$ python
Python 2.6.5 ...
>>> from hashlib import md5
>>> p = "havebadpass"
>>> h = md5(p).hexdigest()
>>> print h
e1a31eee2136eb73e8e47f9e9d13ab0d

Now you can replace the password for jsmith in the passwd.properties file with the encrypted value.

You can provide your own method of authenticating to Cassandra if you want to make special requirements, such as a Kerberos ticket or encryption, or if you want to store passwords in a different location, such as an LDAP directory. To create your own authentication scheme, simply implement the IAuthenticator interface. This interface requires two methods, as shown here:

public AccessLevel login(String keyspace, AuthenticationRequest authRequest) 
    throws AuthenticationException, AuthorizationException;
    
public void validateConfiguration() throws ConfigurationException;

The login method must return a Thrift AccessLevel instance, indicating what degree of access the authenticating user is allowed. The validateConfiguration method simply allows a check to ensure that the authentication mechanism is properly set up. For example, with the SimpleAuthenticator, it just checks that the required access and passwd files have been specified.

You can see which keys are in your SSTables using a script called sstablekeys. To run it, just use the location of the SSTable for which you want to see keys, as shown here:

eben@morpheus$ bin/sstablekeys /var/lib/cassandra/data/Hotelier/Hotel-1-Data.db
 WARN 10:56:05,928 Schema definitions were defined both locally and in cassandra.yaml. 
Definitions in cassandra.yaml were ignored.
415a435f303433
415a535f303131
4341535f303231
4e594e5f303432

If you had a keyspace defined in 0.6 using the configuration file that you’d like to import into Cassandra 0.7 or higher, you can use a special JMX operation, StorageService.loadSchemaFromYaml(). Note that this method has two important caveats: first, it is intended to be used only once; second, it will probably be removed by version 0.8.

Starting with version 0.7, the user keyspaces defined in cassandra.yaml are not loaded by default when the server starts. So you might see a message like this as your Cassandra server starts up for the first time:

INFO config.DatabaseDescriptor: Found table data in data directories. 
Consider using JMX to call org.apache.cassandra.service.StorageService.
loadSchemaFromYaml().

In order to load them, you need to invoke the loadSchemaFromYaml JMX operation. But in order to invoke this command, you need to do a couple of things. First, get mx4j-tools.jar from Sourceforge.net. Download and extract the ZIP file into any directory. Then, copy the JAR named mx4j-tools.jar in its lib directory into Cassandra’s lib directory. This will allow you to make JMX connections to interact with Cassandra in really rich ways. We’ll see more about using JMX with Cassandra later, but for now we just want to get a keyspace up for testing. Restart Cassandra after adding the JAR.

Next, open a new terminal and issue the command jconsole. A GUI will start and load the JConsole tool that ships with Java. This tool can introspect the Java Virtual Machine and allow you to view runtime data and invoke operations that are exposed via JMX.

To load the keyspaces defined in cassandra.yaml, click the MBeans tab in the JConsole GUI. Expand the org.apache.cassandra.service bean, then StorageService, then Operations. Click the loadSchemaFromYAML operation and click the button. This will execute the command on the Cassandra service and load your schemas in the cassandra.yaml file.

To perform the once-only operation to import a 0.6 configuration into 0.7, use the loadSchemaFromYaml operation on the StorageService MBean. This is shown in Figure 6-4.

Figure 6-4. Using the jconsole tool to load old keyspaces defined in cassandra.yaml

Now you should see output similar to the following in your logs:

17:35:47 INFO thrift.CassandraDaemon: Cassandra starting up...
17:35:48 INFO utils.Mx4jTool: mx4j successfuly loaded
HttpAdaptor version 3.0.2 started on port 8081
17:40:43 INFO config.DatabaseDescriptor: UTF8Type
17:40:43 INFO config.DatabaseDescriptor: BytesType
17:40:43 INFO config.DatabaseDescriptor: UTF8Type
17:40:43 INFO config.DatabaseDescriptor: TimeUUIDType
17:40:43 INFO config.DatabaseDescriptor: BytesType
17:40:43 INFO config.DatabaseDescriptor: BytesType
17:40:43 INFO config.DatabaseDescriptor:

The database descriptor logs are a good thing, as this indicates that the operation loaded your schemas.

You can also use the org.apache.cassandra.config.Converter class to assist you in converting from storage-conf.xml to a cassandra.yaml file. If you are upgrading from 0.6 to 0.7, this should be your first step. To run the converter, use the config-converter script in the bin directory. It will read in the old file, convert it, and dump the contents.