Commit 9ecf843f authored by cdanger's avatar cdanger

Updated doc for new release 9.0.1 of AuthzForce Server

parent dffb703e
Features
========
See `the list of features on Github for the current version <https://github.com/authzforce/fiware/blob/release-8.1.0/doc/Features.md>`__.
See `the list of features on Github for the current version <https://github.com/authzforce/fiware/blob/release-9.0.1/doc/Features.md>`__.
......@@ -14,11 +14,11 @@ The system requirements are the following:
* RAM: 4GB min
* Disk space: 10 GB min
* File system: ext4
* Operating System: Ubuntu 16.04 LTS
* Operating System: Ubuntu 18.04 LTS
* Java environment:
* JRE 8 either from OpenJDK or Oracle;
* Tomcat 8.x.
* Tomcat 9.x.
Installation
============
......@@ -34,29 +34,29 @@ Minimal setup
* If you prefer OpenJDK: ``$ sudo apt install openjdk-8-jre``
* If you prefer Oracle JDK, follow the instructions from `WEB UPD8 <http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html>`_.
In the end, you should have the package ``oracle-java8-installer`` installed.
#. Install Tomcat 8: ``$ sudo apt install tomcat8``.
#. Install Tomcat 9: ``$ sudo apt install tomcat9``.
#. Each AuthzForce Server version number has the form MAJOR.MINOR.PATH (Semantic Versioning). Identify the latest binary (Ubuntu package with ``.deb`` extension) release of AuthzForce Server
on `Maven Central Repository <http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/>`_ that matches the MAJOR.MINOR version of this documentation.
This is the current latest software version to which this documentation version applies.
If you want to use a different software version, go to the latest documentation version with matching MAJOR.MINOR and follow instructions there.
Else you may download the software version. We will refer to its version number as ``M.m.P`` (please replace accordingly):
$ wget http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/M.m.P/authzforce-ce-server-dist-M.m.P.deb
$ wget https://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/M.m.P/authzforce-ce-server-dist-M.m.P.deb
You should get a file called ``authzforce-ce-server-dist-M.m.P.deb``.
#. Copy this file to the host where you want to install the software.
#. On the host, from the directory where you copied this file, run the following commands::
$ sudo aptitude install gdebi curl
$ sudo gdebi authzforce-ce-server-dist-M.m.P.deb
$ sudo apt install curl
$ sudo apt install ./authzforce-ce-server-dist-M.m.P.deb
#. At the end, you will see a message giving optional instructions to go through. Please follow them as necessary.
Note that Tomcat default configuration may specify a very low value for the Java ``Xmx`` flag, causing the Authzforce webapp startup to fail.
Note that Tomcat default configuration may specify a very low value for the Java ``Xmx`` flag, causing the AuthzForce webapp startup to fail.
In that case, make sure Tomcat with ``Xmx`` at 1 Go or more (2 Go recommended).
You can fix it as follows::
$ sudo sed -i "s/-Xmx128m/-Xmx1024m/" /etc/default/tomcat
$ sudo service tomcat8 restart
$ sudo systemctl restart tomcat9
**Known issue: lack of entropy may cause delays in Tomcat start up on virtual machines in particular**:
`more info on Entropy Source issue <https://wiki.apache.org/tomcat/HowTo/FasterStartUp#Entropy_Source>`_. **So beware.**
......@@ -65,7 +65,7 @@ Upgrade
-------
If you are still using an older version of AuthzForce and wish to migrate your setup to the new version, assuming you made a backup in a separate location, as told previously, please follow these steps:
#. Download AuthzForce server `upgrader distribution (.tar.gz extension) from Maven Central Repository <http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-upgrader/>`_
#. Download AuthzForce server `upgrader distribution (.tar.gz extension) from Maven Central Repository <https://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-upgrader/>`_
in the same version as the Server version you want to upgrade to.
You get a file called ``authzforce-ce-server-upgrader-M.m.P.tar.gz`` (replace ``M.m.P`` with the corresponding version).
#. Copy this file to the host where the old AuthzForce Server is installed, and unzip it and change directory::
......@@ -90,18 +90,18 @@ Administration
Tomcat
------
For configuring and managing Tomcat, please refer to the `official user guide <http://tomcat.apache.org/tomcat-7.0-doc/index.html>`_.
For configuring and managing Tomcat, please refer to the `official user guide <http://tomcat.apache.org/tomcat-9.0-doc/index.html>`_.
Authzforce webapp
-----------------
The Authzforce webapp configuration directory is located here: ``/opt/authzforce-ce-server/conf``.
In particular, the file ``logback.xml`` configures the logging for the webapp (independently from Tomcat). By default, Authzforce-specific logs go to ``/var/log/tomcat8/authzforce-ce/error.log``.
In particular, the file ``logback.xml`` configures the logging for the webapp (independently from Tomcat). By default, Authzforce-specific logs go to ``/var/log/tomcat9/authzforce-ce/error.log``.
Restart Tomcat to apply any configuration change::
$ sudo service tomcat8 restart
$ sudo systemctl restart tomcat9
.. _adminGuideFastInfoset:
......@@ -118,7 +118,7 @@ and that `adopted <http://www.web3d.org/documents/specifications/19776-3/V3.3/Pa
for the serialization and compression of `X3D <http://www.web3d.org/x3d/what-x3d>`_ documents. X3D is a standard for representing 3D scenes and objects using XML.
AuthzForce Server offers experimental support for Fast Infoset (use with caution). This feature is disabled by default.
To enable Fast Infoset support, change the value of the parameter ``spring.profiles.active`` to ``+fastinfoset`` in the webapp context configuration file ``/etc/tomcat8/Catalina/localhost/authzforce-ce.xml``;
To enable Fast Infoset support, change the value of the parameter ``spring.profiles.active`` to ``+fastinfoset`` in the webapp context configuration file ``/etc/tomcat9/Catalina/localhost/authzforce-ce.xml``;
then restart Tomcat as shown in the previous section in order to apply changes.
.. _adminGuideDomainAdmin:
......@@ -271,7 +271,7 @@ In order to achieve high availability with multiple AuthzForce Server instances
* **Embedded file monitoring threads**: it is possible to enable file monitoring threads embedded in AuthzForce Server.
These threads check for changes to the local data directory periodically, and synchronize the cache automatically. This feature is disabled by default.
To enable it, change the value of the parameter ``org.ow2.authzforce.domains.sync.interval`` to a strictly positive integer
in the webapp context configuration file ``/etc/tomcat8/Catalina/localhost/authzforce-ce.xml``.
in the webapp context configuration file ``/etc/tomcat9/Catalina/localhost/authzforce-ce.xml``.
The parameter value indicates the period between two checks for changes, in seconds.
Beware that this feature creates one extra thread per domain. Therefore, the impact on memory and CPU usage increases with the number of domains.
Last but not least, **use this feature only on filesystems that support millisecond or higher resolution of file timestamps**, such as ``ext4`` (supports nanosecond resolution).
......@@ -330,18 +330,18 @@ Diagnosis Procedures
#. Perform the test described in `End to End testing`_.
#. If you get a Connection Refused/Error, check whether Tomcat is started::
$ sudo service tomcat8 status
$ sudo systemctl status tomcat9
#. If status stopped, start Tomcat::
$ sudo service tomcat8 start
#. If Tomcat fails to start, check for any Tomcat high-level error in Tomcat log directory: ``/var/log/tomcat8``
$ sudo systemctl start tomcat9
#. If Tomcat fails to start, check for any Tomcat high-level error in Tomcat log directory: ``/var/log/tomcat9``
#. If Tomcat is successfully started (no error in server logs), perform the test described in `End to End testing`_ again.
#. If you still get a Connection Refused/error, check whether Tomcat is not listening on a different port::
$ sudo netstat -lataupen|grep java
#. If you still get a connection refused/error, especially if you are connecting remotely, check whether you are able to connect locally, then check the network link,
i.e. whether any network filtering is in place on the host or on the access network, or other network issue: network interface status, DNS/IP adress resolution, routing, etc.
#. If you get an error ``404 Not Found``, make sure the webapp is deployed and enabled in Tomcat. Check for any webapp deployment error in file: ``/var/log/tomcat8/authzforce-ce/error.log``.
#. If you get an error ``404 Not Found``, make sure the webapp is deployed and enabled in Tomcat. Check for any webapp deployment error in file: ``/var/log/tomcat9/authzforce-ce/error.log``.
Resource availability
......@@ -385,7 +385,7 @@ For instance, the *NIST Guide to General Server Security* (SP 800-123) is a good
Server Security Setup
+++++++++++++++++++++
For more Tomcat-specific security guidelines, please read `Tomcat 8 Security considerations <https://tomcat.apache.org/tomcat-8.0-doc/security-howto.html>`_.
For more Tomcat-specific security guidelines, please read `Tomcat 9 Security considerations <https://tomcat.apache.org/tomcat-9.0-doc/security-howto.html>`_.
For security of communications (confidentiality, integrity, client/server authentication), it is also recommended to enable SSL/TLS with PKI certificates.
The first step to set up this is to have your Certification Authority (PKI) issue a server certificate for your AuthzForce instance.
......@@ -414,7 +414,7 @@ use the ``pathlen`` parameter to restrict number of subordinate CA, ``pathlen=0`
Server SSL Certificate Setup
++++++++++++++++++++++++++++
For Tomcat 8, refer to the `Tomcat 8 SSL/TLS Configuration HOW-TO <https://tomcat.apache.org/tomcat-8.0-doc/ssl-howto.html>`_.
For Tomcat 9, refer to the `Tomcat 9 SSL/TLS Configuration HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html>`_.
Web Application Secutity
......@@ -426,8 +426,8 @@ XML Security
The AuthzForce web application exposes a XML-based API. Therefore it is vulnerable to XML denial-of-service attacks.
To mitigate these attacks, there are two solutions:
* **Authzforce native protection**: you can add the following `Environment entries <https://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Environment_Entries>`_
in Authzforce webapp context file ``/etc/tomcat8/Catalina/localhost/authzforce-ce.xml`` (if an entry is absent or its value is negative, the default value is used):
* **AuthzForce native protection**: you can add the following `Environment entries <https://tomcat.apache.org/tomcat-9.0-doc/config/context.html#Environment_Entries>`_
in AuthzForce webapp context file ``/etc/tomcat9/Catalina/localhost/authzforce-ce.xml`` (if an entry is absent or its value is negative, the default value is used):
.. code-block:: xml
......@@ -479,8 +479,8 @@ Similarly, if you want to use TLS, then the WAF or some proxy in front of it mus
Disabling unused features
*************************
You can disable all PAP features, i.e. make the REST API read-only by setting the ``enablePdpOnly`` `environment entry <https://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Environment_Entries>`_
to ``true`` in Authzforce webapp context file ``/etc/tomcat8/Catalina/localhost/authzforce-ce.xml`` (if an entry is absent or its value is negative, the default value is used):
You can disable all PAP features, i.e. make the REST API read-only by setting the ``enablePdpOnly`` `environment entry <https://tomcat.apache.org/tomcat-9.0-doc/config/context.html#Environment_Entries>`_
to ``true`` in AuthzForce webapp context file ``/etc/tomcat9/Catalina/localhost/authzforce-ce.xml`` (if an entry is absent or its value is negative, the default value is used):
.. code-block:: xml
......
This diff is collapsed.
......@@ -93,9 +93,9 @@ author = u'Cyril Dangerville, THALES'
# built documents.
#
# The short X.Y version.
version = '8.1.0'
version = '9.0.1'
# The full version, including alpha/beta/rc tags.
release = '8.1.0'
release = '9.0.1'
rst_epilog = """
.. |product.version| replace:: {0}
......
# Copyright (C) 2012-2019 THALES.
#
# This file is part of AuthZForce CE.
#
# AuthZForce CE is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# AuthZForce CE is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with AuthZForce CE. If not, see <http://www.gnu.org/licenses/>.
# Best practices for writing Dockerfiles:
# https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/
# Tips to do an unattended installation on Debian/Ubuntu:
# http://www.microhowto.info/howto/perform_an_unattended_installation_of_a_debian_package.html
# The alternative is to use FROM ubuntu:* then install tomcat ubuntu package and use upstart/sysctl init script but this is not the way to go:
# https://github.com/docker/docker/issues/6800
FROM tomcat:8-jre8
MAINTAINER AuthzForce Team (contact mailing list: http://scr.im/azteam)
ENV DEBIAN_FRONTEND noninteractive
# Proxy configuration (if you are building from behind a proxy)
# Next release of docker 1.9.0 should allow you to configure these by passing build-time arguments
# More info: https://github.com/docker/docker/issues/14634
#ENV http_proxy 'http://user:password@proxy-host:proxy-port'
#ENV https_proxy 'http://user:password@proxy-host:proxy-port'
#ENV HTTP_PROXY 'http://user:password@proxy-host:proxy-port'
#ENV HTTPS_PROXY 'http://user:password@proxy-host:proxy-port'
ENV JAVA_OPTS="-Djava.security.egd=file:/dev/./urandom -Djava.awt.headless=true -Djavax.xml.accessExternalSchema=all -Xms1024m -Xmx2048m -XX:+UseConcMarkSweepGC -server"
ENV AUTHZFORCE_SERVER_VERSION="8.1.0"
ENV AUTHZFORCE_SERVER_DOWNLOAD_URL="http://repo1.maven.org/maven2/org/ow2/authzforce/authzforce-ce-server-dist/$AUTHZFORCE_SERVER_VERSION/authzforce-ce-server-dist-$AUTHZFORCE_SERVER_VERSION.deb"
# Download and install Authzforce Server (service starts automatically)
# Where there is a command with a pipe, we need to put in between quotes and make it an argument to bash -c command
RUN apt-get update --assume-yes -qq && \
apt-get install --assume-yes -qq \
locales-all \
locales \
less \
apt-utils \
debconf-utils \
gdebi \
curl && \
rm -rf /var/lib/apt/lists/*
RUN locale-gen en_US en_US.UTF-8
RUN dpkg-reconfigure locales
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US:en
ENV LC_ALL en_US.UTF-8
RUN curl --silent --output authzforce-ce-server.deb --location $AUTHZFORCE_SERVER_DOWNLOAD_URL && \
dpkg --extract authzforce-ce-server.deb /root/authzforce/ && \
mv /root/authzforce/etc/tomcat8/Catalina /usr/local/tomcat/conf/ && \
mv /root/authzforce/opt/* /opt/ && \
rm -rf /opt/authzforce-ce-server/data/domains/* && \
rm -rf /root/authzforce && \
rm -f authzforce-ce-server.deb
VOLUME /opt/authzforce-ce-server/data
VOLUME /usr/local/tomcat/conf
CMD ["catalina.sh", "run"]
### Exposed ports
# - App server
EXPOSE 8080
## Authorization PDP - AuthzForce Docker minimal image
## AuthzForce Server CE - Minimal Docker image
[Authorization PDP - AuthzForce](http://catalogue.fiware.org/enablers/authorization-pdp-authzforce) is a Reference Implementation of the Authorization PDP Generic Enabler (formerly Access Control GE).
Find detailed information of this Generic Enabler at [Fiware catalogue](http://catalogue.fiware.org/enablers/authorization-pdp-authzforce).
This image is intended to work together with [Identity Manager - Keyrock](http://catalogue.fiware.org/enablers/identity-management-keyrock) and [PEP Proxy Wilma](http://catalogue.fiware.org/enablers/pep-proxy-wilma) generic enabler; and also integrated in Bitergia's [Chanchan APP](https://github.com/Bitergia/fiware-chanchan).
This image of a minimal AuthzForce Server runtime is intended to work together with [Identity Manager - Keyrock](http://catalogue.fiware.org/enablers/identity-management-keyrock) and [PEP Proxy Wilma](http://catalogue.fiware.org/enablers/pep-proxy-wilma) generic enabler.
## Image contents
- OpenJDK JRE 8;
- Tomcat 8;
- Authzforce Server (version matching the Docker image tag).
- Tomcat 9;
- AuthzForce Server CE (version matching the Docker image tag).
## Usage
This image gives you a minimal installation for testing purposes. The AuthzForce Installation and administration guide on [readthedocs.org](https://readthedocs.org/projects/authzforce-ce-fiware/versions/) (select the version matching the Docker image tag, then **AuthzForce - Installation and Administration Guide**) provides you a better approach for using it in a production environment. This installation guide also gives instructions to install from .deb package (instead of Docker), which is the recommended way for Ubuntu hosts.
This image gives you a minimal installation for testing purposes. The AuthzForce Installation and Administration guide on [readthedocs.org](https://readthedocs.org/projects/authzforce-ce-fiware/versions/) (select the version matching the Docker image tag, then **AuthzForce - Installation and Administration Guide**) provides you a better approach for using it in a production environment. This installation guide also gives instructions to install from .deb package (instead of Docker), which is the recommended way for Ubuntu hosts.
Create a container using `fiware/authzforce-ce-server` image by doing (replace the first *8080* after *-p* with whatever network port you want to use on the host to access the Authzforce Server, e.g. 80; and *release-6.0.0* with the current Docker image tag that you are using):
Create a container using `authzforce/server` image by doing (replace the first *8080* after *-p* with whatever network port you want to use on the host to access the AuthzForce Server, e.g. 80; and *release-9.0.0* with the current Docker image tag that you are using):
```
docker run -d -p 8080:8080 --name <container-name> fiware/authzforce-ce-server:release-6.0.0
docker run -d -p 8080:8080 --name <container-name> fiware/authzforce-ce-server:release-9.0.0
```
As stands in the AuthzForce Installation and administration guide on [readthedocs.org](https://readthedocs.org/projects/authzforce-ce-fiware/versions/) (select the version matching the Docker image tag, then **AuthzForce - Installation and Administration Guide**) you can:
......@@ -56,8 +52,8 @@ These tasks are now delegated to the [Identity Manager - Keyrock](http://catalog
### Documentation
All the information regarding the Dockerfile is hosted publicly on [Github](https://github.com/authzforce/fiware/tree/master/docker).
All the information regarding the Dockerfile is hosted publicly on [Github](https://github.com/authzforce/server/tree/master/src/docker).
### Issues
If you find any issue with this image, feel free to report at [Github issue tracking system](https://github.com/authzforce/fiware/issues).
If you find any issue with this image, feel free to report at [Github issue tracking system](https://github.com/authzforce/server/issues).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment