diff options
Diffstat (limited to 'docs/sections')
| -rw-r--r-- | docs/sections/development/index.rst | 161 | ||||
| -rw-r--r-- | docs/sections/installation/AAF-Integration-Guide.rst | 72 | ||||
| -rw-r--r-- | docs/sections/installation/AAF_Environment_Beijing.rst | 256 | ||||
| -rw-r--r-- | docs/sections/installation/Bootstrapping-AAF-Components.rst | 256 | ||||
| -rw-r--r-- | docs/sections/installation/Installation.rst | 104 | ||||
| -rw-r--r-- | docs/sections/installation/client_vol.rst | 151 | ||||
| -rw-r--r-- | docs/sections/installation/install_from_source.rst | 219 | ||||
| -rw-r--r-- | docs/sections/logging.rst | 13 |
8 files changed, 174 insertions, 1058 deletions
diff --git a/docs/sections/development/index.rst b/docs/sections/development/index.rst index be962522..623da6aa 100644 --- a/docs/sections/development/index.rst +++ b/docs/sections/development/index.rst @@ -14,6 +14,167 @@ Resources * `Example RESTful Client`_ (Java Client) * `Developer Video`_ (might be large) +========================= +ONAP Test Env +========================= + +------- +Purpose +------- + +The AAF Test Environment is a single instance VM setp so that + - ONAP Developers can utilize AAF with their personal machines without having to run their own AAF. + - ONAP Developers can put the Permissions and Roles required for their Apps into a common AAF Environment with others + - AAF will pull (on demand) all the ONAP related Data (Perms/Roles/Identities) and put into "Bootstrap Data". + - This Bootstrap data becomes available on the myriad Testing Systems so that + - They don't have to create AAF Data loading on their own. + - The data is already consistent with other ONAP entities. + +------ +Access +------ + +You must be connected to the WindRiver "pod-onap-01" VPN to gain access +to AAF Beijing + +---------------- +DNS (/etc/hosts) +---------------- + +At this time, there is no known DNS available for ONAP Entities. It is +recommended that you add the following entry into your "/etc/hosts" on +your accessing machine: + + /etc/hosts: + + 10.12.6.214 aaf-onap-beijing-test aaf-onap-beijing-test.osaaf.org + +------------------------------ +Environment Artifacts (AAF FS) +------------------------------ + + AAF has an HTTP Fileserver to gain access to needed public info. + + http://aaf-onap-beijing-test.osaaf.org/- + +----------- +Credentials +----------- + + AAF does support User/Password, and allows additional plugins as it + did in Amsterdam, however, User/Password credentials are inferior to + PKI technology, and does not match the ONAP Design goal of TLS and + PKI Identity across the board. Therefore, while an individual + organization might avail themselves of the User/Password facilities + within AAF, for ONAP, we are avoiding. + + THEREFORE: **GO WITH CERTIFICATE IDENTITY** + + +Root Certificate +^^^^^^^^^^^^^^^^ + + `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__ + +AAF CA +^^^^^^ + + At time of Beijing, an official Certificate Authority for ONAP was + not declared, installed or operationalized. Secure TLS requires + certificates, so for the time being, the Certificate Authority is + being run by AAF Team. + +Root Certificate +'''''''''''''''' + + | The Root Certificate for ONAP Certificate Authority used by AAF + is \ `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__ + | Depending on your Browser/ Operating System, clicking on this link + will allow you to install this Cert into your Browser for GUI + access (see next) + + This Root Certificate is also available in "truststore" form, ready + to be used by Java or other processes: + +- + + - + + - `truststoreONAP.p12 <http://aaf-onap-beijing-test.osaaf.org/truststoreONAP.p12>`__ + - This Truststore has ONLY the ONAP AAF\_RootCA in it. + + - `truststoreONAPall.jks <http://aaf-onap-beijing-test.osaaf.org/truststoreONAPall.jks>`__ + - This Truststore has the ONAP AAF\_RootCA in it PLUS all the Public CA Certs that are in Java 1.8.131 (note: this is in jks format, because the original JAVA truststore was in jks format) + + Note: as of Java 8, pkcs12 format is recommended, rather than jks. + Java's "keytool" utility provides a conversion for .jks for Java 7 + and previous. + +Identity +'''''''' + + Certificates certify nothing if there is no identity or process to + verify the Identity. Typically, for a company, an HR department + will establish the formal organization, specifically, who reports to + whom. For ONAP, at time of Beijing, no such formalized "Org Chart" + existed, so we'll be building this up as we go along. + + Therefore, with each Certificate Request, we'll need identity + information as well, that will be entered into an ONAP Identity + file. Again, as a real company, this can be derived or accessed + real-time (if available) as an "Organization Plugin". Again, as + there appears to be no such central formal system in ONAP, though, + of course, Linux Foundation logins have some of this information for + ALL LF projects. Until ONAP declares such a system or decides how + we might integrate with LF for Identity and we have time to create + an Integration strategy, AAF will control this data. + + For each Identity, we'll need: + + People + + + | # 0 - unique ID (for Apps, just make sure it is unique, for + People, one might consider your LinuxFoundation ID) + | # 1 - full name (for App, name of the APP) + | # 2 - first name (for App, + | # 3 - last name + | # 4 - phone + | # 5 - official email + | # 6 - type - person + | # 7 - reports to: If you are working as part of a Project, list + the PTL of your Project. If you are PTL, just declare you are the + PTL + + Applications + + + | # 0 - unique ID - For ONAP Test, this will be the same a the App + Acronym. + | # 1 - full name of the App + | # 2 - App Acronym + | # 3 - App Description, or just "Application" + | # 5 - official email - a Distribution list for the Application, or + the Email of the Owner + | # 6 - type - application + | # 7 - reports to: give the Application Owner's Unique ID. Note, + this should also be the Owner in AAF Namespace + +Obtaining a Certificate +''''''''''''''''''''''' + +Services/Clients + See `Automated Configuration and Certificates`_. + +.. _Automated Configuration and Certificates: AAF_4.1_config.html + +People + + + People Certificates can be used for browsers, curl, etc. + + Automation and tracking of People Certificates will be proposed for + Dublin. diff --git a/docs/sections/installation/AAF-Integration-Guide.rst b/docs/sections/installation/AAF-Integration-Guide.rst deleted file mode 100644 index 413b25cf..00000000 --- a/docs/sections/installation/AAF-Integration-Guide.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -AAF Integration Guide -============================ -.. code:: bash - - cadi.properties Template - # This is a normal Java Properties File - # Comments are with Pound Signs at beginning of lines, - # and multi-line expression of properties can be obtained by backslash at end of line - #hostname= - - cadi_loglevel=WARN - cadi_keyfile=conf/keyfile - - - # Configure AAF - aaf_url=http://172.18.0.2:8101 - #if you are running aaf service from a docker image you have to use aaf service IP and port number - aaf_id=<yourAPPID>@onap.org - aaf_password=enc:<encrypt> - - aaf_dme_timeout=5000 - # Note, User Expires for not Unit Test should be something like 900000 (15 mins) default is 10 mins - # 15 seconds is so that Unit Tests don't delay compiles, etc - aaf_user_expires=15000 - # High count... Rough top number of objects held in Cache per cycle. If high is reached, more are - # recycled next time. Depending on Memory usage, 2000 is probably decent. 1000 is default - aaf_high_count=100 - - -How to create CADI Keyfile & Encrypt Password ---------------------------------------------- - -Password Encryption -------------------- -CADI provides a method to encrypt data so that Passwords and other sensitive data can be stored safely. - -Keygen (Generate local Symmetrical Key) -A Keyfile is created by Cadi Utility. - -.. code:: bash - - java -jar cadi-core-<version>.jar keygen <keyfile> -Given this key file unlocks any passwords created, it should be stored in your configuration directory and protected with appropriate access permissions. For instance, if your container is Tomcat, and runs with a "tomcat" id, then you should: - -.. code:: bash - - java -jar cadi-core-<version>.jar keygen keyfile - chmod 400 keyfile - chown tomcat:tomcat keyfile - -Digest - Encrypt a Password ---------------------------- -The password is obtained by using the Cadi digest Utility (contained in the cadi-core-<version>.jar). - -.. code:: bash - - java -jar cadi-core-<version>.jar digest <your_password> <keyfile> - • "<keyfile>" is created by Cadi Utility, #keygen - • Understand that if you change the keyfile, then you need to rerun "digest" on passwords used in the users/groups definitions. - • Note: You cannot mix versions of cadi; the version used to digest your password must be the same version used at runtime. - -CADI PROPERTIES - CADI properties, typically named "cadi.properties", must have passwords encrypted. - 1. Take the results of the "Digest" command and prepend "enc:" - 2. Use this as the value of your property - -Example: aaf_password=enc:fMKMBfKHlRWL68cxD5XSIWNKRNYi5dih2LEHRFMIsut - diff --git a/docs/sections/installation/AAF_Environment_Beijing.rst b/docs/sections/installation/AAF_Environment_Beijing.rst deleted file mode 100644 index e93f7b17..00000000 --- a/docs/sections/installation/AAF_Environment_Beijing.rst +++ /dev/null @@ -1,256 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -AAF Environment - Beijing -========================= - -Access -~~~~~~ - -You must be connected to the WindRiver "pod-onap-01" VPN to gain access -to AAF Beijing - -DNS (/etc/hosts) -~~~~~~~~~~~~~~~~ - -At this time, there is no known DNS available for ONAP Entities. It is -recommended that you add the following entry into your "/etc/hosts" on -your accessing machine: - - /etc/hosts: - - 10.12.6.214 aaf-onap-beijing-test aaf-onap-beijing-test.osaaf.org - -Environment Artifacts (AAF FS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - AAF has an HTTP Fileserver to gain access to needed public info. - - http://aaf-onap-beijing-test.osaaf.org/- - -Credentials -~~~~~~~~~~~ - - AAF does support User/Password, and allows additional plugins as it - did in Amsterdam, however, User/Password credentials are inferior to - PKI technology, and does not match the ONAP Design goal of TLS and - PKI Identity across the board. Therefore, while an individual - organization might avail themselves of the User/Password facilities - within AAF, for ONAP, we are avoiding. - - THEREFORE: **GO WITH CERTIFICATE IDENTITY** - -Certificates -~~~~~~~~~~~~ - -Root Certificate -^^^^^^^^^^^^^^^^ - - `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__ - -AAF CA -^^^^^^ - - At time of Beijing, an official Certificate Authority for ONAP was - not declared, installed or operationalized. Secure TLS requires - certificates, so for the time being, the Certificate Authority is - being run by AAF Team. - -Root Certificate -'''''''''''''''' - - | The Root Certificate for ONAP Certificate Authority used by AAF - is \ `AAF\_RootCA.cer <http://aaf-onap-beijing-test.osaaf.org/AAF_RootCA.cer>`__ - | Depending on your Browser/ Operating System, clicking on this link - will allow you to install this Cert into your Browser for GUI - access (see next) - - This Root Certificate is also available in "truststore" form, ready - to be used by Java or other processes: - -- - - - - - - `truststoreONAP.p12 <http://aaf-onap-beijing-test.osaaf.org/truststoreONAP.p12>`__ - - This Truststore has ONLY the ONAP AAF\_RootCA in it. - - - `truststoreONAPall.jks <http://aaf-onap-beijing-test.osaaf.org/truststoreONAPall.jks>`__ - - This Truststore has the ONAP AAF\_RootCA in it PLUS all - the Public CA Certs that are in Java 1.8.131 (note: this is - in jks format, because the original JAVA truststore was in - jks format) - - Note: as of Java 8, pkcs12 format is recommended, rather than jks. - Java's "keytool" utility provides a conversion for .jks for Java 7 - and previous. - -Identity -'''''''' - - Certificates certify nothing if there is no identity or process to - verify the Identity. Typically, for a company, an HR department - will establish the formal organization, specifically, who reports to - whom. For ONAP, at time of Beijing, no such formalized "Org Chart" - existed, so we'll be building this up as we go along. - - Therefore, with each Certificate Request, we'll need identity - information as well, that will be entered into an ONAP Identity - file. Again, as a real company, this can be derived or accessed - real-time (if available) as an "Organization Plugin". Again, as - there appears to be no such central formal system in ONAP, though, - of course, Linux Foundation logins have some of this information for - ALL LF projects. Until ONAP declares such a system or decides how - we might integrate with LF for Identity and we have time to create - an Integration strategy, AAF will control this data. - - For each Identity, we'll need: - - People - - - | # 0 - unique ID (for Apps, just make sure it is unique, for - People, one might consider your LinuxFoundation ID) - | # 1 - full name (for App, name of the APP) - | # 2 - first name (for App, - | # 3 - last name - | # 4 - phone - | # 5 - official email - | # 6 - type - person - | # 7 - reports to: If you are working as part of a Project, list - the PTL of your Project. If you are PTL, just declare you are the - PTL - - Applications - - - | # 0 - unique ID - For ONAP Test, this will be the same a the App - Acronym. - | # 1 - full name of the App - | # 2 - App Acronym - | # 3 - App Description, or just "Application" - | # 5 - official email - a Distribution list for the Application, or - the Email of the Owner - | # 6 - type - application - | # 7 - reports to: give the Application Owner's Unique ID. Note, - this should also be the Owner in AAF Namespace - -Obtaining a Certificate -''''''''''''''''''''''' - - There are 3 types of Certificates available for AAF and ONAP - community through AAF. People, App Client-only, and App Service - (can be used for both Client and Service) - -Process (This process may fluctuate, or move to iTrack, so revisit this page for each certificate you request) - - -1. - - 1. - - 1. - - 1. Email the AAF Team - (jonathan.gathman@`att.com <http://att.com>`__, for now) - - 2. Put "REQUEST ONAP CERTIFICATE" in the Subject Line - - 3. If you have NOT established an Identity, see above, put the - Identity information in first - - 4. Then declare which of the three kinds of Certificates you - want. - - 1. **People** and **App Client-only** certificates will be - Manual - - 1. You will receive a reply email with instructions on - creating and signing a CSR, with a specific Subject. - - 2. Reply back with the CSR attached. DO NOT CHANGE the - Subject. - - 1. Subject is NOT NEGOTIABLE. If it does not match the - original Email, you will be rejected, and will - waste everyone's time. - - 3. You will receive back the certificate itself, and some - openssl instructions to build a .p12 file (or maybe a - ready-to-run Shell Script) - - 2. *App Service Certificate* is supported by AAF's Certman - - 1. However, this requires the establishment of Deployer - Identities, as no Certificate is deployed without - Authorization. - - 2. Therefore, for now, follow the "Manual" method, - described in 4.a, but include the Machine to be the - "cn=" - -People - - - People Certificates can be used for browsers, curl, etc. - - Automation and tracking of People Certificates will be proposed for - Casablanca. - - In the meantime, for testing purposes, you may request a certificate - from AAF team, see process. - -Application Client-only - - - Application Client-only certificates are not tied to a specific - machine. They function just like people, only it is expected that - they are used within "keystores" as identity when talking to AAF - enabled components. - - PLEASE USE your APP NAME IN CI/CD (OOM, etc) in your request. That - makes the most sense for identity. - - Automation and tracking of Application Certificates will be proposed - for Casablanca. - - In the meantime, for testing purposes, you may request a certificate - from AAF team, see process. - -Application Service - - - This kind of Certificate must have the Machine Name in the "CN=" - position. - - AAF supports Automated Certificate Deployment, but this has not been - integrated with OOM at this time (April 12, 2018). - -- - - - Please request Manual Certificate, but specify the Machine as - well. Machine should be a name, so you might need to provide - your Clients with instructions on adding to /etc/hosts until - ONAP address Name Services for ONAP Environments (i.e. DNS) - - **GUI** - - https://aaf-onap-beijing-test.osaaf.org - - Note: this link is actually to the AAF Locator, which redirects you - to an available GUI - - The GUI uses the ONAP AAF Certificate Authority (private). Before - you can use the Browser, you will need to - -- - - - Accept the `Root - Certificate <#AAFEnvironment-Beijing-RootCertificate>`__ - - - Obtain a Personal Certificate above - - - Add the Personal Certificate/Private key to your Browser. - Typically, this is done by having it packaged in a - P\ https://zoom.us/j/793296315 diff --git a/docs/sections/installation/Bootstrapping-AAF-Components.rst b/docs/sections/installation/Bootstrapping-AAF-Components.rst deleted file mode 100644 index 64987e4a..00000000 --- a/docs/sections/installation/Bootstrapping-AAF-Components.rst +++ /dev/null @@ -1,256 +0,0 @@ -.. contents:: - :depth: 3 -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -Summary -Essentials -Technologies required to run AAF -Optional Technologies for special cases -Data Definitions -AAF Data Definitions -ILM (Identity Lifecycle Management) -Initializing Default Implementation -Extract Sample Configuration -Certificate Authority -Creating your own Certificate Authority (if desired) -Create your Intermediate CAs -Use the Intermediate CA for creating Service/Identity Certs (can be utilized by Certman with LocalCA) -Copy initializations to Host Machine -Load Data and/or Meta-Data into Cassandra -Build Source -Run Java - -Summary -------- - -AAF Components are all Java(tm) HTTP/S based RESTful services, with the following exceptions: - - - AAF GUI component is an HTTP/S HTML5 generating component. It uses the same code base, but isn't strictly RESTful according to definition. - - AAF FS component is a FileServer, and is HTTP only (not TLS), so it can deliver publicly accessible artifacts without Authentication. - -Essentials -========== - -Technologies required to run AAF --------------------------------- - - - Java(tm). Version 8.121+ - - Oracle Java previous to Oracle Java SE 8 to version 8 Update 121 is vulnerable to "SWEET32" attack. - - 1369383 - CVE-2016-2183 SSL/TLS: Birthday attack against 64-bit block ciphers (SWEET32) - - - Cassandra, Version 2.1.14+ - - X509 Certificates (at minimum to support HTTP/S TLS transactions (TLS1.1 and TLS1.2 are default, but can be configured). - -Optional Technologies for special cases ---------------------------------------- - - - Build your own Certificate Authority for Bootstrapping and/or Certificate Manager component. - - openssl - - bash - -Data Definitions ----------------- - -AAF Data Definitions - - - AAF is Data Driven, and therefore, needs to have some structure around the Initial Data so that it can function. You will need to define: - -Your Organization: - - Example: Are you a company? Do you already have a well known internet URL? - - If so, you should set up AAF Namespaces with this in mind. Example: - - - for "Kumquat Industries, LTD", with internet presence "kumquats4you.com" (currently, a fictitious name), you would want all your AAF Namespaces to start with: - -"com.kumquats4you" -The examples all use - -"org.osaaf" - -However it is recommended that you change this once you figure out your organizations' structure. -Your AAF Root Namespace -This can be within your company namespace, i.e. - -"com.kumquats4you.aaf" - -but you might consider putting it under different root structure. -Again, the bootstrapping examples use: - -"org.osaaf.aaf" - -While creating these, recognize that -2nd position of the Namespace indicates company/organization -3rd+ position are applications within that company/organization - -"com.kumquats4you.dmaap" - -Following this "positional" structure is required for expected Authorization behavior. - - -ILM (Identity Lifecycle Management) -Neither Authentication nor Authorization make any sense outside the context of Identity within your Organization. - -Some organizations or companies will have their own ILM managers. - -If so you may write your own implementation of "Organization" -Ensure the ILM of choice can be access real-time, or consider exporting the data into File Based mechanism (see entry) -AAF comes with a "DefaultOrganization", which implements a file based localization of ILM in a simple text file - -Each line represents an identity in the organization, including essential contact information, and reporting structure -This file can be updated by bringing in the entire file via ftp or other file transfer protocol, HOWEVER -Provide a process that -Validates no corruption has occurred -Pulls the ENTIRE file down before moving into the place where AAF Components will see it. -Take advantage of UNIX File System behaviors, by MOVING the file into place (mv), rather than copying while AAF is Active -Note: This file-based methodology has been shown to be extremely effective for a 1 million+ Identity organization -TBA-how to add an entry - -TBA-what does "sponsorship mean" - -Initializing Default Implementation -This is recommended for learning/testing AAF. You can modify and save off this information for your Organizational use at your discretion. - -Extract Sample Configuration -On your Linux box (creating/setting permissions as required) - -mkdir -p /opt/app/osaaf - -cd /opt/app/osaaf - -# Download AAF_sample_config_v1.zip (TBA) - -jar -xvf AAF_sample_config_v1.zip - -Certificate Authority -You need to identify a SAFE AND SECURE machine when working with your own Certificate Authority. Realize that if a hacker gets the private keys of your CA or Intermediate CAs, you will be TOTALLY Compromised. - -For that reason, many large companies will isolate any machines dealing with Certificates, and that is the recommendation here as well... However, this page cannot explain what works best for you. JSCEP is an option if you have this setup already. - -If you choose to make your own CA, at the very least, once you create your private key for your Root Cert, and your Intermediate Certs, you might consider saving your Private Keys off line and removing from the exposed box. Again, this is YOUR responsibility, and must follow your policy. - - - -IMPORTANT! As you create Certificates for Identities, the Identities you use MUST be identities in your ILM. See /opt/app/aaf/osaaf/data/identities.dat - -Creating your own Certificate Authority (if desired) -1) Obtain all the Shell Scripts from the "conf/CA" directory which you can get the from the git repo. - -For this example, we'll put everything in /opt/app/osaaf - -mkdir /opt/app/osaaf/CA, if required - -$ cd /opt/app/osaaf/CA - -view README.txt for last minute info - -view and/or change "subject.aaf" for your needs. This format will be used on all generated certs from the CA. - -$ cat subject.aaf - -If you will be using PKCS11 option, review the "cfg.pkcs11" file as well - -$ cat cfg.pkcs11 - -$ bash newca.sh - -Obviously, save off your passphrase in an encrypted place... how you do this is your procedure - -At this point, your Root CA information has been created. If you want to start over, you may use "bash clean.sh" - -Create your Intermediate CAs -2) You do NOT sign regular Cert requests with your Root. You only sign with Intermediate CA. The "intermediate.sh" will create a NEW Intermediate CA Directory and copy appropriate Shell scripts over. Do this for as many Intermediate CAs as you need. - -$ bash newIntermediate.sh - -creates directories in order, intermediate_1, intermediate_2, etc. - -Use the Intermediate CA for creating Service/Identity Certs (can be utilized by Certman with LocalCA) -3) When creating a Manual Certificate, DO THIS from the Intermediate CA needed - -$ cd intermediate_1 - -4) Create initial Certificate for AAF - -IMPORTANT! As you create Certificates for Identities, the Identities you use MUST be identities in your ILM. See /opt/app/aaf/osaaf/data/identities.dat - -To create LOCALLY, meaning create the CSR, and submit immediately, do the following - -$ bash manual.sh <machine-name> -local - -FQI (Fully Qualified Identity): - -<identity from identities.dat>@<domain, ex: aaf.osaaf.org> - -To create Information suitable for Emailing, and signing the returned CSR - -$ bash manual.sh <machine-name> - -FQI (Fully Qualified Identity): - -<identity from identities.dat>@<domain, ex: aaf.osaaf.org> - -5) Create p12 file for AAF - -REMAIN in the intermediate directory... - -$ bash p12.sh <machine-name> - -Copy initializations to Host Machine -AAF is setup so it can run - -On the O/S, using Java -On Docker -On K8s -In each case, even for Docker/K8s, we utilize the File O/S for host specific information. This is because - -Many things are Host Specific -The Hostname required for TLS interactions -Cassandra specific information (when external/clustered) -Logging (if logging is done in container, it will be lost if container goes down) -To make things simpler, we are assuming that the file structure will be "/opt/app/osaaf". The code supports changing this, but documentation will wait until use cases arises for ONAP. - -Steps: - -1) Copy "osaaf.zip" to your Host Machine, where osaaf.zip is provided by AAF SME. // TODO POST SAMPLE HERE - -2) Copy your "p12" file generated by your CA (see above), and place in your "certs" directory - -3) SSH (or otherwise login) to your Docker/K8s Host Machine - -4) setup your directories (you might need to be root, then adjust what you need for O/S File Permissions - -$ mkdir /opt/app/osaaf - -$ cd /opt/app/osaaf - -$ mkdir cred logs - -$ unzip ~/osaaf.zip - -$ mv ~/<p12 file from CA above> cred - -$ - -Unzip the "osaaf.zip" so it goes into the /opt/app/osaaf directory (should have "etc", "data", "public" and "certs" directories) - -4) Modify "org.osaaf.props" to have - - - -Load Data and/or Meta-Data into Cassandra -Setting this initial Data can be done directly onto Cassadra using "cqlsh" using the following "cql" files: - -init<version>.cql (whatever is latest in the "zip" file) -osaaf.cql - This file contains initial Authorization Structures, see AAF Data Structures. - This is where you would modify your own initial Structures. -Build Source -(if not done already) - -Run Java -Note: If you have a Kubernets requirement (support), it is STILL RECOMMENDED you run AAF as stand-alone Java Components on your system, and work out any modifications required BEFORE trying to run in Kubernetes. - -TBA <java -Dcadi_prop_files=/opt/app/osaaf/etc/org.osaaf.locator.props -cp <path> File> - diff --git a/docs/sections/installation/Installation.rst b/docs/sections/installation/Installation.rst deleted file mode 100644 index 095739b4..00000000 --- a/docs/sections/installation/Installation.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
-
-Installation
-============
-This document will illustrates how to build and deploy all AAF components.
-
-Clone AAF Code:
-Build AAF with settings.xml:
-Build Docker Images:
-Modify the properties file:
-Mount the sample to /opt/app/osaaf:
-Run the docker containers:
-Clone AAF Code:
-bharath@bharath:~$ git clone https://git.onap.org/aaf/authz
-
-
-Build AAF with settings.xml:
----------------------------
-Copy the settings.xml from here and paste in ~/.m2/settings.xml
-
-Then run the following command
-
-.. code:: bash
-
- bharath@bharath:~$ cd authz && mvn clean install -DskipTests
-
-
-If the build is successful, then you can see a folder in "authz/auth" called "aaf_VERSION-SNAPSHOT" which contains all binaries of the components
-
-.. code:: bash
-
- bharath@bharath:~/authz/auth$ ls
-aaf_2.1.1-SNAPSHOT auth-cass auth-cmd auth-deforg auth-gui auth-locate auth-service pom.xml target
-auth-batch auth-certman auth-core auth-fs auth-hello auth-oauth docker sample
-
-Build Docker Images:
--------------------
-Now after building binaries, the next step is to build docker images for each aaf component.
-
-.. code:: bash
-
- bharath@bharath:~/authz/auth/docker$ chmod +x *.sh
- bharath@bharath:~/authz/auth/docker$ ./dbuild.sh
-
-The above command will build the following images:
-
-aaf_service
-aaf_oauth
-aaf_locate
-aaf_hello
-aaf_gui
-aaf_fs
-aaf_cm
-Modify the properties file:
-Modify the contents of the "authz/auth/docker/d.props
-
-.. code:: bash
-
- bharath@bharath:~/authz/auth/docker$ cat d.props
-
-# Variables for building Docker entities
-ORG=onap
-PROJECT=aaf
-DOCKER_REPOSITORY=nexus3.onap.org:10003
-OLD_VERSION=2.1.0-SNAPSHOT
-VERSION=2.1.1-SNAPSHOT
-CONF_ROOT_DIR=/opt/app/osaaf
-
-
-# Local Env info
-HOSTNAME="<HOSTNAME>"
-HOST_IP="<HOST_IP>"
-CASS_HOST="cass"
-
-Replace the <HOSTNAME> with your hostname and HOST_IP with your host IP.
-
-Add the following entry to your /etc/hosts file
-
-
-
-127.0.0.1 aaf.osaaf.org
-Mount the sample to /opt/app/osaaf:
-As you can see there is a parameter "CONF_ROOT_DIR" which is set to "/opt/app/osaaf". So we have to create a folder "/opt/app/osaaf" and copy the contents of authz/auth/sample to /opt/app/osaaf
-
-.. code:: bash
-
- bharath@bharath:~/authz/auth$ mkdir -p /opt/app/osaaf
- bharath@bharath:~/authz/auth$ cp -r sample/* /opt/app/osaaf/
-
-Run the docker containers:
---------------------------
-.. code:: bash
-
- bharath@bharath:~/authz/auth/docker$ ls
- dbash.sh dbuild.sh dclean.sh Dockerfile d.props dpush.sh drun.sh dstart.sh dstop.sh
- bharath@bharath:~/authz/auth/docker$ ./drun.sh
-
-
-
-
-
-
diff --git a/docs/sections/installation/client_vol.rst b/docs/sections/installation/client_vol.rst deleted file mode 100644 index 4d999e9f..00000000 --- a/docs/sections/installation/client_vol.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -======================================== -Setting up Certs and CADI Configurations -======================================== - -*Note: this document assumes UNIX Bash Shell. Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.* - ------------------- -Strategy ------------------- - -ONAP is deployed in Docker Containers or Kubernetes managed Docker Containers. Therefore, this instruction utilizes a Docker Container as a standalone Utility... (This means that this container will stop as soon as it is done with its work... it is not a long running daemon) - -Given that all ONAP entities are also in Docker Containers, they all can access Persistent Volumes. - -This tool creates all the Configurations, including Certificates, onto a declared Volume on the directories starting with "/opt/app/osaaf" - ------------------- -Prerequisites ------------------- - * Docker - * Note: it does NOT have to be the SAME Docker that AAF is deployed on... - | but it DOES have be accessible to the AAF Instance. - * For ONAP, this means - - * Windriver VPN - * include "10.12.6.214 aaf-onap-test.osaaf.org" in your /etc/hosts or DNS - ------------------------ -Obtain the Agent Script ------------------------ -Choose the directory you wish to start in... - -If you don't want to clone all of AAF, just get the "agent.sh" from a Browser: - - https://gerrit.onap.org/r/gitweb?p=aaf/authz.git;a=blob_plain;f=auth/docker/agent.sh;hb=HEAD - - rename file "auth-docker-agent.sh" to "agent.sh" (named because of subdirectory in which it is found) - -Note: curl/wget returns an html, instead of text. This cannot be used! - | You have to mv, and rename it to "agent.sh", but avoids full clone... - -------------------------- -Run Script -------------------------- - -In your chosen directory :: - - $ bash agent.sh - -The Agent will look for "aaf.props", and if it doesn't exist, or is missing information, it will ask for it. - -This file is available to reuse for multiple calls. More importantly, you should use it as a template for auto-configuration. (In ONAP, these are HEAT templates and OOM Helm Charts) - ---------------------- -'aaf.prop' Properties ---------------------- - -=================== =============== ============ -Query Tag Description -=================== =============== ============ -CADI Version VERSION Defaults to CADI version of this -AAF's FQDN AAF_FQDN PUBLIC Name for AAF. For ONAP Test, it is 'aaf-onap-test.osaaf.org' -Deployer's FQI DEPLOY_FQI In a REAL system, this would be a person or process. For ONAP Testing, the id is deployer@people.osaaf.org, password (see Dynamic Properties) is 'demo123456!' -App's Root FQDN APP_FQDN This will show up in the Cert Subject, and should be the name given by Docker. i.e. clamp.onap -App's FQI APP_FQI Fully Qualified ID given by Organization and with AAF NS/domain. ex: clamp@clamp.onap.org -App's Volume VOLUME Volume to put the data, see above. ex: clamp_aaf -DRIVER DRIVER Docker Volume type... See Docker Volume documentation -LATITUDE of Node LATITUDE Global latitude coordinate of Node (best guess in Kubernetes) -LONGITUDE of Node LONGITUDE Global longitude coordinate of Node (best guess in Kubernetes) -=================== =============== ============ - ---------------------- -Dynamic Properties ---------------------- - -These Properties do not automatically save in 'aaf.props', because... - - | Passwords should not be stored clear text, with the possible exception of constant Environment Recreation, where it is impractical. - | The IP of the AAF's FQDN is looked up, if possible. It can be set, however, when lookup isn't available. - -=================== =============== ============ -Query Tag Description -=================== =============== ============ -Deployer's Password DEPLOY_PASSWORD Password for the Deployer. Avoids storing, except where impossible otherwise. -IP of <AAF_FQDN> AAF_FQDN_IP IP for Name of AAF FQDN, if not available by normal lookup means -=================== =============== ============ - -------------------------------- -Typical ONAP Entity Info in AAF -------------------------------- -*This is not intended to be a comprehensive list, but a short list of main entities* - -============================= =========================== ======================= ============================================== -ONAP Namespaces APP FQI APP FQDN OOM APP FQDN HEAT -============================= =========================== ======================= ============================================== -org.osaaf.aaf aaf@aaf.osaaf.org aaf.onap aaf.api.simpledemo.onap.org -org.onap.aaf-sms aaf-sms@aaf-sms.onap.org aaf-sms.onap aaf-sms.api.simpledemo.onap.org -org.onap.aai aai@aai.onap.org aai.onap aai.api.simpledemo.onap.org -org.onap.appc appc@appc.onap.org appc.onap appc.api.simpledemo.onap.org -org.onap.clamp clamp@clamp.onap.org clamp.onap clamp.api.simpledemo.onap.org -org.onap.dcae dcae@dcae.onap.org dcae.onap dcae.api.simpledemo.onap.org -org.onap.dmaap dmaap@dmaap.onap.org dmaap.onap dmaap.api.simpledemo.onap.org -org.onap.dmaap-bc dmaap-bc@dmaap-bc.onap.org dmaap-bc.onap dmaap-bc.api.simpledemo.onap.org -org.onap.dmaap-dr dmaap-bc@dmaap-dr.onap.org dmaap-dr.onap dmaap-dr.api.simpledemo.onap.org -org.onap.dmaap-mr dmaap-mr@dmaap-mr.onap.org dmaap-mr.onap dmaap-mr.api.simpledemo.onap.org -org.onap.oof oof@oof.onap.org oof.onap oof.api.simpledemo.onap.org -org.onap.policy policy@policy.onap.org policy.onap policy.api.simpledemo.onap.org -org.onap.pomba pomba@pomba.onap.org pomba.onap pomba.api.simpledemo.onap.org -org.onap.portal portal@portal.onap.org portal.onap portal.api.simpledemo.onap.org -org.onap.sdc sdc@sdc.onap.org sdc.onap sdc.api.simpledemo.onap.org -org.onap.sdnc sdnc@sdnc.onap.org sdnc.onap sdnc.api.simpledemo.onap.org -org.onap.so so@so.onap.org so.onap so.api.simpledemo.onap.org -org.onap.vfc vfc@vfc.onap.org vfc.onap vfc.api.simpledemo.onap.org -org.onap.vid vid@vid.onap.org vid.onap vid.api.simpledemo.onap.org -============================= =========================== ======================= ============================================== - -*Note 1: FQDNs are set in AAF's Credential Artifact data, accessible in "Cred Details" from Namespace Page* - -*Note 2: Also, AAF itself is different, as it is not an ONAP only component... It is also expected to be used outside of ONAP.* - -If something goes wrong, and Certificate is not created, you can adjust the data, remove the data from the Container's /opt/app/osaaf/local dir, and it will generate again. :: - - root@77777:/opt/app/osaaf/local# rm * - root@77777:/opt/app/osaaf/local# exit - $ bash agent.sh bash - -------------- -Informational -------------- - -There are two sets of Credentials at play here. The ability to create the Certificate belongs to one of - - * The person responsible for the ID in the Organization - * A delegated deployer - -It is expected in large organizations that Individual Employees are given the responsibility of an ID for an APP they are responsible for. - - In ONAP test, to simplify create/tear-down environment... - | The **Owner** is always "mmanager@people.osaaf.org". - | The **Sponsor** is always "aaf_admin@people.osaaf.org". - -In a large org, there are probably many Operations teams to support many different apps. - - In ONAP test, - The **Deployer** is always set to "deployer@people.osaaf.org" for all Apps. - - diff --git a/docs/sections/installation/install_from_source.rst b/docs/sections/installation/install_from_source.rst deleted file mode 100644 index dd7f71e0..00000000 --- a/docs/sections/installation/install_from_source.rst +++ /dev/null @@ -1,219 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -============================ -Installing from Source Code -============================ - -*Note: this document assumes UNIX Bash Shell. Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.* - ------------------- -Modes ------------------- - -AAF can be run in various ways - * Standalone (on your O/S) - * Docker (localized) - * Kubernetes - * ONAP Styles - * HEAT (Docker Container Based Initilization) - * OOM (a Helm Chart based Kubernetes Environment) - ------------------- -Prerequisites ------------------- - -You need the following tools to build and run AAF - * git - * maven - * Java (JDK 1.8+, openjdk is fine) - * Cassandra - * a separate installation is fine - * these instructions will start off with a Docker based Cassandra instance - * Machine - one of the following - * Standalone Java Processes - no additional running environments necessary - * docker - typically available via packages for O/S - * kubernetes - ditto - - ------------------- -Build from Source ------------------- -Choose the directory you wish to start in... This process will create an "authz" subdirectory:: - - $ mkdir -p ~/src - $ cd ~/src - -Use 'git' to 'clone' the master code:: - - $ git clone https://gerrit.onap.org/r/aaf/authz - -Change to that directory:: - - $ cd authz - -Use Maven to build:: - - << TODO, get ONAP Settings.xml>> - $ mvn install - -.. ----------------- -.. Standalone -.. ----------------- - ------------------ -Docker Mode ------------------ - -After you have successfully run maven, you will need a Cassandra. If you don't have one, here are instructions for a Docker Standalone Cassandra. For a *serious* endeavor, you need a multi-node Cassandra. - -From "authz":: - - $ cd auth/auth-cass/src/main/cql - $ vi config.dat - -=================== -Existing Cassandra -=================== - -AAF Casablanca has added a table. If you have an existing AAF Cassandra, do the following:: - - ### If Container Cassandra, add these steps, otherwise, skip - $ docker container cp init2_1.cql aaf_cass:/tmp - $ docker exec -it aaf_cass bash - (docker) $ cd /tmp - ### - $ cqlsh -f 'init2_1.cql' - -===================== -New Docker Cassandra -===================== - -Assuming you are in your src/authz directory:: - - $ cd auth/auth-cass/docker - $ bash dinstall.sh - ---------------------- -AAF Itself ---------------------- - -Assuming you are in your src/authz directory:: - - $ cd auth/docker - ### If you have not done so before (don't overwrite your work!) - $ cp d.props.init d.props - -You will need to edit and fill out the information in your d.props file. Here is info to help - -**Local Env info** - These are used to load the /etc/hosts file in the Containers, so AAF is available internally and externally - - =============== ============= - Variable Explanation - =============== ============= - HOSTNAME This must be the EXTERNAL FQDN of your host. Must be in DNS or /etc/hosts - HOST_IP This must be the EXTERNAL IP of your host. Must be accessible from "anywhere" - CASS_HOST If Docker Cass, this is the INTERNAL FQDN/IP. If external Cass, then DNS|/etc/hosts entry - aaf_env This shows up in GUI and certs, to differentiate environments - aaf_register_as As pre-set, it is the same external hostname. - cadi_latitude Use "https://bing.com/maps", if needed, to locate your current Global Coords - cadi_longitude ditto - =============== ============= - -============================== -"Bleeding Edge" Source install -============================== - -AAF can be built, and local Docker Images built with the following:: - - $ bash dbuild.sh - -Otherwise, just let it pull from Nexus - -============================== -Configure AAF Volume -============================== - -AAF uses a Persistent Volume to store data longer term, such as CADI configs, Organization info, etc, so that data is not lost when changing out a container. - -This volume is created automatically, as necessary, and linked into the container when starting. :: - - ## Be sure to have your 'd.props' file filled out before running. - $ bash aaf.sh - -============================== -Bootstrapping with Keystores -============================== - -Start the container in bash mode, so it stays up. :: - - $ bash aaf.sh bash - id@77777: - -In another shell, find out your Container name. :: - - $ docker container ls | grep aaf_config - -CD to directory with CA p12 files - - * org.osaaf.aaf.p12 - * org.osaaf.aaf.signer.p12 (if using Certman to sign certificates) - -Copy keystores for this AAF Env :: - - $ docker container cp -L org.osaaf.aaf.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local - ### IF using local CA Signer - $ docker container cp -L org.osaaf.aaf.signer.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local - -In Agent Window :: - - id@77777: agent encrypt cadi_keystore_password - ### IF using local CA Signer - id@77777: agent encrypt cm_ca.local - -Check to make sure all passwords are set :: - - id@77777: grep "enc:" *.props - -When good, exit from Container Shell and run AAF :: - - id@77777: exit - $ bash drun.sh - -Check the Container logs for correct Keystore passwords, other issues :: - - $ docker container logs aaf_<service> - -Watch logs :: - - $ bash aaf.sh taillog - -Notes: - -You can find an ONAP Root certificate, and pre-built trustores for ONAP Test systems at: - | authz/auth/sample/public/AAF_RootCA.cert - | authz/auth/sample/public/truststoreONAPall.jks - -Good Tests to run :: - - ## From "docker" dir - ## - ## assumes you have DNS or /etc/hosts entry for aaf-onap-test.osaaf.org - ## - $ curl --cacert ../sample/public/AAF_RootCA.cer -u demo@people.osaaf.org:demo123456! https://aaf-onap-test.osaaf.org:8100/authz/perms/user/demo@people.osaaf.org - $ openssl s_client -connect aaf-onap-test.osaaf.org:8100 - - - - - - - - - - - - - - diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst index 0672b1db..5daa2b1c 100644 --- a/docs/sections/logging.rst +++ b/docs/sections/logging.rst @@ -19,6 +19,19 @@ Where to Access Information --------------------------- AAF uses log4j framework to generate logs and all the logs are stored in a persistent volume. +* For Standalone O/S, logs are placed on the machine. cd as follows +* For any AAF Container or Kubernetes, get a bash prompt into that container. Then cd as follows. + +.. code:: bash + + $ cd /opt/app/osaaf/logs + +For convenience, there is a tool to easily tail all component's transactions realtime, from this directory: + +.. code:: bash + + $ bash taillog + Error / Warning Messages ------------------------ Following are the error codes |