######################## Configuration Directives ######################## ======== Overview ======== The PixStor Management REST API is controlled by various configuration directives. These are represented in a filesystem heirarchy, and manifest themselves as dot seperated properties. The content of the actual property values is JSON formatted. More complex properties (e.g. dicts/maps) are also used for some properties. .. important:: It is especially important to note that raw strings are NOT valid JSON, therefore all string values must be appropriately quoted The base location for PixStor configuration values is ``/opt/arcapix/etc`` (see below). Thus, to set the value of ``arcapix.auth.server.url`` to ``https://localhost/`` one would write a file containing precisely .. code-block:: JSON "https://localhost/" into ``/opt/arcapix/etc/arcapix/auth/server/url`` Location -------- The default location for configuration values is ``/opt/arcapix/etc/``. However, this can be overridden by setting the ``ARCAPIX_CONFIG`` environment variable to point to a suitable directory - this may be useful for example to centralise configuration values. Defaults -------- The system does not have any "default" values - all configuration values must be explictly set. Using Python to write the config values --------------------------------------- One of the most convenient methods for setting configuration values is to use the supplied python library. .. code-block:: Python from arcapix.config import config config["arcapix.auth.server.url"] = "https://localhost" ======================== Configuration properties ======================== The following properties are currently defined for search. .. note:: there may be other properties present in the ``/opt/arcapix/etc/`` heirarchy - these are for other PixStor products not connected with the management API arcapix.auth.server.url ------------------------ This value defines the server which the management server can use to verify access tokens. This server _should_ use https: rather than http:, but this is not mandated. ======================= ========================================================================================================================================================== Type String Suggested default value "https://localhost" (This url will have /oauth2/token_info appended to it automatically.) ======================= ========================================================================================================================================================== arcapix.management.database.path -------------------------------- Absolute path to the management SQL database file ======================= ========================================================================================================================================================== Type String Suggested default value "/mmfs1/.arcapix/apmgmt.db" ======================= ========================================================================================================================================================== arcapix.management.database.reconcile.every ------------------------------------------- The frequency at which database reconcile runs, in seconds. When the REST server is started, a database reconcile job is put in the job engine. This job makes sure the database stays in sync with the state of the filesystem. Note - if you change this config, you will need to restart the REST server for the change to take effect. ======================= ========================================================================================================================================================== Type Integer Suggested default value 300 (every 5 minutes) ======================= ========================================================================================================================================================== arcapix.management.filesets.allocinodes --------------------------------------- The default number of inodes to allocate to new independent filesets You can specify the number of inodes to allocate to an independent fileset (space) by specifying ``extras['gpfs.fileset.allocinodes']`` when creating a space. If that isn't specified, then the value of this config will be used as the default. ======================= ========================================================================================================================================================== Type Integer Suggested default value 10000 ======================= ========================================================================================================================================================== arcapix.management.filesets.maxinodes ------------------------------------- The default maximum number of inodes to set for new independent filesets You can specify the max number of inodes for an independent fileset (space) by specifying ``extras['gpfs.fileset.maxinodes']`` when creating a space. If that isn't specified, then the value of this config will be used as the default. ======================= ========================================================================================================================================================== Type Integer Suggested default value 20000 ======================= ========================================================================================================================================================== arcapix.management.filesets.quota_soft_ratio -------------------------------------------- When a size is specified when creating or updating a space, a quota will be created. The quota hard block limit will be set to the provided size. This config defines the relative size of the quota soft block limit. For example, if the size is 1000 and the ``quota_soft_ratio`` is 0.9, then the quota hard limit will be set to 1000 and the soft limit will be set to 900. ======================= ========================================================================================================================================================== Type Float Suggested default value 0.9 ======================= ========================================================================================================================================================== arcapix.management.filesets.exclude ----------------------------------- List of names of filesets that should be excluded from being ingested ======================= ========================================================================================================================================================== Type List of strings Suggested default value ['root'] ======================= ========================================================================================================================================================== arcapix.management.filesystems.exclude -------------------------------------- List of names of filesystems that should be excluded from being ingested ======================= ========================================================================================================================================================== Type List of strings Suggested default value ['apfs'] ======================= ========================================================================================================================================================== arcapix.management.shares.migration_mode ---------------------------------------- If a share is created via PixStor Management, it is considered to be 'pixmanaged'. If it was populated from the system share configs - typically ``/etc/smb/samba.conf`` and ``/etc/exports`` - it is not pixmanaged. Any manual changes made to pixmanaged shares (i.e. by editing their config files) may be reverted. This config controls what happens if a user attempts to modify or delete a non-pixmanaged share. If ``never``, non-pixmanaged shares are treated as immutable, and any attempt to change them via PixStor Management will result in an error. If ``auto``, any attempt to change a non-pixmanaged share will cause it to be converted into a pixmanaged share. This means that it will be removed from the system share config. It also means that it can no longer be manually edited. There is no functionality for converting a pixmanaged share back to a non-managed share. ======================= ========================================================================================================================================================== Type String Suggested default value auto ======================= ========================================================================================================================================================== arcapix.management.shares.validate_path --------------------------------------- When creating new NFS or SMB shares, or when populating existing shares, the share path will be validated to check that it exists. This behaviour may not be desirable, if the user creating/populating the share doesn't have permission to see the path, or if the path is temporarily unavailable. By setting this config to False, validation will be disabled, allowing shares to be created/populated with any (non-null) path. ======================= ========================================================================================================================================================== Type Boolean Suggested default value true ======================= ========================================================================================================================================================== arcapix.management.tasks.loglevel --------------------------------- Logging level to apply to tasks. Can be any valid PixStor logging level - debug, verbose, info, audit, notify, warning, error, critical This controls what logging messages will be visible in the scheduler logs; either via the REST API or the Admin UI. ======================= ========================================================================================================================================================== Type String Suggested default value notify ======================= ========================================================================================================================================================== arcapix.management.templates.max_size ------------------------------------- Maximum size for a template source, in bytes. If the source directory for a new template is bigger than the configured limit, an error will be raised, the template source won't be ingested, and the template will be set to status ERRORED This also applies to updates, where the template location is changed to a new directory which exceeds the max size. If no limit is configured, a template source can be any size. Note - this limit is not applied to already existing templates. ======================= ========================================================================================================================================================== Type Integer Suggested default value null ======================= ========================================================================================================================================================== arcapix.management.templates.store ---------------------------------- Fully qualified path to a directory, in which templates will be stored. ======================= ========================================================================================================================================================== Type String Suggested default value "/mmfs1/.arcapix/templates" ======================= ========================================================================================================================================================== arcapix.management.tools.adminctl.populate.lock ----------------------------------------------- Fully qualified path to a file to use as the database lock. The database lock prevents multiple invocations of ``adminctl populate now`` running concurrently. This allows, for example, a recurring populate to be scheduled in cron to keep the database up-to-date with the filesystem. Note - this path must be writable by any user who might run populate ======================= ========================================================================================================================================================== Type String Suggested default value "/mmfs1/.arcapix/apmgmt/dbreconcile.lck" ======================= ========================================================================================================================================================== arcapix.schedulers.server.endpoint ---------------------------------- This value defines the endpoint for the PixStor Schedulers REST api, relative to the server (see below) This should include leading and trailing slashes. ======================= ========================================================================================================================================================== Type String Suggested default value "/jobs/" ======================= ========================================================================================================================================================== arcapix.schedulers.server.url ----------------------------- This value defines the server which the management server can use to submit jobs to PixStor Schedulers. ======================= ========================================================================================================================================================== Type String Suggested default value "https://localhost" ======================= ========================================================================================================================================================== executables.csync2 ------------------ Absolute path to the ``csync2`` executable. csync2 is used to synchronise nfs and smb configuration files across the cluster ======================= ========================================================================================================================================================== Type String Suggested default value "/usr/sbin/csync2" ======================= ========================================================================================================================================================== shares.managed.nfs ------------------ Absolute path to the (local) filesystem's directory of pixmanaged nfs configuration files. This will be synced across the cluster using csync2 The directory contains config files for shares created via the PixStor Management REST API. The PixStor Management shares will be prefixed with ``pixmanaged.`` This directory may contain other share configs, but they will be treated as 'readonly' by PixStor Management. .. important:: These files should not be edited manually. ======================= ========================================================================================================================================================== Type String Suggested default value "/etc/exports.d/" ======================= ========================================================================================================================================================== shares.managed.smb ------------------ Absolute path to the (local) filesystem's directory of pixmanaged samba configuration files. This will be synced across the cluster using csync2 The directory contains config files for shares created via the PixStor Management REST API. The PixStor Management shares will be prefixed with ``pixmanaged.`` This directory may contain other share configs, but they will be treated as 'readonly' by PixStor Management. .. important:: These files should not be edited manually. .. note:: The system samba config must include ``include = /path/to/configs/*.conf`` in the ``[global]`` section for samba to discover those configs ======================= ========================================================================================================================================================== Type String Suggested default value "/etc/samba/apmgmt/" ======================= ========================================================================================================================================================== shares.nfs ---------- Absolute path to the (local) filesystem's system nfs configuration file. Shares loaded from this file are 'immutable' and can't be modified or deleted via the PixStor Management REST API ======================= ========================================================================================================================================================== Type String Suggested default value "/etc/exports" ======================= ========================================================================================================================================================== shares.smb ---------- Absolute path to the (local) filesystem's system smb configuration file. Shares loaded from this file are 'immutable' and can't be modified or deleted via the PixStor Management REST API ======================= ========================================================================================================================================================== Type String Suggested default value "/etc/samba/smb.conf" ======================= ==========================================================================================================================================================