diff --git a/source/fusiondirectory-orchestrator/configuration/configuration.rst b/source/fusiondirectory-orchestrator/configuration/configuration.rst new file mode 100644 index 0000000000000000000000000000000000000000..882f937d4e495797d891a426298b0869e7b06fce --- /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 0000000000000000000000000000000000000000..fde21e937a446c84414f109593e5f9294333efd8 --- /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 0000000000000000000000000000000000000000..c0dd60fd49ef5a0a351e1312bb2460acbdfb1778 --- /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 0000000000000000000000000000000000000000..bbcc2e432f0d802c0cc406178d14be4ce2a2d60a --- /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 0000000000000000000000000000000000000000..23bd041c51fab7bd8876a51e8a7e36089c9fa675 --- /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 0000000000000000000000000000000000000000..d990e2fa22781f5c3d6a7c5fc3321cda1361098b --- /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 0000000000000000000000000000000000000000..4eb5b3a12f0a4ed6f080b3e0dff71e21d5301ced --- /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 0000000000000000000000000000000000000000..4ce4563be2a8d4ba48e4a142ec1a37d63f8915be --- /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 0000000000000000000000000000000000000000..4749ab4ed977e0bf10b95f85c76c3f2c9610e9e2 --- /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 0000000000000000000000000000000000000000..ca5e8f0bc0c0499acdea6860c08fcdf3fbea09b2 --- /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 0000000000000000000000000000000000000000..396fc460d06e8ebef2e1c636065f60046260f55b --- /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 0000000000000000000000000000000000000000..09e91ff59f69986f84cbd9da391f4ae93ac7592a --- /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 0000000000000000000000000000000000000000..0deeb8ae1995d87d06205e6728ed867ba8399ff1 --- /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 0000000000000000000000000000000000000000..7b187542cc111fdd5bc173082893f1e2306d03d6 --- /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 0000000000000000000000000000000000000000..4a79b9724bb24ea064f0acbd9b7831aa28fd7358 --- /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 aa2dd1f056e753db0028ad6d877ecbc7bd16fd26..10997014543b36a33d56ec3b5913121a8c82b001 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 0ccd7c30974c6595740a53e51b472516e1cda0bd..2a647468f580d441be7acd65ec1ef459bb9c2d78 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 ec121e1b918c4fd0dcde722cd423499dc93be33a..a6308bc43822e7bca4b184eba84b8e62cb4b2bff 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 +