docs/sections/configuration/AAF_4.0_config.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4
   5 ============================
   6 Configuring
   7 ============================
   8 *Note: this document assumes UNIX Bash Shell.  Being Java, AAF works in Windows, but you will have to create your own script/instruction conversions.*
   9
  10 --------------------
  11 Configure AAF Volume
  12 --------------------
  13
  14 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.
  15
  16 This volume is created automatically, as necessary, and linked into the container when starting. ::
  17
  18   ## Be sure to have your 'd.props' file filled out before running.
  19   $ bash aaf.sh
  20
  21 ----------------------------
  22 Bootstrapping with Keystores
  23 ----------------------------
  24
  25 Start the container in bash mode, so it stays up. ::
  26
  27   $ bash aaf.sh bash
  28   id@77777:
  29
  30 In another shell, find out your Container name. ::
  31
  32   $ docker container ls | grep aaf_config
  33
  34 CD to directory with CA p12 files
  35
  36   * org.osaaf.aaf.p12
  37   * org.osaaf.aaf.signer.p12    (if using Certman to sign certificates)
  38
  39 Copy keystores for this AAF Env ::
  40
  41   $ docker container cp -L org.osaaf.aaf.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local
  42   ### IF using local CA Signer
  43   $ docker container cp -L org.osaaf.aaf.signer.p12 aaf_agent_<Your ID>:/opt/app/osaaf/local
  44
  45 In Agent Window ::
  46
  47   id@77777: agent encrypt cadi_keystore_password
  48   ### IF using local CA Signer
  49   id@77777: agent encrypt cm_ca.local
  50
  51 Check to make sure all passwords are set ::
  52
  53   id@77777: grep "enc:" *.props
  54
  55 When good, exit from Container Shell and run AAF ::
  56
  57   id@77777: exit
  58   $ bash drun.sh
  59
  60 Check the Container logs for correct Keystore passwords, other issues ::
  61
  62   $ docker container logs aaf_<service>
  63
  64 Watch logs ::
  65
  66   $ bash aaf.sh taillog
  67
  68 Notes:
  69
  70 You can find an ONAP Root certificate, and pre-built trustores  for ONAP Test systems at:
  71   | authz/auth/sample/public/AAF_RootCA.cert
  72   | authz/auth/sample/public/truststoreONAPall.jks
  73
  74 Good Tests to run ::
  75
  76   ## From "docker" dir
  77   ##
  78   ## assumes you have DNS or /etc/hosts entry for aaf-onap-test.osaaf.org
  79   ##
  80   $ 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
  81   $ openssl s_client -connect aaf-onap-test.osaaf.org:8100
  82
  83 -------------------------------
  84 Working with CADI Properties
  85 -------------------------------
  86
  87 .. code:: bash
  88
  89    cadi.properties Template
  90   # This is a normal Java Properties File
  91   # Comments are with Pound Signs at beginning of lines,
  92   # and multi-line expression of properties can be obtained by backslash at end of line
  93   #hostname=
  94
  95   cadi_loglevel=WARN
  96   cadi_keyfile=conf/keyfile
  97
  98
  99   # Configure AAF
 100   aaf_url=http://172.18.0.2:8101
 101   #if you are running aaf service from a docker image you have to use aaf service IP and port number
 102   aaf_id=<yourAPPID>@onap.org
 103   aaf_password=enc:<encrypt>
 104
 105   aaf_dme_timeout=5000
 106   # Note, User Expires for not Unit Test should be something like 900000 (15 mins) default is 10 mins
 107   # 15 seconds is so that Unit Tests don't delay compiles, etc
 108   aaf_user_expires=15000
 109   # High count... Rough top number of objects held in Cache per cycle.  If high is reached, more are
 110   # recycled next time.  Depending on Memory usage, 2000 is probably decent.  1000 is default
 111   aaf_high_count=100
 112
 113
 114 How to create CADI Keyfile & Encrypt Password
 115 ---------------------------------------------
 116
 117 Password Encryption
 118 -------------------
 119 CADI provides a method to encrypt data so that Passwords and other sensitive data can be stored safely.
 120
 121 Keygen (Generate local Symmetrical Key)
 122 A Keyfile is created by Cadi Utility.
 123
 124 .. code:: bash
 125
 126   java -jar cadi-core-<version>.jar keygen <keyfile>
 127   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:
 128
 129 .. code:: bash
 130
 131   java -jar cadi-core-<version>.jar keygen keyfile
 132   chmod 400 keyfile
 133   chown tomcat:tomcat keyfile
 134
 135 Digest - Encrypt a Password
 136 ---------------------------
 137 The password is obtained by using the Cadi digest Utility (contained in the cadi-core-<version>.jar).
 138
 139 .. code:: bash
 140
 141   java -jar cadi-core-<version>.jar digest <your_password> <keyfile>
 142    •  "<keyfile>" is created by Cadi Utility, #keygen
 143    •  Understand that if you change the keyfile, then you need to rerun "digest" on passwords used in the users/groups definitions.
 144    •  Note: You cannot mix versions of cadi; the version used to digest your password must be the same version used at runtime.
 145
 146 CADI PROPERTIES
 147    CADI properties, typically named "cadi.properties", must have passwords encrypted.
 148       1.        Take the results of the "Digest" command and prepend "enc:"
 149       2.        Use this as the value of your property
 150
 151 Example:   aaf_password=enc:fMKMBfKHlRWL68cxD5XSIWNKRNYi5dih2LEHRFMIsut
 152