Description

Apache Cassandra is an open source distributed database management system designed to handle large amounts of data across many servers, providing high availability with no single point of failure.

First steps with the Bitnami Cassandra Stack

Welcome to your new Bitnami application running on Microsoft Azure! Here are a few questions (and answers!) you might need when first starting with your application.

What credentials do I need?

You need two sets of credentials:

• The application credentials that allow you to log in to your new Bitnami application. These credentials consist of a username and password.
• The server credentials that allow you to log in to your Microsoft Azure server using an SSH client and execute commands on the server using the command line. These credentials consist of an SSH username and key.

What is the administrator username set for me to log in to the application for the first time?

Username: cassandra

What SSH username should I use for secure shell access to my application?

SSH username: bitnami

How to start or stop the services?

Each Bitnami stack includes a control script that lets you easily stop, start and restart services. The script is located at /opt/bitnami/ctlscript.sh. Call it without any service name arguments to start all services:

$ sudo /opt/bitnami/ctlscript.sh start

Or use it to restart a single service, such as Apache only, by passing the service name as argument:

$ sudo /opt/bitnami/ctlscript.sh restart apache

Use this script to stop all services:

$ sudo /opt/bitnami/ctlscript.sh stop

Restart the services by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh restart

Obtain a list of available services and operations by running the script without any arguments:

$ sudo /opt/bitnami/ctlscript.sh

What is the default configuration?

The Cassandra admin user for all databases is automatically generated. The administrator user name is cassandra and you can get the password from the server dashboard for your server.

You can connect to the Cassandra server locally or remotely using the cqlsh command line tool:

$ cqlsh -u cassandra
Password:
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 2.1.1 | CQL spec 3.2.0 | Native protocol v3]
Use HELP for help.

The Cassandra server is configured to accept incoming connections on the default Cassandra client port 9042. This could be a security issue so it is strongly advisable to close this port or open it only for a specific IP address. Other ports for configuring nodes are closed by default in the firewall.

Cassandra configuration file

The Cassandra configuration file is located at /opt/bitnami/cassandra/conf/cassandra.yaml.

Cassandra ports

• Cassandra client: 9042
• Cassandra client thrift port: 9160
• Cassandra transport port: 7000
• Cassandra transport secure port: 7001
• Cassandra jmx port: 7199

Cassandra log file

The Cassandra log file is created at /opt/bitnami/cassandra/log/system.log.

What are the default ports?

A port is an endpoint of communication in an operating system that identifies a specific process or a type of service. Bitnami stacks include several services or servers that require a port.

Remember that if you need to open some ports you can follow the instructions given in the FAQ to learn how to open the server ports for remote access.

Port 22 is the default port for SSH connections.

The Cassandra access port is 9042. This port is closed by default, you must open it to enable remote access.

How to upload files to the server with SFTP?

First, obtain your SSH credentials by following these steps:

• Browse to the Bitnami Launchpad for Microsoft Azure and sign in if required using your Bitnami account.
• Select the "Virtual Machines" menu item.
• Select your cloud server from the resulting list.

• Note the server IP address and SSH credentials on the resulting page. Your server may have been deployed using either an SSH password or an SSH key.

  

  

Although you can use any SFTP/SCP client to transfer files to your server, this guide documents FileZilla (Windows, Linux and Mac OS X), WinSCP (Windows) and Cyberduck (Mac OS X).

Using an SSH Key

Once you have your server's SSH key, choose your preferred application and follow the steps below to connect to the server using SFTP.

FileZilla

Follow these steps:

• Download and install FileZilla.
• Launch FileZilla and use the "Edit -> Settings" command to bring up FileZilla's configuration settings.

• Within the "Connection -> SFTP" section, use the "Add keyfile" command to select the private key file for the server. FileZilla will use this private key to log in to the server.

  

• Use the "File -> Site Manager -> New Site" command to bring up the FileZilla Site Manager, where you can set up a connection to your server.
• Enter your server host name and specify bitnami as the user name.

• Select "SFTP" as the protocol and "Ask for password" as the logon type.

  

• Use the "Connect" button to connect to the server and begin an SFTP session. You might need to accept the server key, by clicking "Yes" or "OK" to proceed.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

If you have problems accessing your server, get extra information by use the "Edit -> Settings -> Debug" menu to activate FileZilla's debug log.

WinSCP

Follow these steps:

• Download and install WinSCP.
• Launch WinSCP and in the "Session" panel, select "SCP" as the file protocol.

• Enter your server host name and specify bitnami as the user name.

  

• Click the "Advanced…" button and within the "SSH -> Authentication -> Authentication parameters" section, select the private key file for the server. WinSCP will use this private key to log in to the server.

  

• From the "Session" panel, use the "Login" button to connect to the server and begin an SCP session.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

If you need to upload files to a location where the bitnami user doesn't have write permissions, you have two options:

• Once you have configured WinSCP as described above, click the "Advanced…" button and within the "Environment -> Shell" panel, select sudo su - as your shell. This will allow you to upload files using the administrator account.

  

• Upload the files to the /home/bitnami directory as usual. Then, connect via SSH and move the files to the desired location with the sudo command, as shown below:

   $ sudo mv /home/bitnami/uploaded-file /path/to/desired/location/
  

Cyberduck

Follow these steps:

• Select the "Open Connection" command and specify "SFTP" as the connection protocol.

  

• In the connection details panel, under the "More Options" section, enable the "Use Public Key Authentication" option and specify the path to the private key file for the server.

  

• Use the "Connect" button to connect to the server and begin an SFTP session.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

Using a Password

Once you have your server's SSH credentials, choose your preferred application and follow the steps below to connect to the server using SFTP.

FileZilla

Follow these steps:

• Download and install FileZilla.
• Launch FileZilla and use the "File -> Site Manager -> New Site" command to bring up the FileZilla Site Manager, where you can set up a connection to your server.
• Enter your server host name.

• Select "SFTP" as the protocol and "Ask for password" as the logon type. Use bitnami as the server username and the password generated during the server deployment process.

  

• Use the "Connect" button to connect to the server and begin an SFTP session. You might need to accept the server key, by clicking "Yes" or "OK" to proceed.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

If you have problems accessing your server, get extra information by use the "Edit -> Settings -> Debug" menu to activate FileZilla's debug log.

WinSCP

Follow these steps:

• Download and install WinSCP.
• Launch WinSCP and in the "Session" panel, select "SCP" as the file protocol.

• Enter your server host name and set bitnami as the server username. Enter the corresponding password as well.

  

• From the "Session" panel, use the "Login" button to connect to the server and begin an SCP session.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

Cyberduck

Follow these steps:

• Select the "Open Connection" command and specify "SFTP" as the connection protocol.

  

• In the connection details panel, enter the server IP address, bitnami as the username, and the password generated during the deployment process.

  

• Use the "Connect" button to connect to the server and begin an SFTP session.

You should now be logged into the /home/bitnami directory on the server. You can now transfer files by dragging and dropping them from the local server window to the remote server window.

How to create a Virtual Network peering?

To connect two instances internally you can enable a Virtual Network (VNet) peering from the Azure Portal. Depending if the instances were launched in the same or in different resource groups, there are two methods for performing a internal connection: sharing a virtual network or enabling a virtual network peering.

• Learn how to share a virtual network to join instances from the same resource group.
• Learn how to enable virtual network peering to join instances from different resource groups.

How to find the database credentials?

• Database username: cassandra.
• Database password: The same as the application password. Find out how to obtain application credentials.

How to connect to the Cassandra server?

You can connect to Cassandra from the same server. Obtain the password from the dashboard for your server.

$ cqlsh -u cassandra

This will connect you to the Cassandra console and display a prompt. Once connected, you can run cqlsh commands to create and populate data. For example, the command below lists available keyspaces:

cassandra@cqlsh> describe keyspaces
system_traces  system_schema  system_auth  system  system_distributed

You can learn more about Cassandra in the Cassandra Getting Started guide.

How to connect to Cassandra from a different machine?

For security reasons, the Cassandra ports in this solution cannot be accessed over a public IP address. To connect to Cassandra from a different machine, you must open ports 9042, 9160, 7000, 7001 and 7199 for remote access. Refer to the FAQ for more information on this.

IMPORTANT: Making this application's network ports public is a significant security risk. You are strongly advised to only allow access to those ports from trusted networks. If, for development purposes, you need to access from outside of a trusted network, please do not allow access to those ports via a public IP address. Instead, use a secure channel such as a VPN or an SSH tunnel. Follow these instructions to remotely connect safely and reliably.

You can then access Cassandra using a command like the one below:

$ cqlsh -u cassandra SERVER-IP

How to check the Cassandra server version?

Use the commands below:

$ cqlsh -u cassandra
Password:
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 2.1.1 | CQL spec 3.2.0 | Native protocol v3]
Use HELP for help.

cassandra@cqlsh> show version
[cqlsh 5.0.1 | Cassandra 2.1.1 | CQL spec 3.2.0 | Native protocol v3]

How to change the Cassandra administrator password?

You can modify the Cassandra password using the following command at the shell prompt:

$ cqlsh -u cassandra -p PASSWORD
Connected to Test Cluster at 127.0.0.1:9042.
[cqlsh 5.0.1 | Cassandra 3.9 | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.

cqlsh> ALTER USER cassandra with PASSWORD 'NEWPASSWORD';
cqlsh> exit

How to reset the Cassandra administrator password?

You can reset the administrator password by following the steps below:

• Edit the /opt/bitnami/cassandra/conf/cassandra.yaml file and replace the following lines:

     authenticator: PasswordAuthenticator
     authorizer: CassandraAuthorizer
  

  with:

     authenticator: AllowAllAuthenticator
     authorizer: AllowAllAuthorizer
  

• Restart your database:

     $ sudo /opt/bitnami/ctlscript.sh restart cassandra
  

• Execute the following commands:

     $ cqlsh
     Connected to Test Cluster at 127.0.0.1:9042.
     [cqlsh 5.0.1 | Cassandra 3.9 | CQL spec 3.4.2 | Native protocol v4]
     Use HELP for help.
        
     cqlsh> UPDATE system_auth.roles SET salted_hash = '$2a$10$1gMPBy9zSkDzKxdbU2v/gOslcMRPDcXVqmwQYBmi8MVgYvNdRZw/.' WHERE role = 'cassandra';
     cqlsh> exit
  

• Undo the changes made in /opt/bitnami/cassandra/conf/cassandra.yaml and restart Cassandra again. Now you can access your database using the user name cassandra and password cassandra:

       $ cqlsh -u cassandra -p cassandra
       Connected to Test Cluster at 127.0.0.1:9042.
       [cqlsh 5.0.1 | Cassandra 3.9 | CQL spec 3.4.2 | Native protocol v4]
       Use HELP for help.
       cqlsh>
  

Once you have access, don't forget to change the cassandra user account password to something else as described in the previous section. This is the default password and it's unsecure.

How to create a Cassandra cluster?

Create a Cluster with a Single Seed Node

• Launch the Bitnami Cassandra Stack on each node.

• Log in to each node and stop the Cassandra service.

   $ sudo /opt/bitnami/ctlscript.sh stop cassandra
  

• Get the public and private IP address of each node in the cluster.

• Select one of the nodes as the seed node for the cluster. In this guide, assume that the seed node has public IP address 130.1.1.1 and private IP address 10.1.1.1.

• Open the Cassandra transport port (tcp:7000 by default) in your server firewall. Then, restart your Cassandra servers.

• On each node in the cluster, modify the /opt/bitnami/cassandra/conf/cassandra.yaml file and update the following directives:

  • -seeds: Use the public IP address of the seed node.

  • listen_address: Use the current node's private IP address.

  • broadcast_address: Use the current node's public IP address.

  • endpoint_snitch: Select the correct snitch for your environment based on the official documentation.

  For example, on the seed node, your configuration file might look like this:

     cluster_name: 'MyCassandraCluster'
     num_tokens: 256
     seed_provider:
       - class_name: org.apache.cassandra.locator.SimpleSeedProvider
         parameters:
              - seeds: "130.1.1.1"
     broadcast_address: 130.1.1.1
     listen_address: 10.1.1.1
     endpoint_snitch: GossipingPropertyFileSnitch
  

  Repeat the above configuration for all the nodes in the cluster. Remember that you must modify the listen_address and broadcast_address on each node to reflect the node's IP addresses.

• For all nodes apart from the seed node, delete the default data. This is necessary to avoid collisions between the system tables on different nodes.

   $ sudo rm -rf /opt/bitnami/cassandra/data/*
  

• Start Cassandra on the seed node, followed by the other nodes, to have the changes take effect:

   $ sudo /opt/bitnami/ctlscript.sh start cassandra
  

Your cluster should now be operational with a single seed node. To verify, execute the command below on any node in the cluster:

$ /opt/bitnami/cassandra/bin/nodetool status

You can connect to any server of the cluster using the credentials for the first seed node.

You can also watch the Cassandra log file at /opt/bitnami/cassandra/log/system.log to check that the cluster nodes recognize and can communicate with each other.

Create a Cluster with Multiple Seed Nodes

• Launch the Bitnami Cassandra Stack on a new node. This will be the new seed node for your cluster.

• Log in to each node and stop the Cassandra service.

     $ sudo /opt/bitnami/ctlscript.sh stop cassandra
  

• Get the public and private IP address of the new seed node. In this guide, assume that the new seed node has public IP address 140.1.1.1 and private IP address 20.1.1.1.

• On the new node, edit the configuration file /opt/bitnami/cassandra/conf/cassandra.yaml and specify it as a seed node by adding its public IP address to the seeds list. Also specify the other configuration parameters, such as the listen_address and the broadcast_address, as described in the previous section. Here is what the configuration file would look like:

     cluster_name: 'MyCassandraCluster'
     num_tokens: 256
     seed_provider:
       - class_name: org.apache.cassandra.locator.SimpleSeedProvider
         parameters:
              - seeds: "130.1.1.1, 140.1.1.1"
     broadcast_address: 140.1.1.1
     listen_address: 20.1.1.1
     endpoint_snitch: GossipingPropertyFileSnitch
  

• Delete the default data. This is necessary to avoid collisions between the system tables on different nodes.

     $ sudo rm -rf /opt/bitnami/cassandra/data/*
  

• On each of the other nodes in the cluster, update the /opt/bitnami/cassandra/conf/cassandra.yaml file and add the public IP address of the new seed node to the seeds list.

• Restart Cassandra on the seed nodes, followed by the non-seed nodes.

     $ sudo /opt/bitnami/ctlscript.sh start cassandra
  

Your cluster should now be operational with the new seed node. To verify, execute the command below on any node in the cluster:

$ /opt/bitnami/cassandra/bin/nodetool status

You can connect to any server of the cluster using the credentials for the first seed node.

You can also watch the Cassandra log file at /opt/bitnami/cassandra/log/system.log to check that the cluster nodes recognize and can communicate with each other.

How can I run a command in the Bitnami Cassandra Stack?

Log in to the server console as the bitnami user and run the command as usual. The required environment is automatically loaded for the bitnami user.

How to create a full backup of Cassandra?

Backup

The Bitnami Cassandra Stack is self-contained and the simplest option for performing a backup is to copy or compress the Bitnami stack installation directory. To do so in a safe manner, you will need to stop all servers, so this method may not be appropriate if you have people accessing the application continuously.

Follow these steps:

• Change to the directory in which you wish to save your backup:

    $ cd /your/directory
  

• Stop all servers:

    $ sudo /opt/bitnami/ctlscript.sh stop
  

• Create a compressed file with the stack contents:

    $ sudo tar -pczvf application-backup.tar.gz /opt/bitnami
  

• Restart all servers:

    $ sudo /opt/bitnami/ctlscript.sh start
  

You should now download or transfer the application-backup.tar.gz file to a safe location.

Restore

Follow these steps:

• Change to the directory containing your backup:

    $ cd /your/directory
  

• Stop all servers:

    $ sudo /opt/bitnami/ctlscript.sh stop
  

• Move the current stack to a different location:

    $ sudo mv /opt/bitnami /tmp/bitnami-backup
  

• Uncompress the backup file to the original directoryv

    $ sudo tar -pxzvf application-backup.tar.gz -C /
  

• Start all servers:

    $ sudo /opt/bitnami/ctlscript.sh start
  

If you want to create only a database backup, refer to these instructions for MySQL and PostgreSQL.