#################
Technical Details
#################

Database
========

The underlying PixStor Management database uses SQLite3

In PixStor Management 0.3 and earlier, the database was located at ``/mmfs1/.arcapix/apmgmt.db`` [#]_

As of PixStor Management 0.4, the database is located at ``/mmfs1/.arcapix/apmgmt/apmgmt.db``

Job Engine
==========

When a change is made via the REST API, a task is submitted to the job engine, to be executed asynchronously.

The default job engine is PixStor Schedulers. Tasks are submitted to Schedulers via its own REST API.

Run as User
-----------

Jobs, which make changes to the filesystem, are run as the user who triggered the job.

For example, if a user is authenticated as ``pixadmin``, then the job will be run as user ``pixadmin``.

Therefore, that user must have appropriate permissions, such as sudo permission or read/write permission for any relevant files or directories.
PixStor Management (by way of PixStor) maintains a 'sudoers' configuration which assigns relevant permissions to users,
based on their rights and roles.

Shares
======

NFS and Samba shares are represented in the PixStor Manamgenent :doc:`object model <orm>` as 'exposers';
``NFSExposer`` and ``CIFSExposer``, respectively.

.. note::

    In a multi-node cluster, PixStor Management requires that share definitions are identical across all nodes.

Pix-Managed Shares
------------------

Prior to PixStor Management 0.5 (PixStor 5.1.5.1), all share definitions were in the default share config files

    - nfs: ``/etc/exports``
    - samba: ``/etc/samba/smb.conf``

For PixStor Management 0.5+, shares created or edited using the REST API (or Admin UI) are ‘pix-managed’.
Pix-managed shares are stored, one-per-file, in

    - nfs: ``/etc/exports.d``
    - samba: ``/etc/samba/apmgmt/``

the files in ``/etc/samba/apmgmt/`` are merged into a single file, ``/etc/samba/apmgmt.conf``,
so that they can be included in the main ``smb.conf``

Each of these pixmanaged files is named like ``pixmanaged.<uuid>.conf``, where uuid is the id of the share in PixStor Management.

This approach is intended to work around issues with e.g. managing user permissions on config files.

Shares created by manually editing the main configs ``/etc/exports`` or ``/etc/samba/smb.conf`` are not pix-managed.
However, if you edit one of these unmanaged shares via the REST API (or Admin UI), it will be converted into a pix-managed share.
This means it is removed from the main config and written to a pix-managed files.

.. note::

    If an unmanaged share is created or editted directly, PixStor Management must be re-populated to pick up the change.

    PixStor is typically configured to automatically populate every 5 minutes. It can also be populate on demand, with the command

    .. code-block:: console

        adminctl populate now

.. _placement_rules:

Placement Policy Rules
======================

PixStor Manamgenent needs to create some placement policies - one per data pool (per filesystem).
This is used to ensure space (fileset) data is assigned to the desired datastore (pool)

If any placement rules are missing, they can be installed with

.. code-block:: console

    adminctl policy install default
    adminctl populate now --conditional


No default placement policy
---------------------------

The above command will not install placement rules for any policy which is missing a default placement rule.
In that case, populate will display a warning like

.. code::

    Can't populate profiles for mmfs1 - [AP000000117X] Filesystem mmfs1 has no default placement policy - skipping

Check the current policy with

.. code-block:: console

    mmlspolicy mmfs1 -L

A default placement rule looks like

.. code::

    RULE 'default' SET POOL 'system'

If it’s missing, one will need to be created.

For more details, see ``man adminctl-providers-box``

----

.. rubric:: Footnotes

.. [#] or under the equivalent primary filesystem mountpoint