From 7e50c8abfa36711a328d0cd266893806a24cf359 Mon Sep 17 00:00:00 2001
From: bmortier <benoit.mortier@fusiondirectory.org>
Date: Thu, 28 Sep 2023 16:47:05 +0000
Subject: [PATCH] Resolve "[Orchestrator] - Installation and configuration
manual"
---
.../configuration/configuration.rst | 88 +++++++++++++++++++
.../endpoints/index.rst | 8 ++
.../endpoints/tasks/description.rst | 16 ++++
.../endpoints/tasks/functionalities.rst | 63 +++++++++++++
.../endpoints/tasks/index.rst | 8 ++
source/fusiondirectory-orchestrator/index.rst | 14 +++
.../centos/centos-orchestrator-install.rst | 37 ++++++++
.../install/centos/index.rst | 7 ++
.../debian/debian-orchestrator-install.rst | 38 ++++++++
.../install/debian/index.rst | 7 ++
.../install/index.rst | 10 +++
.../license/index.rst | 7 ++
.../license/license.rst | 6 ++
.../prerequisite/prerequisite.rst | 34 +++++++
.../whatis/orchestrator.rst | 37 ++++++++
source/index.rst | 1 +
source/repositories/centos.rst | 12 +++
source/repositories/debian.rst | 12 ++-
18 files changed, 403 insertions(+), 2 deletions(-)
create mode 100644 source/fusiondirectory-orchestrator/configuration/configuration.rst
create mode 100644 source/fusiondirectory-orchestrator/endpoints/index.rst
create mode 100644 source/fusiondirectory-orchestrator/endpoints/tasks/description.rst
create mode 100644 source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst
create mode 100644 source/fusiondirectory-orchestrator/endpoints/tasks/index.rst
create mode 100644 source/fusiondirectory-orchestrator/index.rst
create mode 100644 source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst
create mode 100644 source/fusiondirectory-orchestrator/install/centos/index.rst
create mode 100644 source/fusiondirectory-orchestrator/install/debian/debian-orchestrator-install.rst
create mode 100644 source/fusiondirectory-orchestrator/install/debian/index.rst
create mode 100644 source/fusiondirectory-orchestrator/install/index.rst
create mode 100644 source/fusiondirectory-orchestrator/license/index.rst
create mode 100644 source/fusiondirectory-orchestrator/license/license.rst
create mode 100644 source/fusiondirectory-orchestrator/prerequisite/prerequisite.rst
create mode 100644 source/fusiondirectory-orchestrator/whatis/orchestrator.rst
diff --git a/source/fusiondirectory-orchestrator/configuration/configuration.rst b/source/fusiondirectory-orchestrator/configuration/configuration.rst
new file mode 100644
index 00000000..882f937d
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/configuration/configuration.rst
@@ -0,0 +1,88 @@
+Configuration
+-------------
+
+| Orchestrator requires a one file to be configured properly.
+
+Configuration file
+""""""""""""""""""
+.. note::
+ The editable file is located at **/etc/fusiondirectory-orchestrator/orchestrator.conf**
+
+[LDAP settings]
+^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+ LDAP_HOST="localhost"
+
+Required in order to connect to the proper host.
+FQDN or IP must be provided.
+
+.. code-block:: shell
+
+ LDAP_ADMIN="cn=admin,dc=fusiondirectory,dc=org"
+
+Required by LDAP in order to use the proper privileges.
+
+.. code-block:: shell
+
+ LDAP_PWD="ldap_pwd"
+
+Required password to authenticate LDAP
+
+.. code-block:: shell
+
+ LDAP_OU_USER="ou=people,dc=fusiondirectory"
+
+Required to ease the research of the branch people by endpoints.
+
+[JWT token settings]
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: shell
+
+ #SECRET_KEY can be generated via a 256 bit Wep key generator such as
+ #https://allkeysgenerator.com/
+ SECRET_KEY="256 bit key"
+
+Required to secure and validate the generation of access and refresh tokens.
+
+[SMTP server settings]
+^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+ MAIL_USER="mail_user"
+
+The login ID to authenticate to the specified SMTP server.
+
+.. code-block:: shell
+
+ MAIL_PASS="mail_pwd"
+
+The password used for above authentication.
+
+.. code-block:: shell
+
+ MAIL_HOST="fqdn or IP"
+
+The SMTP server domain name or IP.
+
+.. code-block:: shell
+
+ MAIL_SEC="ssl"
+
+The required secure methode. "TLS" can be used for "STARTLS".
+Please note the importance of lowercase in 'ssl' or 'tls'.
+
+.. code-block:: shell
+
+ MAIL_PORT="SMTP port number"
+
+The TCP/UDP port number of the SMTP server.(Example: SSL 465 / TLS 586).
+
+.. Note::
+
+ | Orchestrator is highly depending on the URL rewriting mechanism of the web server.
+ | In case of Apache2 ".htaccess" files are responsible for that logic.
+
+ | Although informative, there should not be any value of modifying the contents of those files.
+ | The goal is to redirect any call on URI to the main index file located in API directory.
diff --git a/source/fusiondirectory-orchestrator/endpoints/index.rst b/source/fusiondirectory-orchestrator/endpoints/index.rst
new file mode 100644
index 00000000..fde21e93
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/endpoints/index.rst
@@ -0,0 +1,8 @@
+FusionDirectory Orchestrator Endpoints
+======================================
+
+
+.. toctree::
+ :maxdepth: 2
+
+ tasks/index.rst
diff --git a/source/fusiondirectory-orchestrator/endpoints/tasks/description.rst b/source/fusiondirectory-orchestrator/endpoints/tasks/description.rst
new file mode 100644
index 00000000..c0dd60fd
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/endpoints/tasks/description.rst
@@ -0,0 +1,16 @@
+Description
+===========
+
+Tasks is an endpoints of Orchestrator.
+
+.. note::
+ It is reachable via **https://your_fqdn/api/tasks/**
+
+Arguments
+---------
+
+- Mail
+
+You can :
+ - Retrieve all tasks of type mail.
+ - Process all tasks of type mail and forward the related e-mails.
diff --git a/source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst b/source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst
new file mode 100644
index 00000000..bbcc2e43
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst
@@ -0,0 +1,63 @@
+
+Functionalities
+===============
+
+| E-mails are being sent based on the schedule of the processed task.
+
+How it works
+------------
+
+Asking the proper endpoints with the allowed HTTP methods will trigger the required action.
+
+Examples
+--------
+
+.. note::
+
+ | An orchestrator client is being developped in order to automate some of the below examples.
+ | It will allow easier management of repeated tasks within a CRON job.
+
+
+Get access-token
+""""""""""""""""
+
+.. code-block:: shell
+
+ # Login and get access-token
+ curl -X POST -H "Content-Type: application/json" https://example.org/orchestrator/api/login -d '{"username":"admin","password":"secret"}'
+
+Get all mail tasks
+""""""""""""""""""
+
+.. code-block:: shell
+
+ # Get all mail tasks using the access-token
+ curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer {token}" https://example.org/orchestrator/api/tasks/mail
+
+Send e-mails
+""""""""""""
+
+.. code-block:: shell
+
+ # Login and get access-token
+ curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {token}" https://example.org/orchestrator/api/tasks/mail
+
+Refresh access token
+""""""""""""""""""""
+
+.. code-block:: shell
+
+ # Refresh access token with refresh token
+ curl -X POST -H "Content-Type: application/json" http://192.168.1.100:8080/orchestrator/api/refresh -d '{"token":"refresh-token"}'
+
+Conditions
+----------
+
+In order to process mail tasks, a few conditions are analysed:
+
+- Schedule for the tasks.
+- A max-emails threshold to be sent.
+- A time interval between mail tasks processing.
+
+.. note::
+ The settings for above conditions are found within FusionDirectory configuration menu.
diff --git a/source/fusiondirectory-orchestrator/endpoints/tasks/index.rst b/source/fusiondirectory-orchestrator/endpoints/tasks/index.rst
new file mode 100644
index 00000000..23bd041c
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/endpoints/tasks/index.rst
@@ -0,0 +1,8 @@
+Orchestrator Mail Task
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ description.rst
+ functionalities.rst
diff --git a/source/fusiondirectory-orchestrator/index.rst b/source/fusiondirectory-orchestrator/index.rst
new file mode 100644
index 00000000..d990e2fa
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/index.rst
@@ -0,0 +1,14 @@
+FusionDirectory Orchestrator
+============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ whatis/orchestrator.rst
+ prerequisite/prerequisite.rst
+ install/index.rst
+ configuration/configuration.rst
+ endpoints/index.rst
+ license/index.rst
diff --git a/source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst b/source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst
new file mode 100644
index 00000000..4eb5b3a1
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst
@@ -0,0 +1,37 @@
+Installing Dependencies
+'''''''''''''''''''''''
+
+All The needed dependancies are resolved by the centos packages
+
+.. note::
+
+ The repositories are in https for Centos, same repos as FusionDirectory.
+
+Install FusionDirectory Orchestrator
+''''''''''''''''''''''''''''''''''''
+
+You can then install Orchestrator by running:
+
+.. code-block:: shell
+
+ yum install fusiondirectory-orchestrator
+ yum install fusiondirectory-orchestrator-schema
+
+FusionDirectory Orchestrator Schema installation
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+Now that we have Orchestrator installed, we need to install the
+Orchestrator schemas into our LDAP database.
+
+We can easily do this by running:
+
+.. code-block:: shell
+
+ fusiondirectory-schema-manager --insert-schema /etc/openldap/schema/fusiondirectory/fusiondirectory-orchestrator.schema
+
+You should now be able to use Orchestrator API by visiting :
+
+http://SERVER-IP/orchestrator/api
+
+
+
diff --git a/source/fusiondirectory-orchestrator/install/centos/index.rst b/source/fusiondirectory-orchestrator/install/centos/index.rst
new file mode 100644
index 00000000..4ce4563b
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/install/centos/index.rst
@@ -0,0 +1,7 @@
+Install FusionDirectory Orchestrator on Centos
+==============================================
+
+.. toctree::
+ :maxdepth: 4
+
+ centos-orchestrator-install.rst
diff --git a/source/fusiondirectory-orchestrator/install/debian/debian-orchestrator-install.rst b/source/fusiondirectory-orchestrator/install/debian/debian-orchestrator-install.rst
new file mode 100644
index 00000000..4749ab4e
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/install/debian/debian-orchestrator-install.rst
@@ -0,0 +1,38 @@
+Installing Dependencies
+'''''''''''''''''''''''
+
+All The needed dependancies are resolved by the debian packages
+
+.. note::
+
+ The repositories are in https for Debian
+ so you will need to install **apt-transport-https**
+
+Install FusionDirectory Orchestrator
+''''''''''''''''''''''''''''''''''''
+
+You can then install Orchestrator by running:
+
+.. code-block:: shell
+
+ apt-get install fusiondirectory-orchestrator
+ apt-get install fusiondirectory-orchestrator-schema
+
+FusionDirectory Orchestrator Schema installation
+''''''''''''''''''''''''''''''''''''''''''''''''
+
+Now that we have Orchestrator installed, we need to install the
+Orchestrator schemas into our LDAP database.
+
+We can easily do this by running:
+
+.. code-block:: shell
+
+ fusiondirectory-schema-manager --insert-schema /etc/ldap/schema/fusiondirectory/fusiondirectory-orchestrator.schema
+
+You should now be able to use Orchestrator API by visiting :
+
+http://SERVER-IP/orchestrator/api
+
+
+
diff --git a/source/fusiondirectory-orchestrator/install/debian/index.rst b/source/fusiondirectory-orchestrator/install/debian/index.rst
new file mode 100644
index 00000000..ca5e8f0b
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/install/debian/index.rst
@@ -0,0 +1,7 @@
+Install FusionDirectory Orchestrator on Debian
+==============================================
+
+.. toctree::
+ :maxdepth: 4
+
+ debian-orchestrator-install.rst
diff --git a/source/fusiondirectory-orchestrator/install/index.rst b/source/fusiondirectory-orchestrator/install/index.rst
new file mode 100644
index 00000000..396fc460
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/install/index.rst
@@ -0,0 +1,10 @@
+Install FusionDirectory Orchestrator
+====================================
+
+.. toctree::
+ :maxdepth: 2
+
+ ../../gpg/index.rst
+ ../../repositories/index.rst
+ debian/index.rst
+ centos/index.rst
diff --git a/source/fusiondirectory-orchestrator/license/index.rst b/source/fusiondirectory-orchestrator/license/index.rst
new file mode 100644
index 00000000..09e91ff5
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/license/index.rst
@@ -0,0 +1,7 @@
+License
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ license
diff --git a/source/fusiondirectory-orchestrator/license/license.rst b/source/fusiondirectory-orchestrator/license/license.rst
new file mode 100644
index 00000000..0deeb8ae
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/license/license.rst
@@ -0,0 +1,6 @@
+License
+=======
+
+FusionDirectory is available under the `GNU General Public License 2.0 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+
+FusionDirectory documentation is under the `Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) <https://creativecommons.org/licenses/by-sa/4.0/>`_
diff --git a/source/fusiondirectory-orchestrator/prerequisite/prerequisite.rst b/source/fusiondirectory-orchestrator/prerequisite/prerequisite.rst
new file mode 100644
index 00000000..7b187542
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/prerequisite/prerequisite.rst
@@ -0,0 +1,34 @@
+Prerequisites
+=============
+
+FusionDirectory Orchestrator is a Web application that will need:
+
+* A webserver;
+* PHP;
+* An ldap server;
+* Fusion Directory 1.4 with configured tasks.
+
+Web server
+----------
+
+FusionDirectory Orchestrator requires the following web server that supports PHP and URL Rewriting:
+
+* `Apache 2 (or more recent) <http://httpd.apache.org>`_;
+
+PHP
+---
+
+As of 1.4 release, FusionDirectory Orchestrator requires `PHP <https://www.php.net>`_ 7.3 or 7.4.
+
+^^^^^^^^^^^^^^^^^^^^
+
+LDAP server
+-----------
+
+FusionDirectory Orchestrator will use the LDAP server managed by your FusionDirectory.
+
+Servers know to work are :
+
+* `OpenLDAP`_
+
+.. _OpenLDAP : https://www.openldap.org/
diff --git a/source/fusiondirectory-orchestrator/whatis/orchestrator.rst b/source/fusiondirectory-orchestrator/whatis/orchestrator.rst
new file mode 100644
index 00000000..4a79b972
--- /dev/null
+++ b/source/fusiondirectory-orchestrator/whatis/orchestrator.rst
@@ -0,0 +1,37 @@
+What is FusionDirectory Orchestrator ?
+======================================
+
+| FusionDirectory Orchestrator provides a web service solution serving a REST API.
+| It allows a granular management of some specialized tasks.
+
+Features
+^^^^^^^^
+
+- Tasks management.
+- Tasks execution.
+- JWT Authentication methods
+
+
+Tasks management
+^^^^^^^^^^^^^^^^
+
+| FusionDirectory Orchestrator REST API allows the retrieval of existing created Tasks.
+| Offering a simple view on the status of each tasks.
+
+It is possible to retrieve specialized tasks such as Mail.
+
+Tasks execution
+^^^^^^^^^^^^^^^
+
+| One of the main aspect of FusionDirectory Orchestrator is to allow processing of some desired tasks.
+| In case of a task of type mail, the list of related emails will be sent if scheduled is matched.
+
+JWT authentication
+^^^^^^^^^^^^^^^^^^
+
+| It was decided to enhance our authentication mechanism and use the JWT methodology.
+| Allowing after proper username/password authentication the reception of an access and refresh token.
+
+The access token is to be used for any operations on FusionDirectory Orchestrator endpoints.
+
+
diff --git a/source/index.rst b/source/index.rst
index aa2dd1f0..10997014 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -18,6 +18,7 @@ Contents:
fusiondirectory/index.rst
fusiondirectory-conf/index.rst
fusiondirectory-tools/index.rst
+ fusiondirectory-orchestrator/index.rst
fusiondirectory-webservice/index.rst
support/index.rst
security/index.rst
diff --git a/source/repositories/centos.rst b/source/repositories/centos.rst
index 0ccd7c30..2a647468 100644
--- a/source/repositories/centos.rst
+++ b/source/repositories/centos.rst
@@ -52,3 +52,15 @@ Add a file named **fusiondirectory-release.repo** in /etc/yum.repos.d/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-FUSIONDIRECTORY
+To install FusionDirectory Orchestrator
+
+Add a file named **fusiondirectory-orchestrator-release.repo** in /etc/yum.repos.d/
+
+.. code-block:: shell
+
+ [fusiondirectory-orchestrator-release]
+ name=Fusiondirectory Packages for CentOS 7
+ baseurl=https://public.fusiondirectory.org/centos/centos7-fusiondirectory-rochestrator-release/RPMS
+ enabled=1
+ gpgcheck=1
+ gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-FUSIONDIRECTORY
diff --git a/source/repositories/debian.rst b/source/repositories/debian.rst
index ec121e1b..a6308bc4 100644
--- a/source/repositories/debian.rst
+++ b/source/repositories/debian.rst
@@ -26,8 +26,7 @@ Add a file named **fusiondirectory-external-libraries.list** in /etc/apt/sources
#fusiondirectory libraries
deb https://public.fusiondirectory.org/debian/fusiondirectory-external-libraries/ bullseye main
-
-
+
Debian Buster
^^^^^^^^^^^^^
@@ -49,3 +48,12 @@ Add a file named **fusiondirectory-release.list** in /etc/apt/sources.list.d/
#fusiondirectory repository
deb https://public.fusiondirectory.org/debian/bullseye-fusiondirectory-release/ bullseye main
+To install FusionDirectory Orchestrator
+
+Add a file named **fusiondirectory-orchestrator-release.list** in /etc/apt/sources.list.d/
+
+.. code-block:: shell
+
+ #fusiondirectory Orchestrator repository
+ deb https://public.fusiondirectory.org/debian/bullseye-orchestrator-release/ bullseye main
+
--
GitLab