feat(doc) Releasing User Manual for FusionDirectory 1.5

Signed-off-by: Benoit Mortier <benoit.mortier@fusiondirectory.org>

.gitignore

+.directory
+build

Changelog.md

+## %"FusionDirectory 1.5" - 2025-02-24
+
+### Added
+
+#### user-manual
+- user-manual#175 add the new fonctionnality to desactivate supann tab in supann plugin manual
+- user-manual#176 add new configuration for supann consent in the supann tab in the configuration backend
+- user-manual#177 add new configuration for supann etiquettes for mail and tel in the supann tab in the configuration backend
+- user-manual#219 [user-manual] - updates supann-ext documentation
+- user-manual#241 add the new configuration for the fusiondirectory configuration partage backend configuration
+- user-manual#248 [Tasks] - Explaination in details with screenshots of the new tabs life cycle and the incoming notifications
+- user-manual#258 explain to user how to register the plugin in each plugin installation section
+- user-manual#263 Migration note for 1.4 to 1.5
+- user-manual#271 The task explanation page should show the full task menu and then explain the different sections
+- user-manual#276 add a sectionn for the marketplace from the dev documentation
+
+### Changed
+
+#### user-manual
+- user-manual#253 update the logo with the new one
+- user-manual#265 Add new Authors to the Manual
+- user-manual#268 Update the readme.md
+- user-manual#269 remove the part that talk about stable dev and rewrite the fixes part
+- user-manual#274 make clear that FusionDirectory only support PHP 7.4 and that FusionDirectory Orchestrator start at PHP 7.4
+
+### Removed
+
+#### user-manual
+- user-manual#256 remove the bionic reference form the manual
+- user-manual#260 removing the old gpg singature from the manual
+- user-manual#261 remove the development gpg key
+- user-manual#262 change support link due to the new website
+- user-manual#275 remove the mention of iis in the manual
+
+### Fixed
+
+#### user-manual
+- user-manual#244 Change the core/main menu into the documentation to reflect the new FusionDirectory menu organisation
+- user-manual#249 Wrong command in "Check for deprecated attributes" section of migration guide from 1.3.-1 to 1.4
+- user-manual#251 remove the utilities repository from the documentation as tools is already containing everything
+- user-manual#254 Wrong url for orchestrator release
+- user-manual#259 Wrong commands in latest/fusiondirectory/plugins/ipam/
+- user-manual#264 Documentation for migration from 1.31 to 1.4 missing migrating mail-fd-conf.schema
+- user-manual#270 there is an error in the task mail explanation
+
+
 ## %"FusionDirectory 1.4" - 2024-02-22
 
 ### Added
@@ -184,5 +230,3 @@
 - user-manual#145 url for the old webservice based on jsonrpc is wrong in the manual
 - user-manual#178 replace freenode by libera
 - user-manual#184 FD upgrade : updating fd-core schema not mentioned in the doc
-
-

README.md

-### FusionDirectory User Manual
\ No newline at end of file
+### FusionDirectory User Manual
+
+
+This is the FusionDirectory user documentation
+
+This source is compiled to give the [FusionDirectory User Manual][fusionDirectory-user-manual]
+
+## Get help
+
+### Community support
+
+There are a couple of ways you can try [to get help][get help].
+
+### Professional support
+
+Professional support is provided through of subscription.
+
+* [FusionDirectory Subscription][subscription-fusiondirectory] : Global subscription for FusionDirectory 
+
+The subscription provides access to FusionDirectory's enterprise repository, tested and pre-packaged versions with patches between versions, 
+providing reliable software updates and security enhancements, as well as technical help and support.
+
+Choose the plan that's right for you. Our subscriptions are flexible and scalable according to your needs
+
+The subscription period is one year from the date of purchase and provides you with access to the extensive infrastructure of enterprise-class software and services.
+
+### Best practice badge
+
+[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/351/badge)](https://bestpractices.coreinfrastructure.org/projects/351)
+  
+## Crowfunding
+
+If you like us and want to send us a small contribution, you can use the following crowdfunding services
+
+* [donate-liberapay]
+
+* [donate-kofi]
+
+* [donate-github]
+  
+## License
+
+[FusionDirectory][FusionDirectory] is  [GPL 2 License](COPYING).
+
+[FusionDirectory]: https://www.fusiondirectory.org/
+
+[fusionDirectory-user-manual]: https://fusiondirectory-user-manual.readthedocs.io/en/dev/fusiondirectory/index.html
+
+[get help]: https://fusiondirectory-user-manual.readthedocs.io/en/latest/support/index.html
+
+[subscription-fusiondirectory]: https://www.fusiondirectory.org/en/iam-tool-service-subscriptions/
+
+[register]: https://register.fusiondirectory.org
+
+[donate-liberapay]: https://liberapay.com/fusiondirectory/donate
+
+[donate-kofi]: https://ko-fi.com/fusiondirectory
+
+[donate-github]: https://github.com/fusiondirectory

source/conf.py

@@ -53,17 +53,17 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'FusionDirectory User Manual'
-copyright = u'2017, Benoit Mortier Paola Penati'
-author = u'Benoit Mortier Paola Penati'
+copyright = u'2017-2024, FusionDirectory'
+author = u'Benoit Mortier Paola Penati Jonathan Swaelens Thibault Dockx'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'1.4'
+version = u'dev'
 # The full version, including alpha/beta/rc tags.
-release = u'1.4'
+release = u'dev'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -264,7 +264,7 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'FusionDirectoryUserManual.tex', u'FusionDirectory User Manual Documentation',
-     u'Benoit Mortier Paola Penati', 'manual'),
+     u'Benoit Mortier Paola Penati Jonathan Swaelens Thibault Dockx', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

source/fusiondirectory-marketplace/index.rst

+FusionDirectory Marketplace
+===========================
+
+The FusionDirectory marketplace is the best way to find new plugins for FusionDirectory. 
+
+.. image:: /_static/images/marketplace/marketplace-index.png
+
+Looking at a plugin 
+
+.. image:: /_static/images/marketplace/marketplace-show-plugin.png 
+
+
+

source/fusiondirectory-orchestrator/configuration/configuration.rst

@@ -12,10 +12,16 @@ Configuration file
 ^^^^^^^^^^^^^^^
 .. code-block:: shell
 	
-  LDAP_HOST="localhost"
+  FD_LDAP_MASTER_URL="ldaps://ldap.fusiondirectory.org"
 
 Required in order to connect to the proper host.
-FQDN or IP must be provided.
+FQDN or IP must be provided with ldap(s) to secure the connection.
+
+.. code-block:: shell
+
+  LDAP_BASE="dc=fusiondirectory,dc=org"
+
+Required to operate with ldap libraries.
 
 .. code-block:: shell
 	
@@ -31,9 +37,9 @@ Required password to authenticate LDAP
 
 .. code-block:: shell
 	
-  LDAP_OU_USER="ou=people,dc=fusiondirectory"
+  LDAP_OU_DSA="ou=dsa,dc=fusiondirectory,dc=org"
 
-Required to ease the research of the branch people by endpoints.
+Required to ease the research of the branch DSA by endpoints.
 
 [JWT token settings]
 ^^^^^^^^^^^^^^^^^^^^
@@ -46,8 +52,27 @@ Required to ease the research of the branch people by endpoints.
 
 Required to secure and validate the generation of access and refresh tokens.
 
+.. code-block:: shell
+
+	TOKEN_EXPIRY="300"
+
+Required to limit the availability of an issued token. In seconds.
+
+.. code-block:: shell
+
+	REFRESH_EXPIRY="432000"
+
+Required to limit the availability of an issued refresh token. In seconds.
+
 [SMTP server settings]
 ^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+  MAIL_AUTH="TRUE/FALSE"
+
+If authentication is required, the following settings will be applied.
+Note that some mail servers, such as relay servers, may not require authentication.
+
 .. code-block:: shell
 	
   MAIL_USER="mail_user"
@@ -66,9 +91,16 @@ The password used for above authentication.
 
 The SMTP server domain name or IP.
 
+.. code-block:: shell
+
+  MAIL_SEC_VERIFY="TRUE/FALSE"
+
+This setting determines whether to accept all types of certificates,
+including self-signed certificates, if necessary.
+
 .. code-block:: shell
 	
-  MAIL_SEC="ssl"
+  MAIL_SEC="TLS/SSL"
 
 The required secure methode. "TLS" can be used for "STARTLS".
 Please note the importance of lowercase in 'ssl' or 'tls'.
@@ -79,6 +111,33 @@ Please note the importance of lowercase in 'ssl' or 'tls'.
 
 The TCP/UDP port number of the SMTP server.(Example: SSL 465 / TLS 586).
 
+[DSA Login Information]
+^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+  DSA_LOGIN="DSA Login Name"
+  DSA_PASS="DSA Password"
+
+The DSA login that should be used to interact with LDAP.
+
+.. code-block:: shell
+
+  ORCHESTRATOR_API_URL="https://orchestrator.fusiondirectory.org"
+
+The REST API URL in HTTP(s). Required by the fd-orchestrator-client.
+
+[WEB Service FusionDirectory]
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: shell
+
+  FUSION_DIRECTORY_API_URL="https://fd.fusiondirectory.org/rest.php/v1"
+  WEB_LOGIN="weblogin_username"
+  WEB_PASS="weblogin_password"
+
+Information related to the webservice of fusiondirectory. This is required for fusiondirectory-orchestrator
+to activate specific actions within FusionDirectory WEB.
+
+
 .. Note::
 
   | Orchestrator is highly depending on the URL rewriting mechanism of the web server.

source/fusiondirectory-orchestrator/endpoints/audit.rst

+Audit task execution
+====================
+
+.. _audit-task-execution-label:
+
+Once the task is configured, execute it using the **orchestrator-client** tool. You have two execution options:
+
+.. code-block:: bash
+
+   fusiondirectory-orchestrator-client --audit
+
+.. note::
+   **Recommendation** automate this process within a CRON job.
+
+.. note::
+  Add the ``--verbose`` flag to the command for detailed output during execution.
+
+
+.. note::
+    The logs are stored by default at the following location:
+
+    ``/var/log/orchestrator/orchestrator.log``
+

source/fusiondirectory-orchestrator/endpoints/description.rst

+Description
+===========
+
+FusionDirectory Orchestrator provides a primary endpoint, referred to as **tasks**, which accepts multiple arguments for execution.
+New task objects can be added as plugins and invoked as arguments to this endpoint.
+
+.. note::
+   The **tasks** endpoint is accessible via **https://your_fqdn/api/tasks/**.
+
+Arguments
+---------
+
+The **tasks** endpoint supports multiple arguments. Below is a list of the officially supported arguments:
+
+.. note::
+   Each official plugin within **tasks** can be passed as an argument to the **tasks** endpoint. Additionally, a client is available within **FusionDirectory-Tools** to simplify interactions.
+
+- **login**
+   This endpoint facilitates authentication and provides the access and refresh tokens required for further communication with subsequent endpoints.
+
+- **tasks/mail**
+   Invoking this endpoint triggers the execution of mail task objects defined within **FusionDirectory**.
+   It processes the results from the mail server and reports the status to the associated tasks.
+
+- **tasks/lifeCycle**
+   This endpoint executes lifecycle task objects defined within **FusionDirectory**. Based on task configuration, it evaluates whether a specified Supann resource has reached expiration and performs actions accordingly.
+
+- **tasks/activateCyclicTasks**
+   Activates all repetitive tasks based on their defined recurrence schedules.
+
+- **tasks/removeSubTasks**
+   Removes all sub-tasks marked as completed.
+   All sub-tasks status can be seen within FusionDirectory dashboard.
+
+- **tasks/reminder**
+   Executes reminder task objects and sends emails to specified groups or individuals. Based on configuration, it can generate tokens for potential account extensions.
+
+- **tasks/notifications**
+   Triggers the execution of notification task objects. Any changes to the supplied attributes result in email notifications being sent to the designated individuals or groups.
+
+- **tasks/audit**
+   This endpoint allows for the deletion of historical audit logs based on a retention period specified in the task configuration within **FusionDirectory**.

source/fusiondirectory-orchestrator/endpoints/index.rst

-FusionDirectory Orchestrator Endpoints
-======================================
-
+Endpoints
+=========
 
 .. toctree::
    :maxdepth: 2
 
-   tasks/index.rst
+   description.rst
+   lifecycle.rst
+   notifications.rst
+   userreminder.rst
+   audit.rst
+   mails.rst

source/fusiondirectory-orchestrator/endpoints/lifecycle.rst

+Life cycle Task Execution
+==========================
+
+.. _lifecycle-task-execution-label:
+
+Once the task is configured, execute it using the **orchestrator-client** tool. You have two execution options:
+
+.. code-block:: bash
+
+   fusiondirectory-orchestrator-client --lifecycle
+
+.. note::
+   **Recommendation** automate this process within a CRON job.
+
+.. note::
+  Add the ``--verbose`` flag to the command for detailed output during execution.
+
+
+.. note::
+    The logs are stored by default at the following location:
+
+    ``/var/log/orchestrator/orchestrator.log``
+

source/fusiondirectory-orchestrator/endpoints/mails.rst

+Mail Task Execution
+===================
+
+.. _mail-task-execution-label:
+
+Once the task is configured, execute it using the **orchestrator-client** tool. You have two execution options:
+
+.. code-block:: bash
+
+   fusiondirectory-orchestrator-client --emails
+
+.. note::
+   **Recommendation** automate this process within a CRON job.
+
+.. note::
+  Add the ``--verbose`` flag to the command for detailed output during execution.
+
+
+.. note::
+    The logs are stored by default at the following location:
+
+    ``/var/log/orchestrator/orchestrator.log``
+

source/fusiondirectory-orchestrator/endpoints/notifications.rst

+Notifications Task Execution
+============================
+
+.. _notifications-task-execution-label:
+
+Once the task is configured, execute it using the **orchestrator-client** tool. You have two execution options:
+
+.. code-block:: bash
+
+   fusiondirectory-orchestrator-client --notifications
+
+.. note::
+   **Recommendation** automate this process within a CRON job.
+
+.. note::
+  Add the ``--verbose`` flag to the command for detailed output during execution.
+
+
+.. note::
+    The logs are stored by default at the following location:
+
+    ``/var/log/orchestrator/orchestrator.log``
+

source/fusiondirectory-orchestrator/endpoints/tasks/description.rst

-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.

source/fusiondirectory-orchestrator/endpoints/tasks/functionalities.rst

-
-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.

source/fusiondirectory-orchestrator/endpoints/tasks/index.rst

-Orchestrator Mail Task
-======================
-
-.. toctree::
-   :maxdepth: 2
-
-   description.rst
-   functionalities.rst

source/fusiondirectory-orchestrator/endpoints/userreminder.rst

+Reminder Task Execution
+=======================
+
+.. _reminder-task-execution-label:
+
+Once the task is configured, execute it using the **orchestrator-client** tool. You have two execution options:
+
+.. code-block:: bash
+
+   fusiondirectory-orchestrator-client --reminder
+
+.. note::
+   **Recommendation** automate this process within a CRON job.
+
+.. note::
+  Add the ``--verbose`` flag to the command for detailed output during execution.
+
+
+.. note::
+    The logs are stored by default at the following location:
+
+    ``/var/log/orchestrator/orchestrator.log``
+

source/fusiondirectory-orchestrator/install/centos/centos-orchestrator-install.rst

@@ -10,6 +10,14 @@ All The needed dependancies are resolved by the centos packages
 Install FusionDirectory Orchestrator 
 ''''''''''''''''''''''''''''''''''''
 
+.. note::
+
+    You must at least be running PHP 7.4
+
+.. code-block:: shell
+
+    yum-config-manager --enable remi-php74
+
 You can then install Orchestrator by running: 
 
 .. code-block:: shell
@@ -29,9 +37,5 @@ We can easily do this by running:
 
    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
-