Initial code Import.

Issue-ID: MUSIC-21

Change-Id: I89ceab0891b4b7cb999dab532d6bae9092f027cc
Signed-off-by: arthurdent3 <tn1381@att.com>

1 files changed, 385 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..3f83f2da
--- /dev/null
+++ b/README.md
@@ -0,0 +1,385 @@
+## MUSIC - Multi-site State Coordination Service
+
+To achieve 5 9s of availability on 3 9s or lower software and infrastructure in a cost-effective manner, ONAP components need to work in a reliable, active-active manner across multiple sites (platform-maturity resiliency level 3). A fundamental aspect of this is  state management across geo-distributed sites in a reliable, scalable, highly available and efficient manner. This is an important and challenging problem because of three fundamental reasons:
+
+* Current solutions for state-management of  ONAP components like MariaDB clustering, that work very effectively within a site, may not scale across geo-distributed sites (e.g., Beijing, Amsterdam and Irvine) or allow partitioned operation (thereby compromising availability). This is mainly because WAN latencies are much higher across sites and frequent network partitions can occur.
+
+* ONAP components often have a diverse range of requirements in terms of state replication. While some components need to synchronously manage state across replicas, others may tolerate asynchronous replication. This diversity needs to be leveraged to provide better performance and higher availability across sites.
+
+* ONAP components often need to partition state across different replicas, perform consistent operations on them and ensure that on failover, the new owner has access to the latest state. The distributed protocols to achieve such consistent ownership is complex and replete with corners cases, especially in the face of network partitions. Currently, each component is building its own handcrafted solution which is  wasteful and worse, can be erroneous.
+
+In this project, we identify common state management concerns across ONAP components and provide a multi-site state coordination/management service (MUSIC) with a rich suite of recipes that each ONAP component can simply configure and use for their state-management needs.
+
+---
+
+[Local Installation](#local-install)
+
+[Multi-site Installation](#ms-install)
+
+[Muting MUSIC jersey output](#jersey-mute)
+
+[Authentications/AAF Setup](#auth-setup)
+
+
+Prerequisites
+
+MUSIC is to be installed in a single Dir. 
+
+```bash
+#The main MUSIC dir should be
+/opt/app/music
+# These also need to be set up
+/opt/app/music/etc
+/opt/app/music/logs
+```
+When installing Tomcat, Cassandra and Zookeeper they should also be installed here. 
+```bash
+/opt/app/music/apache-cassandra-n.n.n
+/opt/app/music/zookeeper-n.n.n
+/opt/app/music/apache-tomcat-n.n.n
+```
+Its suggested you create links from install dirs to a common name ie:
+```bash 
+ln -s /opt/app/music/apache-cassandra-n.n.n cassandra
+ln -s /opt/app/music/zookeeper-n.n.n zookeeper
+ln -s /opt/app/music/apache-tomcat-n.n.n tomcat
+```
+ 
+Cassandra and Zookeeper have data dirs. 
+```bash
+# For cassandra it should be (This is the default) 
+/opt/app/music/cassandra/data
+# For Zookeeper it should be 
+/opt/app/music/var/zookeeper/
+```
+ 
+If you are using a VM make sure it has at least 8 GB of RAM (It may work with 4 GB, but with 2 GB it
+does give issues).
+
+<a name="local-install"> 
+
+## Local Installation 
+
+</a>
+
+### Instructions
+
+- Create MUSIC Install dir /opt/app/music
+- Open /etc/hosts as sudo and enter the name of the vm alongside localhost in the line for 127.0.0.1. E.g. 127.0.0.1 localhost music-1. Some of the apt-get installation seem to require this.
+- Ensure you have java jdk 8 or above working on your machine.
+- Download apache Apache Cassandra 3.2, install into /opt/app/music and follow these instructions http://cassandra.apache.org/doc/latest/getting_started/installing.html till and including Step
+- By the end of this you should have Cassandra working.
+- Download Apache Zookeeper 3.4.6, install into /opt/app/music and follow these instructions https://zookeeper.apache.org/doc/trunk/zookeeperStarted.html pertaining to the standalone operation. By the end of this you should have Zookeeper working.
+- Create a music.properties file and place it in /opt/app/music/etc/. Here is a sample of the file:
+
+```properties 
+my.id=0
+all.ids=0
+my.public.ip=localhost
+all.public.ips=localhost
+#######################################
+# Optional current values are defaults
+#######################################
+#zookeeper.host=localhost
+#cassandra.host=localhost
+#music.ip=localhost
+#debug=true
+#music.rest.ip=localhost
+#lock.lease.period=6000
+cassandra.user=cassandra
+cassandra.password=cassandra
+aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
+```
+
+- Make a dir /opt/app/music/logs MUSIC dir with MUSIC logs will be created in this dir after MUSIC starts.
+- Download the latest Apache Tomcat and install it using these instructions http://tecadmin.net/install-tomcat-9-on-ubuntu/ (this is for version 9).
+- Build the MUSIC.war (or download it from https://github.com/att/music/blob/master/MUSIC.war) and place it within the webapps folder of the tomcat installation.
+- Authentications/AAF Setup For Authentication setup.
+- Start tomcat and you should now have MUSIC running.
+
+ 
+Extra Cassandra information for Authentication:
+
+To create first user in Cassandra
+
+Edit conf/Cassandra.yaml file
+
+```yaml 
+authenticator: PasswordAuthenticator
+authorizer: CassandraAuthorizer
+```
+Restart Cassandra
+Login to cqlsh with default credentials
+
+```bash
+cqlsh -u cassandra -p cassandra
+```
+
+To change default user create new user with the following command.
+
+```sql
+CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
+```
+Change password for default user ‘Cassandra’ so that no one will be able to login
+
+```sql
+ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
+```
+Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
+
+```properties
+cassandra.user=<new_user>
+cassandra.password=<new_password>
+```
+
+To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
+
+
+
+<a name ="ms-install">
+
+## Multi-site Installation 
+
+</a>
+
+Follow the instructions for local MUSIC installation on all the machines/VMs/hosts (referred to as a node) on which you want MUSIC installed. However, Cassandra and Zookeeper needs to be configured to run as multi-node installations (instructions below) before running them.
+
+#### Cassandra:
+In the cassandra.yaml file which is present in the cassa_install/conf directory in each node, set the following parameters:
+cassandra.yaml
+```yaml
+cluster_name: ‘name of cluster’
+num_tokens: 256
+seed_provider:
+class_name: org.apache.cassandra.locator.SimpleSeedProvider
+parameters:
+seeds:  "<public ip of first seed>, <public ip of second seed>, etc"
+listen_address: private ip of VM
+broadcast_address: public ip of VM
+endpoint_snitch: GossipingPropertyFileSnitch
+rpc_address: <private ip>
+phi_convict_threshold: 12
+authenticator: PasswordAuthenticator
+authorizer: CassandraAuthorizer
+```
+ 
+
+In the cassandra-rackdc.properties file, assign data center and rack names as if required.
+
+Once this is done on all three nodes, you can run cassandra on each of the nodes through the cassandra bin folder with this command     
+```bash
+./cassandra
+```
+    In the cassandra bin folder, if you run the following it will tell you the state of the cluster.       
+```bash
+./nodetool status
+```
+To access cassandra, one any of the nodes you can run the following and then perform CQL queries.
+```bash
+./cqlsh <private ip>
+```
+
+To create first user in Cassandra
+
+    Restart Cassandra
+    Login to cqlsh with default credentials
+
+```bash
+cqlsh -u cassandra -p cassandra
+```
+
+To change default user create new user with the following command.
+
+```sql
+CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER;
+```
+Change password for default user ‘Cassandra’ so that no one will be able to login
+
+```sql
+ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoOneWillThinkOf’;
+```
+Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:
+
+```properties
+cassandra.user=<new_user>
+cassandra.password=<new_password>
+```
+
+To access keyspace through cqlsh, login with credentials that are passed to MUSIC while creating the keyspace.
+
+#### Zookeeper:
+
+Once zookeeper has been installed on all the nodes, modify the  zk_install_location/conf/zoo.cfg on all the nodes with the following lines:
+```properties
+tickTime=2000
+dataDir=/opt/app/music/var/zookeeper
+clientPort=2181
+initLimit=5
+syncLimit=2
+quorumListenOnAllIPs=true
+server.1=public IP of node 1:2888:3888
+server.2=public IP of node 2:2888:3888
+server.3=public IP of node 3:2888:3888
+```
+In /opt/app/music/var/zookeeper in all the machines, create a file called myid that contains the id of the machine. The machine running node.i will contain just the number i in the file myid.
+
+Start each of the nodes one by one from the zk_install_location/bin folder using the command:
+```bash
+./zkServer.sh start
+```
+On each node check the file zookeeper.out in the  zk_install_location/ bin to make sure all the machines are talking to each other and there are no errors. Note that while the machines are yet to come up there maybe error messages saying that connection has not yet been established. Clearly, this is ok.
+
+If there are no errors, then from zk_install_location/bin simply run the following to get command line access to zookeeper.   ./zkCli.sh
+
+Run these commands on different machines to make sure the zk nodes are syncing.
+```bash
+[zkshell] ls /
+[zookeeper]
+```
+Next, create a new znode by running
+```bash
+create /zk_test my_data.
+```
+This creates a new znode and associates the string "my_data" with the node. You should see:
+```bash
+[zkshell] create /zk_test my_data
+Created /zk_test
+```
+Issue another ls / command to see what the directory looks like:
+```bash
+[zkshell] ls /
+[zookeeper, zk_test]
+```
+
+#### MUSIC
+
+Create a music.properties file and place it in /opt/app/music/etc at each node. Here is a sample of the file: If this location is to be changed please update the file project.properties in the src/main/resources directory before compiling MUSIC to a war.
+```properties
+my.id=0
+all.ids=0:1:2
+my.public.ip=public IP of node 0
+#For each node, a separate file needs to be created with its own id (between 0 and the number of nodes) and with information about its own public ip.
+all.public.ips=public IP of node 0:public IP of node 1:public IP of node 2
+#######################################
+# Optional current values are defaults
+#######################################
+#zookeeper.host=localhost
+#cassandra.host=localhost
+#music.ip=localhost
+#debug=true
+#music.rest.ip=localhost
+#lock.lease.period=6000
+cassandra.user=cassandra
+cassandra.password=cassandra
+aaf.endpoint.url=http://aafendpoint/proxy/authz/nss/
+```
+ 
+- Download the latest Apache Tomcat and install it using these instructions http://tecadmin.net/install-tomcat-9-on-ubuntu/ (this is for version 9).
+- Build the MUSIC.war and place it within the webapps folder of the tomcat installation.
+- Start tomcat and you should now have MUSIC running.
+
+- For Logging create a dir /opt/app/music/logs. When MUSIC/Tomcat starts a dir opt/app/music/logsMUSIC with various logs will be created.
+ The application log is music.log and the others are debug.log and error.log.
+
+<a name="jersey-mute">
+
+### Muting MUSIC jersey output
+
+The jersey package that MUSIC uses to parse REST calls prints out the entire header and json body by
+default. To mute it (if it exists), remove the following lines from the web.xml in the WEB_INF foler:
+
+```xml
+<init-param>
+  <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
+  <param-value>com.sun.jersey.api.container.filter.LoggingFilter</param-value>
+</init-param>
+```
+
+<a name ="auth-setup">
+
+### Authentication Setup
+
+MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF. 
+If an application has already been using AAF, it should have required namespace, mechId and password. Non AAF applications will be provided with a random unique id. MUSIC will tag the keyspace with the UID and store internally and any calls to use/modify the keyspace will require the UID. 
+All the required params should be sent as headers.
+
+- MUSIC has been enhanced to support applications which are already authenticated using AAF and applications which are not authenticated using AAF.
+- If an application has already been using AAF, it should have required namespace, mechId and password.
+- Non AAF applications (AID) will be provided with a random unique id. MUSIC will tag the keyspace with the UID and store internally and any calls to use/modify the keyspace will require the UID.
+
+All the required params should be sent as headers.
+
+Admin needs to create the following keyspace and table via cslsh.
+
+In the cassandra bin dir run ./cqlsh -u <user> -p <password> and log in to db then:
+
+If you want to save the following in a file you can then run ./cqlsh -f <file.cql>
+For Single install:
+```sql
+//Create Admin Keyspace
+ 
+CREATE KEYSPACE admin
+  WITH REPLICATION = {
+    'class' : 'SimpleStrategy',
+    'replication_factor': 1
+  }
+  AND DURABLE_WRITES = true;
+ 
+CREATE TABLE admin.keyspace_master (
+  uuid uuid,
+  keyspace_name text,
+  application_name text,
+  is_api boolean,
+  password text,
+  username text,
+  is_aaf boolean,
+  PRIMARY KEY (uuid)
+);
+```
+Multi-Site Install:
+```sql
+//Create Admin Keyspace
+ 
+CREATE KEYSPACE admin
+  WITH REPLICATION = {
+    'class' : 'NetworkTopologyStrategy',
+    'DC1':2,
+    'DC2':2,
+    'DC3':2
+  }
+  AND DURABLE_WRITES = true;
+ 
+CREATE TABLE admin.keyspace_master (
+  uuid uuid,
+  keyspace_name text,
+  application_name text,
+  is_api boolean,
+  password text,
+  username text,
+  is_aaf boolean,
+  PRIMARY KEY (uuid)
+);
+```
+
+Headers:
+- For AAF applications all the 3 of the following headers are mandatory. 
+  - <b>ns</b>
+  - <b>mechId</b>
+  - <b>password</b>
+- For Non AAF applications if the header <b>aid</b> is not provided MUSIC creates new random unique UUID and returns to caller. 
+- Caller application then need to save the UUID and need to pass the UUID to further modify/access the keyspace.
+- Make sure steps to set up Cassandra for authentication above in the cassandra.yaml were done.
+
+
+### On Boarding app
+The following API is used to onboard the applications.
+/MUSIC/rest/v2/admin/onboardAppWithMusic 
+This is a POST call and requires the following JSON:
+```json
+{
+"appname": "<the Namespace for aaf or the Identifier for the specific app using AID access>",
+"userId" : "<userid>",
+"isAAF"  : true|false
+}
+```
+