| <!-- |
| ~ Copyright © 2009-2013, JoshuaTree. All Rights Reserved. |
| --> |
| <body> |
| <img src="./images/fortresscommunitylogov3.jpg" /> |
| <br> |
| <p> |
| These instructions are intended for new users who want to quickly learn how to install and test JoshuaTree Fortress and ApacheDS IAM software. |
| <br><br>Follow the steps and |
| <ul> |
| <li>ApacheDS will be installed, configured, loaded, and ready to use by <em>Section IV</em>.</li> |
| <li>EnMasse Policy Server demo starts in <em>Section IX</em></li> |
| <li>Commander Web Admin demo starts in <em>Section X</em></li> |
| </ul> |
| </p> |
| <hr> |
| <h2>System Prerequisites</h2> |
| <p> |
| <ul> |
| <li>Internet access to retrieve binary dependencies from online Maven repo.</li> |
| <li>Java SDK Version 7 or beyond installed to target environment</li> |
| <li>Redhat or Ubuntu server machine (for window environments use <em>README-QUICKSTART-WINDOWS.html</em>)</li> |
| <li>1GB RAM</li> |
| <li>20GB HD</li> |
| <li>ApacheDS Pre-installed</li> |
| </ul> |
| </p> |
| |
| <b>NOTE:</b> The Fortress build.xml may run without connection to Internet iff: |
| <ul> |
| <li>The binary dependencies have previously been downloaded to FORTRESS_HOME/lib folder</li> |
| <li>Local mode has been enabled on target machine. Local mode can be enabled by adding this property to build.properties: local.mode=true</li> |
| </ul> |
| <hr> |
| <h2>Guidelines and Tips for first-time users</h2> |
| <ul> |
| <li>In the document that follows, when you read <em>[version]</em> or <em>[platform]</em> substitute with current package info. For example - if the downloaded package version is 1.0.0 and platform is 'Debian Silver i386', the instructions show fortressBuilder-<em>[platform]</em>-<em>[version]</em>.jar your file name would be fortressBuilder-Debian-Silver-i386-1.0.0.zip</li> |
| <br> |
| <li>Is your target machine windows? Go to <em>README-QUICKSTART-WINDOWS</em></li> |
| <br> |
| <li>The source code for this project is located in <em>FORTRESS_HOME/src</em> folder.</li> |
| </ul> |
| |
| <ol type="I"> |
| <hr> |
| <li> |
| <h3>Instructions to extract and configure Fortress Builder Package to Target System</h3> |
| <ol type="A"> |
| <li>Copy fortressBuilder-[platform]-[version].zip to hard drive on target server env.</li> |
| <br> |
| <li>Extract the zip. The location for archive can vary according to requirements. The location of package will be referred to as <em>FORTRESS_HOME</em> later on.</li> |
| <br> |
| <li>Enable permission for the binaries to execute. From FORTRESS_HOME root folder, enter the following command from a system prompt: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">chmod a+x -Rf * |
| </p></pre> |
| <img src="./images/Screenshot1-chmod.png" /> |
| </li> |
| |
| <li>Edit file named 'build.properties' and insert LDAP configuration parameters: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;"> |
| ldap.server.type=apacheds |
| |
| # These parameters point fortress to LDAP host: |
| ldap.host=localhost |
| ldap.port=10389 |
| |
| # These are used to construct suffix for DIT, i.e. dc=example,dc=com. |
| suffix.name=example |
| suffix.dc=com |
| |
| # These are the connection parameters used for LDAP service account: |
| root.dn=uid=admin,ou=system |
| |
| # Used to load OpenLDAP admin root password in slapd.conf and was encrypted using 'slappasswd' command: |
| # This ApacheDS admin root password's value is 'secret', is bound for fortress.properties and was encrypted using 'encrypt' target in build.xml: |
| cfg.root.pw=W7T0G9hylKZQ4K+DF8gfgA== |
| |
| # If encryption of LDAP &/or HTTP service account passwords (e.g. cfg.root.pw, cfg.log.root.pw and http.pw params) is required, this field must be set. |
| # If encryption of service accounts not needed, leave this value blank, and set the password values for cfg.root.pw, cfg.log.root.pw and http.pw to be their clear text value. |
| # Use any arbitrary value here but must be same as key used to encrypt. |
| crypto.prop=abcd12345 |
| |
| </p></pre> |
| </li> |
| |
| </ol> |
| </li> |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to run the Fortress Ant Build</h3> |
| <ol type="A"> |
| <li> |
| From FORTRESS_HOME root folder, edit the b.sh script to point to java home: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">export JAVA_HOME=/opt/jdk1.7.0_10 |
| </p></pre> |
| </li> |
| <img src="./images/Screenshot3-edit-javahome.png" /><br><br> |
| <li> |
| Run the distribution target: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh dist |
| </p></pre> |
| <img src="./images/Screenshot4-ant-dist.png" /><br> |
| <br>Note: The b.sh batch file referred to here uses Ant package that is local to Fortress quickstart package. |
| </li> |
| <br> |
| <li> |
| Verify it ran correctly according to Ant: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">BUILD SUCCESSFUL |
| </p></pre> |
| <img src="./images/Screenshot4-ant-success-dist.png" /><br><br> |
| </li> |
| </ol> |
| You may now view the project binaries and documentation located under FORTRESS_HOME/dist. |
| <br><br><img src="./images/Screenshot5-dist-listing.png" /><br><br> |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to configure ApacheDS and load with seed data</h3> |
| <strong><p style="color:blue;font-size:14px;">Important: This target reloads the ApacheDS configuration and data. |
| </p> |
| |
| </strong> |
| <ol type="A"> |
| <br> |
| <li> |
| Import Fortress ApacheDS schema into ApacheDS server using preferred ldif import tool. Fortress ApacheDS schema located here: FORTRESS_HOME/ldap/schema/apacheds-fortress.ldif |
| |
| <br><br>Screenshot of Apache Directory Studio import of Fortress schema file into ApacheDS: |
| </li> |
| <img src="./images/Screenshot-Studio-Schema-Import.png" /><br><br> |
| |
| <li> |
| The fortress 'init-apacheds' uses LDAPv3 to perform initial operations. |
| <br>edit build.properties, ensure the following line has been commented out: |
| <br><br><img src="./images/Screenshot43-edit-disable-rest.png" /><br><br> |
| Note: The default for this setting is 'false' or disabled.<br><br> |
| </li> |
| |
| <li> |
| From FORTRESS_HOME root folder, enter the following command from a system prompt: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh init-apacheds |
| </p></pre> |
| </li> |
| <li> |
| Verify it ran correctly according to Ant. |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">BUILD SUCCESSFUL |
| </p></pre> |
| <img src="./images/Screenshot7-init-slapd-success.png" /><br><br> |
| <li> |
| After above step completes, Symas ApacheDS will be installed, configured and loaded with fortress bootstrap config. This |
| step also runs provisioning scripts which may be tailored according to requirements. Check out the xml load scripts |
| in FORTRESS_HOME/ldap/setup folder. |
| <br><br> |
| </li> |
| |
| <li> |
| Point your preferred LDAP browser, ours is <a href="http://directory.apache.org/studio/">Apache Directory Studio</a>, to the installed directory. |
| |
| The configuration parameters you'll need to browse can be found in the generated 'slapd.conf' file. |
| <br><br> |
| To view data stored in default database: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">suffix "dc=example,dc=com" |
| rootdn "uid=admin,ou=system" |
| rootpw "secret"</p></pre> |
| The root pw will be encrypted before stored in slapd.conf |
| |
| <br><br><img src="./images/Screenshot8-ldap-browser.png" /><br><br> |
| |
| </li> |
| </ol> |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to regression test Fortress and ApacheDS on target machine (optional)</h3> |
| <ol type="A"> |
| <li>From FORTRESS_HOME root folder, enter the following command from a system prompt: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh test-full |
| </p></pre> |
| </li> |
| <img src="./images/Screenshot10-ant-test-init.png" /><br><br> |
| Note: The Fortress regression tests will run for around 3 minutes.<br><br> |
| <li>Verify these tests ran with no ERRORS. |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">BUILD SUCCESSFUL |
| </p></pre> |
| </li> |
| <img src="./images/Screenshot11-ant-test-success.png" /><br><br> |
| <li> |
| To re-run these tests: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh test-full |
| </p></pre> |
| </li> |
| </ol> |
| Note 1: WARNING messages in test output are good as these are negative tests in action: |
| <br><img src="./images/Screenshot12-junit-warn.png" /> |
| <br><br>Note 2: If you made it this far without junit or ant ERRORS, the Fortress and ApacheDS IAM system are certified to run on your machine. |
| <br><br>Note 3: These tests load tens of thousands of records into your newly installed directory. |
| The 'init-apacheds' and 'test-full' targets may be re-run as often as necessary. After regressions testing has completed, you may run the 'init-apacheds' target to remove all test data from the directory. |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to run the Fortress Command Line Interpreter (CLI) utility (optional)</h3> |
| This command line tool provides an interactive session with the user based on a simple command line syntax.<br><br> |
| <ol type="A"> |
| <li> |
| To start the CLI, enter:<pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh cli |
| </p></pre> |
| <img src="./images/Screenshot13-ant-cli.png" /><br><br> |
| Which will bring up the command interpreter: |
| <br><img src="./images/Screenshot14-cli.png" /><br><br> |
| </li> |
| <li> |
| enter the command: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">review fuser -u demo |
| </p></pre> |
| <img src="./images/Screenshot15-cli-review.png" /><br><br> |
| |
| This example will return all users with userId that begins with 'demo':<br><br> |
| <img src="./images/Screenshot16-cli-fuser.png" /><br><br> |
| </li> |
| <li> |
| To learn more about the CLI and what it can do, follow instructions in the command line interpreter reference |
| manual in the javadoc located here: |
| <br><br> |
| <a href="./dist/docs/api/us/jts/fortress/cli/package-summary.html">Command Line Interpreter</a> |
| <br><br> |
| Note: if javadocs are not found, go to Section VII |
| </li> |
| </ol> |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to run Fortress Console (optional)</h3> |
| For tasks like one-time setup of new users, password resets, searches |
| the Fortress Console application can be used.<br><br> |
| <ol type="A"> |
| <li> |
| From FORTRESS_HOME root folder, enter the following command |
| from a system prompt: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh console |
| </p></pre> |
| <img src="./images/Screenshot17-ant-console.png" /><br><br> |
| </li> |
| |
| <li> |
| Console Screenshots... |
| <ol type="1"> |
| <br> |
| <li> |
| Main Menu: |
| <br><img src="./images/Screenshot18-console-main.png" /><br> |
| </li> |
| <br> |
| <li> |
| Enter choice and follow the screen prompts to edit RBAC data: |
| <br><img src="./images/Screenshot19-console-admin.png" /><br> |
| </li> |
| <br> |
| |
| <li> |
| Enter choice and follow the screen prompts to search RBAC data: |
| <br><img src="./images/Screenshot20-console-review.png" /><br> |
| </li> |
| <br> |
| <li> |
| Enter choice and follow the screen prompts to test RBAC policies: |
| <br><img src="./images/Screenshot21-console-access.png" /><br> |
| </li> |
| <br> |
| <li> |
| Enter choice and follow the screen prompts to setup ARBAC delegated policies: |
| <br><img src="./images/Screenshot22-console-deladmin.png" /><br> |
| </li> |
| <br> |
| <li> |
| Enter choice and follow the screen prompts to search through the AUDIT log: |
| <br><img src="./images/Screenshot23-console-audit.png" /> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </li> |
| <hr> |
| <li> |
| <h3>Instructions to generate and view Javadoc (optional)</h3> |
| <ol type="A"> |
| <li> |
| Run the javadoc target: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">/b.sh javadoc |
| </p></pre> |
| <img src="./images/Screenshot24-ant-javadoc.png" /><br><br> |
| </li> |
| <li>Navigate to where docs are genned:</li> |
| <br> |
| <img src="./images/Screenshot25-javadoc-listing.png" /><br><br> |
| <li>Open 'index.html' using your preferred HTML Browser:</li> |
| <img src="./images/Screenshot26-javadoc.png" /><br><br> |
| |
| <li>The javadoc provides coverage of the Fortress APIs and also provides explanations on how RBAC, ARBAC, PW Policies and Audit work.</li> |
| <br> <a href=""></a> |
| <li> |
| Good places to start learning about Fortress: |
| <ul><br> |
| <li><a href="./dist/docs/api/us/jts/fortress/package-summary.html">Fortress Manager Summary</a></li> |
| <li><a href="./dist/docs/api/us/jts/fortress/rbac/package-summary.html">RBAC Summary</a></li> |
| <li><a href="./dist/docs/api/us/jts/fortress/AuditMgr.html">Audit Manager</a></li> |
| <li><a href="./dist/docs/api/us/jts/fortress/cli/package-summary.html">Command Line Interpreter</a></li> |
| <li><a href="./dist/docs/api/us/jts/fortress/ant/FortressAntTask.html">FortressAntTask</a></li> |
| </ul> |
| </li> |
| </ol> |
| <hr> |
| <li> |
| <h3>Instructions to install EnMasse Policy Server Demo (optional)</h3> |
| <ol type="A"> |
| <li> |
| Run the install-enmasse-demo target: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">/b.sh install-enmasse-demo |
| </p></pre> |
| |
| </li> |
| <li> |
| Verify it ran correctly according to Ant. |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">BUILD SUCCESSFUL |
| </p></pre> |
| <img src="./images/Screenshot42-install-enmasse-demo-success.png" /><br><br> |
| <li> |
| After above step completes, Fortress EnMasse will be installed |
| <br><br> |
| </li> |
| </ol> |
| <hr> |
| <li> |
| <h3>Instructions to regression test EnMasse Policy server on target machine (optional)</h3> |
| <ol type="A"> |
| |
| <li>Edit file named 'build.properties' and enable REST protocol here: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">enable.mgr.impl.rest=true |
| </p></pre> |
| Accept the defaults for other HTTP parameters in build.properties: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">http.user=demouser4 |
| http.pw=gX9JbCTxJW5RiH+otQEX0Ja0RIAoPBQf |
| http.host=localhost |
| http.port=8080 |
| </p></pre> |
| </li> |
| Should look like the following: |
| <br><br><img src="./images/Screenshot41-enmasse-http-settings.png" /><br><br> |
| |
| <li>Save and exit the text file editor |
| </li><br> |
| |
| <li>From FORTRESS_HOME root folder, enter the following command from a system prompt: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh test-full |
| </p></pre> |
| </li> |
| <img src="./images/Screenshot10-ant-test-init.png" /><br><br> |
| Note: The EnMasse regression tests will run for around 20 minutes.<br><br> |
| <li>Verify these tests ran with no ERRORS. |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">BUILD SUCCESSFUL |
| </p></pre> |
| </li> |
| <img src="./images/Screenshot43-ant-enmasse-test-success.png" /><br><br> |
| <li> |
| This regression test may be rerun as often as necessary: |
| <br><pre><p style="font-family:monospace;color:blue;font-size:14px;">./b.sh test-full |
| </p></pre> |
| </li> |
| Note 1: WARNING messages in test output are good as these are negative tests in action: |
| <br><img src="./images/Screenshot12-junit-warn.png" /> |
| <br><br>Note 2: If you made it this far without junit or ant ERRORS, EnMasse is installed and certified to run on your machine. |
| <br><br>Note 3: These tests load tens of thousands of records into your directory. |
| The 'test-full' target may be re-run as often as necessary. After regressions testing have completed, you may run the 'init-apacheds' target to remove all test data from the directory. |
| </li> |
| </li> |
| </ol> |
| <hr> |
| <li> |
| <h3>Instructions to install Commander Web UI Demo (optional)</h3> |
| Run the install-commander-demo target: |
| <pre><p style="font-family:monospace;color:blue;font-size:14px;">/b.sh install-commander-demo |
| </p></pre> |
| |
| </li> |
| <li> |
| <h3>More Utilities</h3> |
| Other execution targets you may find useful: |
| <ol type="A"> |
| <br> |
| <li> |
| 'test-samples' - contains examples of how the Fortress API's work |
| check out the following javadoc for more info on the samples package: |
| <a href="./dist/docs/samples/index.html">Samples Javadoc</a> |
| </li> |
| <br> |
| <li> |
| 'admin' - provides an XML-centric way to provision RBAC data policies and user accounts. |
| check out the following javadoc for more info on this utility: |
| <a href="./dist/docs/api/us/jts/fortress/ant/FortressAntTask.html">Fortress Ant admin script utility document</a> |
| </li> |
| <br> |
| <li>'encrypt' - interface to jacypt encryption utility</li> |
| <br> |
| <li>display all ant targets available: |
| <br><img src="./images/Screenshot27-ant-p.png" /><br><br> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </ol> |
| <hr> |
| Copyright (c) 2009-2013, JoshuaTree. All Rights Reserved. |
| </body> |