diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/authentication.rst | 170 | ||||
| -rwxr-xr-x | docs/index.rst | 21 | ||||
| -rw-r--r-- | docs/multi.rst | 181 | ||||
| -rw-r--r-- | docs/setup.rst | 50 | ||||
| -rw-r--r-- | docs/single.rst | 85 |
5 files changed, 499 insertions, 8 deletions
diff --git a/docs/authentication.rst b/docs/authentication.rst new file mode 100644 index 00000000..3c6f48a4 --- /dev/null +++ b/docs/authentication.rst @@ -0,0 +1,170 @@ + `For Single install:`_ + + `Multi-Site Install:`_ + + `Headers:`_ + + `AAF Authentication`_ + + `AID Authentication Non-AAF`_ + +`Onboarding API`_ + +`Add Application`_ + +`Get Application`_ + +`Edit Application`_ + +`Delete Application`_ + + +Steps to test AAF 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, userId and password. + +**Non AAF applications (AID)** Works just like AAF but Namespace is an app name and MUSIC manages the User instead of AAF + +All the required params should be sent as headers. + +Changed in Cassandra: Admin needs to create the following keyspace and table. + +In the cassandra bin dir run ./cqlsh 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: +^^^^^^^^^^^^^^^^^^^ +:: + + //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: +^^^^^^^^^^^^^^^^^^^ + +:: + + //Create Admin Keyspace + + CREATE KEYSPACE admin + WITH REPLICATION = { + 'class' : 'NetworkTopologyStrategy', + 'DC1':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 headers ns, userId and password are mandatory. + +For Non AAF applications if aid 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. + +Required Headers + +AAF Authentication +^^^^^^^^^^^^^^^^^^ +:: + + Key : Value : Description + ns : org.onap.aaf : AAF Namespace + userId : username : USer Id + password: password : Password of User + +AID Authentication Non-AAF +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + Key : Value : Description + ns : App Name : App Name + userId : username : Username for this user (Required during Create keyspace Only) + password: password : Password for this user (Required during Create keyspace Only) + +Onboarding API +^^^^^^^^^^^^^^ + +Add Application +^^^^^^^^^^^^^^^ + +:: + + POST URL: /MUSIC/rest/v2/admin/onboardAppWithMusic with JSON as follows: + + { + "appname": "<the Namespace for aaf or the Identifier for the specific app using AID access", + "userId" : "<userid>", + "isAAF" : true/false, + "password" : "" + } + +Get Application +^^^^^^^^^^^^^^^ + +:: + + POST URL: /MUSIC/rest/v2/admin/search with JSON as follows: + + { + "appname": "<the Namespace for aaf or the Identifier for the specific app using AID access", + "isAAF" : true/false, + "aid" : "Unique ID for this user" + } + +Edit Application +^^^^^^^^^^^^^^^^ + +:: + + PUT URL: /MUSIC/rest/v2/admin/onboardAppWithMusic with JSON as follows: + + { + "aid" : "Unique ID for this user", + "appname": "<the Namespace for aaf or the Identifier for the specific app using AID access", + "userId" : "<userid>", + "isAAF" : true/false, + "password" : "" + } + +Delete Application +^^^^^^^^^^^^^^^^^^ + +:: + + DELETE URL: /MUSIC/rest/v2/admin/onboardAppWithMusic with JSON as follows: + + { + "aid" : "Unique ID for this app" + } diff --git a/docs/index.rst b/docs/index.rst index 417b6052..3ef97755 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,12 +8,17 @@ Music Developer Documentation .. toctree:: :maxdepth: 1 - architecture - configuration - consumedapis - delivery - index - installation - logging - offeredapis + Single-SIte Install <single> + Muili-Site Install <multi> + setup release-notes + + +.. architecture +.. configuration +.. consumedapis +.. delivery +.. index +.. installation +.. logging +.. offeredapis diff --git a/docs/multi.rst b/docs/multi.rst new file mode 100644 index 00000000..bc26465f --- /dev/null +++ b/docs/multi.rst @@ -0,0 +1,181 @@ +=========================== +Multi-site or Local Cluster +=========================== +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:: + + 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 + +- In the cassandra-rackdc.properties file, assign data center and rack names as needed if required ( This is for multi data center install). +- 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:: + + ./cassandra + +- In the cassandra bin folder, if you run the following it will tell you the state of the cluster:: + + ./nodetool status + +- To access cassandra, one any of the nodes you can run the following and then perform CQL queries.:: + + ./cqlsh <private ip> + +Extra Cassandra information for Authentication: +----------------------------------------------- +To create first user in Cassandra + +1. Edit conf/Cassandra.yaml file:: + + authenticator: PasswordAuthenticator + authorizer: CassandraAuthorizer + + +2. Restart Cassandra +3. Login to cqlsh with default credentials:: + + cqlsh -u cassandra -p cassandra + +4. To change default user create new user with the following command.:: + + CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER; + +5. Change password for default user ‘Cassandra’ so that no one will be able to login:: + + ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoonewillthinkof’; + +6. Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:: + + 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: + +:: + + 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 + +Create the directory /var/zookeeper in all the machines and within that 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: + + + + ./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. + +:: + + [zkshell] ls / + [zookeeper] + +Next, create a new znode by running + +:: + + create /zk_test my_data. + +This creates a new znode and associates the string "my_data" with the node. You should see: + +:: + + [zkshell] create /zk_test my_data + Created /zk_test + +Issue another ls / command to see what the directory looks like: + +:: + + [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: +cassandra.yaml:: + + my.id=0 + all.ids=0 + my.public.ip=localhost + all.public.ips=localhost + ####################################### + # Optional current values are defaults + ####################################### + # If using docker this would point to the specific docker name. + #zookeeper.host=localhost + #cassandra.host=localhost + #music.ip=localhost + #debug=true + #music.rest.ip=localhost + #lock.lease.period=6000 + # Cassandra Login - Do not user cassandra/cassandra + cassandra.user=cassandra1 + cassandra.password=cassandra1 + # AAF Endpoint + #aaf.endpoint.url=<aaf url> + +- Build the MUSIC.war (see `Build Music`_) 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 MUSIC dir with various logs will be created. + +Build Music +^^^^^^^^^^^ +Documentation will be updated to show that. Code can be downloaded from Music Gerrit. +To build you will need to ensure you update your settings with the ONAP settings.xml +(Workspace and Development Tools) + +Once you have done that run the following: + +:: + + # If you installed settings.xml in your ./m2 folder + mvn clean package + # If you placed the settings.xml elsewhere: + mvn clean package -s /path/to/settings.xml + +After it is built you will find the MUSIC.war in the ./target folder. + +There is a folder called postman that contains a postman collection for testing with postman. + +Continue with `Authentication <./automation.rst>`_ +
\ No newline at end of file diff --git a/docs/setup.rst b/docs/setup.rst new file mode 100644 index 00000000..208c779b --- /dev/null +++ b/docs/setup.rst @@ -0,0 +1,50 @@ +Setup for Developing MUSIC +========================== + +.. toctree:: + :maxdepth: 1 + + Single-Site Install <single> + Muili-Site Install <multi> + Authentication + +MUSIC is to be installed in a single Dir on a vm. + + +The main MUSIC dir should be:: + + /opt/app/music + # These also need to be set up + /opt/app/music/etc + /opt/app/music/logs + /opt/app/music/lib/zookeeper + +When installing Tomcat, Cassandra and Zookeeper they should also be installed here.:: + + /opt/app/music/apache-cassandra-n.n.n + /opt/app/music/zookeeper-n.n.n + /opt/app/music/apache-tomcat-n.n.n + + +You could also create links from install dirs to a common name ie\::: + + 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.:: + + # For cassandra it should be (This is the default) + /opt/app/music/cassandra/data + # For Zookeeper it should be + /opt/app/music/zookeeper/ + + +Continue by selecting the link to the setup you are doing. + +.. toctree:: + :maxdepth: 1 + + Single-Site Install <single> + Muili-Site Install <multi> + Authentication diff --git a/docs/single.rst b/docs/single.rst new file mode 100644 index 00000000..08c5e315 --- /dev/null +++ b/docs/single.rst @@ -0,0 +1,85 @@ +====================== +Single VM/Site install +====================== +Local Installation +------------------ +Prerequisites + +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). + +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 OpenJDK 8 on your machine. +- Download Apache Cassandra 3.0, 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. +- Download the Version 8.5 Apache Tomcat and install it using these instructions https://tomcat.apache.org/download-80.cgi (this is for version 8.5). +- Create a music.properties file and place it in /opt/app/music/etc/. Here is a sample of the file: + +music.properties:: + + music.properties + my.id=0 + all.ids=0 + my.public.ip=localhost + all.public.ips=localhost + ######################## + # Optional current values are defaults + ###################################### + # If using docker this would point to the specific docker name. + #zookeeper.host=localhost + #cassandra.host=localhost + #music.ip=localhost + + #debug=true + #music.rest.ip=localhost + #lock.lease.period=6000 + # Cassandra Login - Do not user cassandra/cassandra + cassandra.user=cassandra1 + cassandra.password=cassandra1 + # AAF Endpoint + #aaf.endpoint.url=<aaf url> + +- Make a dir /opt/app/music/logs MUSIC dir with MUSIC logs will be created in this dir after MUSIC starts. +- Build the MUSIC.war and place in tomcat webapps dir. +- 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 + +1. Edit conf/Cassandra.yaml file:: + + authenticator: PasswordAuthenticator + authorizer: CassandraAuthorizer + + +2. Restart Cassandra +3. Login to cqlsh with default credentials:: + + cqlsh -u cassandra -p cassandra + +4. To change default user create new user with the following command.:: + + CREATE USER new_user WITH PASSWORD ‘new_password’ SUPERUSER; + +5. Change password for default user ‘Cassandra’ so that no one will be able to login:: + + ALTER USER cassandra WITH PASSWORD ‘SomeLongRandomStringNoonewillthinkof’; + +6. Provide the new user credentials to Music. Update music.properties file and uncomment or add the following:: + + 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. + +Continue with `Authentication <./automation.rst>`_ + + + +
\ No newline at end of file |