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

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

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”