##################
Command Line Tools
##################

The main command line tool for PixStor Management is ``adminctl``.

This provides sub-commands for performing various administration operations.

For more details, see the manpages - ``man adminctl``


Populate Tools
==============

adminctl populate
-----------------

Populate builds the management database based on the current state of the cluster.

If the database doesn't exist or is empty, it will be populated from scratch.
If the database already exists, it will be 'reconciled' to bring it into line with the current state of the cluster.

**populate now** performs the populate/reconcile operation immediately.
If the configured database doesn't exist, it will be created.

.. code-block:: shell

    adminctl populate now

By default, database entries which are not ``ACTIVE`` - e.g. which are ``ERRORED`` or ``PENDING`` - won't be reconciled.
So if, for example, a space is in state ``ERRORED`` but the corresponding fileset wasn't created or has been manually deleted,
populate will not remove it from the database.

This is to prevent removing things which are ``PENDING`` or ``INPROGRESS``, as this would interfere with jobs,
and to prevent removing ``ERRORED`` things so that they can be retried.

**populate rebuild** makes the database match the state of the filesystem exactly.

.. code-block:: shell

    adminctl populate rebuild

This means entries which don't have a corresponding filesystem object (spaces without filesets, etc.)
will be removed from the database, regardless of their state.

.. important::

    This should not be run if there are any currently ``PENDING`` or ``INPROGRESS`` items.


For more details, see ``man adminctl-populate``

adminctl policy install
-----------------------

Creates PixStor policy rules, which will be used by PixStor Management.

**default** will create a default placement rule for each data storage pool on each filesystem.
If the policy rules already exist, the command will do nothing.

.. code-block:: shell

    adminctl policy install default

The **default** placement rules are required by PixStor Management to be able to perform basic operations, such as creating filesets.
For more details, see :ref:`placement_rules`

For more details, see ``man adminctl-policy-install``

Provider Tools
==============

adminctl providers box
----------------------

Tools for Box.com replication providers

**list** will list the names and ids of currently configured Box.com providers.

.. code-block:: shell

    $ adminctl providers box list

    ID                                    NAME     ACCOUNT
    --------------------------------------------------------
    c06ecf6f-84f8-4e51-8d3f-334f71f2f8f3  box-vfx  box_admin

This is intended only to be used to identify provider ids for use with **refresh**.
The PixStor Management REST API should be used to view full provider details.

**refresh** will refresh the authentication tokens for the Box.com accounts
associated with one or more replication providers.

.. code-block:: shell

    $ adminctl providers box refresh c06ecf6f-84f8-4e51-8d3f-334f71f2f8f3

    NOTIFY: Refreshing tokens for Box account box_admin
    NOTIFY: Successfully refreshed 1 providers

Under normal operation, the tokens should be kept up-to-date by the replication process, i.e. PixStor BoxSync.
However, if sync is not active for more than ~1 hour, the access token may expire.

This tool allows for refreshing tokens without having to fully re-authenticate the associated Box account.