Manage AtoM configuration files¶
Many settings in AtoM can be managed directly through the user interface via the Admin > Settings menu (see: Settings for details). However, there are also several configuration files maintained in AtoM’s code where various settings and configurations can be managed, and which can be edited directly by a user via the command-line. These files can be useful for customizing the behavior and performance of your application. Details on each have been included below.
The Symfony PHP framework that AtoM uses uses a configuration cascade - meaning it will look for configuration files in multiple locations in a specific order, and the final configuration will be compiled from all found configuration files in a specific order of preference. See the Symfony documentation for more information:
The locations of the configuration files listed below are the default locations used in a standard installation using the downloadable tarball package provided on the Access to Memory website’s Downloads page.
However, depending on your installation method (or if you are using an
Artefactual-provided development environment like the AtoM
Vagrant box), these files may appears in different
locations, such as in the
An example: The Elasticsearch search.yml config file
Before installation, the default version of the
file is found in the Elasticsearch (ES) plugin in
This default file is typically copied to its new location once the installer is run as part of the installation process.
If installing via the Artefactual provided downloadable tarball, the new location will typically be:
Making configuration changes
Symfony will compile the settings found in all applicable configuration files, in a specific order of preference. This means that one file will not completely override the other - instead, priority file location values will be favored, but where a configuration setting is not found for a particular parameter in the preferred location, Symfony will check the next location for a relevant parameter.
If a particular parameter exists in multiple files but has different values, then the cascade order preference will determine which setting value takes effect.
If you are uncertain where to make your changes, you can always make them in all relevant configuration files to ensure the changes will take effect as expected.
How to change values in configuration files¶
From AtoM’s root directory, use the
nano command to open a file for editing
You can save changes with
CTRL+O + ENTER, and exit with
will be asked to save if you haven’t yet).
If you change any of the files listed below, clear the cache and restart PHP-FPM to apply the changes.
Important configuration files¶
Below is a list of some of the configuration files available in AtoM that you may need to adjust as a system administrator.
- Security configuration files
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
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
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
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:
- 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.
- 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
- 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!
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).
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  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:
This file contains additional parameters that can be used to configure the CAS single sign-on authentication plugin. For more information, see:
Values that can be configured here include:
cas_versioncan 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
- The location of your CAS server’s SSL certificate can be configured. By
default in a new installation, the
server_certparameter 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
set_groups_from_attributesparameter, adjusting the
attribute_keythat should be used, and configuring the various
user_groupsvalues 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:
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
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.
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:
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.
As these security configuration files control routing and not access control,
in some cases, access control checks may be hard-coded into the application
code for particular pages, and while changing the related
file may allow a member of a different user group to navigate to a previously
restricted page, ACL checks in the page may still restrict access upon
An example of this would be the Accession record security configuration described
below. The security configuration file contains
parameters, but application code ACL checks currently limit view, create,
edit, and delete permissions to the administrator and editor groups.
This means that if you wanted to allow another user group to view and
edit accession records, updating the
security.yml file alone would not
suffice - you would also need to make changes to the application code.
Basic file structure
Below is an example default configuration file - this example is for access to
the taxonomies, and is located at
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
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.
In general, we don’t recommend changing the global
As always when making configuration and code changes, we strongly recommend that you make a back up of your data before proceeding and test thoroughly before any changes on a production instance!
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 ]]
To avoid any errors or unexpected outcomes during this configuration, we recommend that custom group names do not include spaces or special characters.
As with all configuration files, if you make any changes, clear the application cache and restart PHP-FPM to apply the changes.
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
used for Archivematica integration), and other files that are not
easily configured to be accessible to other groups via the user interface.
- Import security configuration
- Accession record security configuration
- Description updates security configuration
- Physical storage security configuration
- Manage menus security configuration
- Taxonomy security configuration
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
group would need to be added to both the
options in the related
Import security configuration¶
- File location:
This file controls the options for import and validation, including:
import: Sets access to run CSV and XML imports
importSelect: Sets access to the import configuration page
validateCsv: Sets access to run CSV validation jobs
Accession record security configuration¶
- File location:
This file controls the ability for user groups to manage accession records. See:
browse: Sets access to the Accessions browse page. Also controls whether a link to the browse page will be available to the relevant user group in the Manage menu.
edit: Sets access to the ability to edit existing accession records
There is another parameter not listed here, which could be manually added:
index will control the routing to access the view page of
Currently, access to accessions is limited via application code to the Administrator and Editor user groups. See:
A developer would need to modify the permissions check in the link above to allow additional groups to access and modify accession records.
Description updates security configuration¶
- File location:
The Description Updates module, normally restricted to the administrator user group, is designed to help authorized users identify new and recently modified records in the system. For more information, see:
By making modifications to this security configuration file and adding a link to the Description Updates page to a different main menu node that all necessary user groups can access, it’s possible to allow others to use this module as well for administration of the site and its metadata.
descriptionUpdates: Sets access to the Description Updates page
globalReplace: This is an outdated module that is currently not operational in AtoM, and should not be modified.
Physical storage security configuration¶
- File location:
This file controls the ability for user groups to access and manage physical storage containers and locations. For more information, see:
Based on the default permissions configured in this file, contributors can view individual storage records from associated links on related archival description or accession records. Translators have the same access, but can also edit those containers they can access via this method, to be able to add translations. Editors and Administrators can browse, view, edit, and delete storage records.
autocomplete: Sets access to viewing matching containers when linking physical storage to other entities via the available autocomplete. See: Link physical storage.
boxList: Sets access to the box list report, avaiable by clicking on the printer icon on the view page of the related storage container. For more information, see: Create physical storage report for a single container.
browse: Sets access to the physical storage browse page
delete: Sets access to the ability to delete physical storage containers and locations
edit: Sets access to the ability to edit existing storage containers, or add new ones
index: Sets access to the view page of individual storage containers.
Static page security configuration¶
- File location:
This file controls the ability for user groups to access and manage static pages in AtoM. For more information, see:
By default, static pages are publicly visible - however, the link to the management page for static pages is included by default in the Admin menu, and the default configuration of this security file limits edit and browse permissions to the administrator and translator user groups, and delete permissions to the administrator group.
delete: Sets access to the ability to delete existing static pages. Note that some static pages, such as the Home page, cannot be deleted, just modified.
edit: Sets access to the ability to modify existing static pages, and create new ones
list: Sets acess to the browse page for existing static pages.
While modifying the
edit parameters can allow additional
user groups to browse existing static pages and create new ones, currently
the ability to edit or delete existing static pages is restricted via
application code to the administrator user group. See:
A developer would need to modify the permissions check in the link above to allow additional groups to modify and delete static pages.
Taxonomy security configuration¶
- File location:
This file controls the routing access to exploring the various taxonomies in AtoM, used to maintain controlled vocabulary terms used in drop-down menus in AtoM’s edit page forms, or in some cases as access points. For more general information on taxonomies and terms, see:
At installation, a link to the taxonomies browse page is available in the Manage menu, and the default configuration of this file allows browse and view access to the editor and administrator user groups.
We recommend making your taxonomy permission changes there first, and only modifying this security configuration file if access is not working as expected.
browse: Deprecated. Sets access to the list of taxonomies.
list: Sets access to the list of taxonomies
index: Sets access to the view page for a taxonomy
autocomplete: Sets access to matching term results showing up in autocomplete results from the global search box or when linking terms in related edit pages. Note that separate application code filters this list so that only subject and place access points are currently included as possible autocomplete matches in the global search.
Remember that Nginx is just the HTTP frontend. Internally, each request is forwarded to php-fpm. php-fpm is a pool of managed AtoM processes. The pool has its own configuration file that defines some important global PHP settings like timeouts, and environment variables that may also modify the way that AtoM works as documented in accesstomemory.org.
The file of the pool is located at
nano. Once saved, run:
sudo systemctl restart php7.4-fpm, and the
changes will apply.