Manage AtoM configuration files¶

config/app.yml¶

This is the primary file where AtoM-specific settings that cannot be managed via the user interface are maintained. This file includes settings such as:

• upload_limit: Global digital object upload limit (in gigabytes) - can be set to -1 for unlimited, or set to a specific limit in GBs.
• download_timeout: Timeout limit for fetching digital objects from external services (in seconds) - default value is 10s. See also: PHP execution limits.
• cache_engine: Which cache engine you want to use (can use Memcached for a distributed cache, for example) - default is sfAPCCache
• read_only: Enable read-only mode, if you want to remove the login button and prevent users from logging into the application. See also: Making AtoM read-only.
• google_analytics_api_key: Set a Google Analytics API key, for basic installation-wide analytics via Google - see: Web analytics
• google_analytics_institutions_dimension_index: Set a custom dimension via Google Analytics to allow for per-institution page view counts in a multi-repository system. See: Google Analytics for tracking institutional pageviews
• google_tag_manager_container_id: Set a Google Tag Manager API key, for further element-specific analytics. See: Google Tag Manager
• htmlpurifier_enabled: Enable htmlpurifier - limits HTML on static pages to a white-list of approved elements and attributes, to prevent XSS. See: Static pages and security configuration.
• workers_key: Allows setting a custom key that will add a unique hash to the Gearman atom-worker, to avoid conflicts when multiple AtoM installations are co-tenanted on the same server.
• treeview_items_per-page_max: Increase the maximum allowed value for the full-width treeview paging limit - see: Items per page

Important

Symfony (the PHP framework that AtoM uses) has a cascading system of priorization for configuration files - if you create an app.yml file in apps/qubit/config/, its settings will override those found in config/app.yml. This can be useful if you want to change some configuration values without actually altering AtoM’s installation defaults - Artefactual uses this method for automated deployment via Ansible, for example.

If your settings changes aren’t taking effect in config/app.yml and you’ve already cleared the cache and restarted php-fpm, you might want to double-check to make sure you don’t have a file in apps/qubit/config/app.yml overriding the other configuration file. If you are using the Vagrant box for example, you will have this extra config file, since Artefactual uses Ansible to automate the build of the Vagrant box.

There are also some settings in this file (such as the read_only setting) that may be overwritten by environment variables in the PHP pool set up during installation. For general information, see below, Application server. For specific information on setting up read-only mode in AtoM, see:

• Making AtoM read-only

Back to top

apps/qubit/config/settings.yml¶

• Symfony and PHP settings - see the Symfony documentation for more general information: http://symfony.com/legacy/doc/reference/1_4/en/04-Settings
• For things like default_culture, default_timezone, login_module, etc
• Includes settings for error handling behavior as well - be careful changing these! We don’t recommend it.

Back to top

config/factories.yml¶

• Another Symfony 1.x configuration file
• More details at: http://symfony.com/legacy/doc/reference/1_4/en/05-factories
• Useful for changing logging options, user class (e.g. LDAP or CAS), etc
• We don’t recommend changing this file unless you know what you’re doing!
• See: Logging for some ideas on how to work with these settings to change or improve logging in AtoM

Back to top

config/config.php¶

• Where basic configuration information for database access is stored, such as the database user, pass, and name
• We don’t recommend changing this file unless you know what you’re doing!

Back to top

config/sitemap.yml¶

This configuration file is used in conjunction with the sitemap generation command-line task - for more information, see: Generate an XML sitemap for search engine optimization.

This file contains the priorities (or weighting) for each level of description of archival descriptions included in the sitemap the CLI task will generate. If you have added new levels of description to the Levels of description taxonomy, you can give them a priority here, or adjust the default priorities included in the file (shown in the image below).

Back to top

config/search.yml¶

This configuration file is used to configure Elasticsearch (ES), the search index used in AtoM, including:

• The host and port of your Elasticsearch index, configured during installation via the command-line installer
• The normalizers, analyzers and filters used by Elasticsearch. See the Elasticsearch documentation for more information on these, and be sure you are looking at the documentation for the correct ES version
• Number of shards and replicas created - these are paramters used for performance optimization and scalability. See the Elasticsearch documentation for more information
• The tokenizers and filters used per culture - these can be useful to adjust when trying to improve AtoM’s multilingual search for a specific language. See the Elasticsearch documentation for more information. This includes whether or not stop words are being filtered for a particular language.

There are also two additional global configuration settings worth mentioning, that can be customized as needed. Be aware that making changes can increase the size of your ES index and require more resources (memory, disk space, etc) if changed.

The first value is the index.mapping.total_fields.limit. This setting defines the maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. By default in new AtoM installations, this value is set to 3000. In particularly large installations it’s possible that this default value is not high enough to support a full index of your data. You will know this is the case if you encounter a message like the following message when attempting to run the Populate search index command:

Limit of total fields [3000] in index [atom] has been exceeded

The second value is the index.max_result_window setting. By default Elasticsearch sets a limit on the number of results returned, since these impact the amount of heap memory required for your search index. This value is set to 10,000 in AtoM by default in new installations.

This means that, in the event that there are more than 10,000 results to return when searching or browsing, AtoM will stop loading results after the limit is reached, to preserve memory capacity, and the user will see the following message:

Users can use the sort direction options in the Sort buttons available on search and browse pages to reverse the sort direction and view results from the end of the list. However, if desired, a system administrator can increase the index.max_result_window value to allow more results to be accessed before the limit is reached. Be aware that this will impact memory usage!

If you make any changes to the search.yml file, you should:

• Run the Populate search index command
• Run the Clear cache command
• Restart PHP-FPM

Back to top

plugins/arCasPlugin/config/app.yml¶

This file contains additional parameters that can be used to configure the CAS single sign-on authentication plugin. For more information, see:

• Enabling CAS authentication

Values that can be configured here include:

• cas_version can be set to 1.0, 2.0, or 3.0. For more information, see: https://apereo.github.io/cas/5.2.x/protocol/CAS-Protocol.html
• You can configure the connection to your CAS authentication server by adjusting the server_name, server_port, and server_path values
• The location of your CAS server’s SSL certificate can be configured. By default in a new installation, the server_cert parameter is set to false. While CAS server SSL validation can be disabled for development, we strongly discourage doing so in a production environment.
• You can configure AtoM user groups to match your CAS user attributes using the set_groups_from_attributes parameter, adjusting the attribute_key that should be used, and configuring the various user_groups values to match your CAS group IDs. For more information, see: Setting AtoM group membership from CAS user attributes.

For further details on basic configuration, see the Administrator’s manual:

• User authentication

There is one other parameter worth mentioning in this file: the service_url variable. This setting lets a system administrator specify the AtoM site URL that the CAS server should use when responding to authentication requests, regardless of where the user originates. This can be useful when multiple domain names with redirects are used for your AtoM site for example, or when the hostname does not match the host part of the AtoM instance URL.

By default, the CAS server will redirect users back to the URL from which the request originated, but this may not always work as expected when there are different domains or subdomains used, and can break the authentication procedure.

To avoid this, system administrators can use the service_url parameter to specify the perferred service URL for your AtoM site that the CAS server should redirect users to after successfully completing authentication.

Example:

service_url: https://atom.somedomain.org/cas/login

Back to top

Security configuration files¶

AtoM includes the ability for an administrator to create and manage user accounts, add them to groups, and configure permissions per user or per group. For more information, see:

• Manage user accounts and user groups
• Edit permissions

However, there are some default permissions that are set in AtoM on a per-group basis that do not currently have granular and customizable permissions settings available via the user interface. In some cases, the default access permissions can be modified via a number of security.yml configuration files found in AtoM.

These security configuration files control application routing - meaning they are applied during page requests, and before any application code is loaded for the page in question. In some case, a system administrator can adjust these files to restrict or provide access to modules on a per-group basis.

Basic file structure

Below is an example default configuration file - this example is for access to the taxonomies, and is located at apps/qubit/modules/taxonomy/config/security.yml.

browse:
  credentials: [[ editor, administrator ]]

list:
  credentials: [[ editor, administrator ]]

index:
  is_secure: false

autocomplete:
  is_secure: false

all:
  is_secure: true

Each security YAML file will include a list of component parameters, and related default permissions. When all includes is_secure: true as a nested value, this means that by default all relevant components will have a permissions check applied and routing access will be restricted to any listed user groups, unless otherwise declared. In the example above, the autocomplete search results for taxonomy terms includes an is_secure: false key/value pair, which overrides the global all variable for that particular component. The ability to browse the taxonomies, and see the view page for a particular taxonomy (list) has been restricted by default to the editor and administrator user groups.

When just one user group is granted access to a particular component, it can be listed immediately after the component name, like this example:

import:
  credentials: administrator

To list multiple groups, enclose the group names in two sets of square brackets and use commas to separate user group names. If you have created custom groups, you can add custom group permissions for them to these configuration files by including the exact form of name of the group, like so:

import:
  credentials: [[ editor, mycustomgroup, administrator ]]

As with all configuration files, if you make any changes, clear the application cache and restart PHP-FPM to apply the changes.

• Clear cache
• Restarting PHP-FPM

Below is a list of some of the key security configuration files available in AtoM. This list is not comprehensive. Not covered below are some files that relate to the underlying Symfony framework (and should not be altered), configuration files for optional plugins (like the arStorageServicePlugin used for Archivematica integration), and other files that are not easily configured to be accessible to other groups via the user interface.

Jump to:

• Import security configuration
• Accession record security configuration
• Description updates security configuration
• Physical storage security configuration
• Manage menus security configuration
• Taxonomy security configuration

Important

While permission to perform certain actions can be modified on a per-group basis by changing these configuration files, control of main menu nodes such as the Admin and Import menus is set via code, and is restricted by default to the administrator group.

However,an administrator can use the Manage Menus module to add links in other menus that the designated group can access, such as the Manage menu, as shown in the example configuration below for granting access to Editors to the CSV import module:

For more information on import security configuration, see below. In the example above, the editor group would need to be added to both the import and importSelect options in the related security.yml file.

Back to top