--- /dev/null
+.. 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.
+
+============================
+Configuring
+============================
+*Note: this document assumes UNIX Bash Shell. Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.*
+
+--------------------
+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
+
+-------------------------------
+Working with CADI Properties
+-------------------------------
+
+.. 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
+
.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
========================================
-Setting up Certs and CADI Configurations
+Automated Configuration and Certificates
========================================
*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)
The **Deployer** is always set to "deployer@people.osaaf.org" for all Apps.
+
+
+
+
+
+
+
+
+
+
* `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.
+++ /dev/null
-.. 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
-
--- /dev/null
+.. 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.
+
+=====================
+Prerequisites for AAF
+=====================
+
+To *run* AAF, you need the following:
+ * Java 8+, openjdk is fine (see Version below)
+ * Cassandra
+ * a separate installation is fine
+ * Docker based AAF Envs offer a single instance Cassandra for convenience. Single Instance Cassandra is **NOT** recommended for real AAF systems.
+ * Machine - one of the following
+ * Standalone Java Processes - Bare Metal or VMs. No additional running environments necessary
+ * docker - typically available via packages for O/S
+ * kubernetes - various installs available
+
+To *build* AAF, you additionally need:
+ * Java 8+, openjdk is fine (see Version below)
+ * git
+ * maven
+ * for Container Based, you'll need Docker to build as well
+ * Note: 'minikube' works well to provide both Docker and Kubernetes Single Instance installations.
+
+
+---------------------------
+Current Technology Versions
+---------------------------
+
+ - 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 3.11+
+
+ - X509 Certificates (at minimum to support HTTP/S TLS transactions (TLS1.1 and TLS1.2 are default, but can be configured).
+
--- /dev/null
+.. 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 Environments
+=========================
+
+AAF can run globally, with high resilience in several different *kinds* of environments. AAF runs globally, because, thanks to the Locator Component, you can place any network accessible element anywhere in the world, and find the best component entry FQDN and Port based on global Position (Latitude/Longitude).
+
+Env Types
+---------
+ 1. Standalone O/S - AAF runs as Standalone Java Processes on bare metal or VMs.
+ 2. Docker containers - AAF runs in containers, controlled by standard Docker Commands.
+ 3. ONAP CSIT (CSIT env is an isolated Testing Environment, run within Jenkins for validation)
+ 4. ONAP HEAT (Deprecated after Beijing)
+ 5. Helm (Kubernetes) - this is a Standalone Helm method, suitable for external use of AAF as a Kubernetes Installation
+ 6. ONAP OOM - AAF deployed as ONAP OOM component. In this mode, AAF starts first, then provides configurations, certificates, etc to ONAP Components.
+
+Cassandra
+---------
+
+A key element of AAF's Global reach and resilience, is that it uses the Cassandra DB. This automatically updates its data on a global scale, which allows AAF to have consistent data across geography.
+
+AAF works best if you create a Network Topology based on "Datacenters" which you place in key geographies for your Entity. You should organize your Cassanda Instances to be colocated with one or more AAF Service/Locator/Oauth instances for optimal performance. Futher, there should always be 3 or more Cassandra instances in each DataCenter (don't forget your "Seed Node" setup, see Cassandra Documentation).
+
+These kinds of setups are achievable fairly easily when using the Standalone O/S model, as it give you maximum control over what is deployed where.
+
+Container based Cassandras, and especially Kubernetes are more of a challenge as to work well, you need to dictate Seed Nodes, etc, but Kubernetes controls which machines any given Cassandra instance resides.
+
+These issues must be solved for best AAF results within your own installations. For that reason, AAF can be configured to simply "point to" any Cassandra Instance scheme you setup.
+
+However, for testing purposes, requiring a Cassandra Setup beforehand is daunting and problematic, especially for automated testing scenarios, which are used extensively within the ONAP Community.
+
+For this reason, all of the Docker based Installations (#2-#6) come with a preconfigured with a single instance Cassandra, ready to run with ONAP data as soon as started.
+
--- /dev/null
+.. 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.
+
+============================
+Building
+============================
+*Note: this document assumes UNIX Bash Shell. Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.*
+
+---------------------
+Building 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 *ONCE* :
+
+### 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
+
.. 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
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.
+| 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)
+++ /dev/null
-.. 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
+++ /dev/null
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
-.. http://creativecommons.org/licenses/by/4.0\r
-.. Copyright © 2017 AT&T Intellectual Property. All rights reserved.\r
-\r
-Installation\r
-============\r
-This document will illustrates how to build and deploy all AAF components.\r
-\r
-Clone AAF Code:\r
-Build AAF with settings.xml:\r
-Build Docker Images:\r
-Modify the properties file:\r
-Mount the sample to /opt/app/osaaf:\r
-Run the docker containers:\r
-Clone AAF Code:\r
-bharath@bharath:~$ git clone https://git.onap.org/aaf/authz\r
-\r
-\r
-Build AAF with settings.xml:\r
----------------------------\r
-Copy the settings.xml from here and paste in ~/.m2/settings.xml\r
-\r
-Then run the following command\r
-\r
-.. code:: bash\r
-\r
- bharath@bharath:~$ cd authz && mvn clean install -DskipTests\r
-\r
-\r
-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\r
-\r
-.. code:: bash\r
-\r
- bharath@bharath:~/authz/auth$ ls\r
-aaf_2.1.1-SNAPSHOT auth-cass auth-cmd auth-deforg auth-gui auth-locate auth-service pom.xml target\r
-auth-batch auth-certman auth-core auth-fs auth-hello auth-oauth docker sample\r
-\r
-Build Docker Images:\r
--------------------\r
-Now after building binaries, the next step is to build docker images for each aaf component.\r
-\r
-.. code:: bash\r
-\r
- bharath@bharath:~/authz/auth/docker$ chmod +x *.sh\r
- bharath@bharath:~/authz/auth/docker$ ./dbuild.sh\r
- \r
-The above command will build the following images:\r
-\r
-aaf_service\r
-aaf_oauth\r
-aaf_locate\r
-aaf_hello\r
-aaf_gui\r
-aaf_fs\r
-aaf_cm\r
-Modify the properties file:\r
-Modify the contents of the "authz/auth/docker/d.props\r
-\r
-.. code:: bash\r
-\r
- bharath@bharath:~/authz/auth/docker$ cat d.props\r
- \r
-# Variables for building Docker entities\r
-ORG=onap\r
-PROJECT=aaf\r
-DOCKER_REPOSITORY=nexus3.onap.org:10003\r
-OLD_VERSION=2.1.0-SNAPSHOT\r
-VERSION=2.1.1-SNAPSHOT\r
-CONF_ROOT_DIR=/opt/app/osaaf\r
-\r
-\r
-# Local Env info\r
-HOSTNAME="<HOSTNAME>"\r
-HOST_IP="<HOST_IP>"\r
-CASS_HOST="cass"\r
-\r
-Replace the <HOSTNAME> with your hostname and HOST_IP with your host IP.\r
-\r
-Add the following entry to your /etc/hosts file\r
-\r
-\r
-\r
-127.0.0.1 aaf.osaaf.org\r
-Mount the sample to /opt/app/osaaf:\r
-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\r
-\r
-.. code:: bash\r
-\r
- bharath@bharath:~/authz/auth$ mkdir -p /opt/app/osaaf\r
- bharath@bharath:~/authz/auth$ cp -r sample/* /opt/app/osaaf/\r
-\r
-Run the docker containers:\r
---------------------------\r
-.. code:: bash\r
-\r
- bharath@bharath:~/authz/auth/docker$ ls\r
- dbash.sh dbuild.sh dclean.sh Dockerfile d.props dpush.sh drun.sh dstart.sh dstop.sh\r
- bharath@bharath:~/authz/auth/docker$ ./drun.sh\r
-\r
-\r
-\r
-\r
-\r
-\r
+++ /dev/null
-.. 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
-
-
-
-
-
-
-
-
-
-
-
-
-
-
---------------------------
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
Code Review / aaf / authz.git / commitdiff