Dashboard Administration tab¶

Using a custom processing configuration file¶

For more advanced workflows, you may wants to create multiple processing configurations - for example, along with the default config, users might want to have a configuration specific to video files. You can add a new processing configuration through the user interface by clicking on the Add button.

Once you have created a custom processing configuration, you can download the XML file by clicking on Download. Rename this file processingMCP.xml. Then place this file in the root directory of the transfer. Archivematica will now use the included file to make processing decisions, rather than the default configuration.

The processingMCP.xml follows a specific XML format:

<processingMCP>
 <preconfiguredChoices>
     <!-- Display metadata reminder -->
     <preconfiguredChoice>
         <appliesTo>eeb23509-57e2-4529-8857-9d62525db048</appliesTo>
         <goToChain>5727faac-88af-40e8-8c10-268644b0142d</goToChain>
     </preconfiguredChoice>
     <!-- Extract packages -->
     <preconfiguredChoice>
         <appliesTo>dec97e3c-5598-4b99-b26e-f87a435a6b7f</appliesTo>
         <goToChain>01d80b27-4ad1-4bd1-8f8d-f819f18bf685</goToChain>
     </preconfiguredChoice>
     <!-- Delete extracted packages -->
     <preconfiguredChoice>
         <appliesTo>f19926dd-8fb5-4c79-8ade-c83f61f55b40</appliesTo>
         <goToChain>85b1e45d-8f98-4cae-8336-72f40e12cbef</goToChain>
     </preconfiguredChoice>
     <!-- Select pre-normalize file format identification command -->
     <preconfiguredChoice>
         <appliesTo>7a024896-c4f7-4808-a240-44c87c762bc5</appliesTo>
         <goToChain>3c1faec7-7e1e-4cdd-b3bd-e2f05f4baa9b</goToChain>
     </preconfiguredChoice>
     <!-- Select compression algorithm -->
     <preconfiguredChoice>
         <appliesTo>01d64f58-8295-4b7b-9cab-8f1b153a504f</appliesTo>
         <goToChain>9475447c-9889-430c-9477-6287a9574c5b</goToChain>
     </preconfiguredChoice>
     <!-- Select compression level -->
     <preconfiguredChoice>
         <appliesTo>01c651cb-c174-4ba4-b985-1d87a44d6754</appliesTo>
         <goToChain>414da421-b83f-4648-895f-a34840e3c3f5</goToChain>
     </preconfiguredChoice>
   </preconfiguredChoices>
  </processingMCP>

Note that appliesTo is the UUID associated with the microservice job presented in the dashboard and goToChain is the UUID of the desired selection.

General configuration¶

Fields:

• Site URL: This is the public URL of your Archivematica dashboard. This field is optional.

Storage Service options¶

Archivematica’s storage spaces and locations are controlled by a back-end application called the Storage Service. For more information about the Storage Service, see the Storage Service documentation.

Fields:

• Storage Service URL: Full URL of the storage service. E.g. https://192.168.168.192:8000
• Storage Service User: User in the Storage Service to authenticate as. Obtain Storage Service credentials from the Administration tab of the Storage Service.
• API key: API key of the storage service user. Obtain Storage Service credentials from the Administration tab of the Storage Service.
• Use default configuration: Check this box if you have deployed the Storage Service using the default space and location configurations. If you have set up custom configurations, uncheck it.

Checksum algorithm¶

You can select which checksum algorithm Archivematica will use during the Assign UUIDs and checksums microservice in Transfer. Choose between MD5, SHA-1, SHA-256 and SHA-512.

Elasticsearch indexing¶

As of Archivematica 1.7, installing Elasticsearch is optional. Elasticsearch powers the indexes that are used for searching in the Backlog, Appraisal, and/or Archival Storage. Installing Archivematica without Elasticsearch results in reduced consumption of compute resources and lower operational complexity. Disabling Elasticsearch means that the Backlog, Appraisal, and/or Archival Storage tabs will not appear in the user interface and their functionality will not be available.

This section in the General configuration shows if Elasticsearch is enabled or disabled.

In this example, indexing is enabled for both transfers and AIPs.

It is possible to disable indexing for transfers (the Backlog and Appraisal tabs), for AIPs (the Archival Storage tab), or for both. For more information on disabling Elasticsearch, please see Elasticsearch in the Administrator Manual.

AtoM DIP upload¶

Archivematica can upload DIPs directly to an AtoM website so that the contents can be accessed online.

The AtoM DIP upload configuration page is where you specify the details of the AtoM installation you’d like the DIPs uploaded to (and, if using Rsync to transfer the DIP files, Rsync transfer details).

Before setting these details, please ensure that you have a working AtoM site that is properly connected to Archivematica. See Using AtoM 2.x with Archivematica for more information.

Fields:

• Upload URL: the URL of the destination AtoM website.
• Login email: the email address used to log in to AtoM.
• Login password: the password used to log in to AtoM.
• AtoM version: the version of the destination AtoM website.
• Rsync target: if you’d like to send the DIP with Rsync before it is deposited in AtoM, enter the destination value for rsync, e.g. foobar.com:/dips. This field is optional.
• Rsync command: if you’ve entered an Rsync target, specify the remote shell manually, e.g. ssh -p 22222 -l user. This field is optional.
• Debug mode: if you would like to have additional details in failure reports, also enable debug mode by choosing “Yes”.

$ sudo -u archivematica ssh-keygen

$ sudo apt-get install rssh
$ sudo useradd -d /home/archivematica -m -s /usr/bin/rssh archivematica
$ sudo passwd -l archivematica
$ sudo vim /etc/rssh.conf // Make sure that allowrsync is uncommented!

$ sudo mkdir /home/archivematica/.ssh
$ chmod 700 /home/archivematica/.ssh/
$ sudo vim /home/archivematica/.ssh/authorized_keys // Paste here the contents of id_dsa.pub
$ chown -R archivematica:archivematica /home/archivematica

sudo apt-get install acl # Ubuntu
sudo yum install acl  # Rocky Linux

sudo mkdir /home/archivematica/atom_sword_deposit
sudo chown archivematica:www-data /home/archivematica/atom_sword_deposit
sudo chmod 770 /home/archivematica/atom_sword_deposit

sudo setfacl -d -m u:www-data:rwX /home/archivematica/atom_sword_deposit

The ACL sets `rw-` permissions for files and `rwx` permissions for
directories for the nginx user and then the `www-data` (or `nginx`) user can
delete the temporay DIP directory.

--url="http://atom-hostname/index.php" \
--email="demo@example.com" \
--password="demo" \
--uuid="%SIPUUID%" \
--rsync-target="archivematica@atom-hostname:/tmp" \
--debug

ArchivesSpace DIP upload¶

Before ingesting digital objects destined for ArchivesSpace, ensure that the ArchivesSpace DIP upload settings in the Administration tab of the dashboard have been set.

These settings should be created and saved before digital objects destined for upload to ArchivesSpace are processed. Note that these can be set once and used for processing any number of transfers (i.e. they do not need to be re-set for each transfer).

Fields:

• ArchivesSpace host: the URL of the host database. Do not include https:// or www., e.g. aspace.test.org.
• ArchivesSpace backend port: the port of the database, e.g. 8089.
• ArchivesSpace administrative user: the username of a user with administrative permissions in ArchivesSpace.
• ArchivesSpace administrative user password: the password for user set above. If you make changes to this configuration, you will need to re-enter the password.
• Restrictions Apply: Selecting Yes will apply a blanket access restriction to all content uploaded from Archivematica to ArchivesSpace. Selecting No will send all content to ArchivesSpace without restrictions. Should you wish to enable the PREMIS-based restrictions functionality, choose Base on PREMIS.
• XLink Show: indicate how the link to the digital object, as it appears in ArchivesSpace, should operate.
  • Embed: the digital object screen is embedded in the current window.
  • New: the digital object screen opens in a new window.
  • None: no specific behaviour is passed to the link.
  • Other: no specific behaviour is passed to the link.
  • Replace: the digital object screen opens in the current window.
• XLink Actuate: indicates when a digital object should display in ArchivesSpace (e.g. whether the link occurs automatically or must be requested by the user). Used in conjunction with XLink Show attribute.
  • None: no specific behaviour is passed to the link.
  • onLoad: link is activated when the document loads (used when Show = Embed).
  • Other: no specific behaviour is passed to the link.
  • onRequest: link is activated when the user selects the link.
• Object Type: entering a value from ArchivesSpace’s controlled list of object types will apply this value to all objects. This field is optional.
• Use statement: entering a value from ArchivesSpace’s controlled list of use statements will apply this value to all objects. This field is optional.
• URL prefix: the URL of DIP object server as you wish it to appear in ArchivesSpace record. Example: http://example.com
• Conditions governing access: entering a value in this field will populate the Conditions governing access note in ArchivesSpace for all objects.
• Conditions governing use: entering a value in this field will populate the Conditions governing use note in ArchivesSpace for all objects.
• ArchivesSpace repository number: the identifier for the ArchivesSpace repository where you are uploading DIPs. Note that the default identifier for a single-repository ArchivesSpace instance is 2.

API keys¶

Use of the REST API requires the use of API keys. An API key is associated with a specific user. To generate an API key for a user:

• Browse to /administration/accounts/list/
• Click the “Edit” button for the user you’d like to generate an API key for
• Click the “Regenerate API key” checkbox
• Click “Save”

After generating an API key, you can click the “Edit” button for the user and you should see the API key.

IP whitelist¶

The API key is always required but in some cases the administrator may want to add an additional security measurement. IP whitelisting allows you to create a list of trusted IP addresses from which you can access to the API.

The IP whitelist can be edited in the administration interface at /administration/api/. If the whitelist is empty all requests will be allowed.

Approving a transfer¶

The REST API can be used to approve a transfer. The transfer must first be copied into the appropriate watch directory. To determine the location of the appropriate watch directory, first figure out where the shared directory is from the watchDirectoryPath value of /etc/archivematica/MCPServer/serverConfig.conf. Within that directory is a subdirectory activeTransfers. In this subdirectory are watch directories for the various transfer types.

When using the REST API to approve a transfer, if a transfer type isn’t specified, the transfer will be deemed a standard transfer.

HTTP Method: POST

URL: /api/transfer/approve

Parameters:

directory: directory name of the transfer

type (optional): transfer type [standard|dspace|unzipped bag|zipped bag]

api_key: an API key

username: the username associated with the API key

Example curl command:

curl --data "username=rick&api_key=f12d6b323872b3cef0b71be64eddd52f87b851a6&type=standard&directory=MyTransfer" http://127.0.0.1/api/transfer/approve

Example result:

{"message": "Approval successful."}

Listing unapproved transfers¶

The REST API can be used to get a list of unapproved transfers. Each transfer’s directory name and type is returned.

Method: GET

URL: /api/transfer/unapproved

Parameters:

api_key: an API key

username: the username associated with the API key

Example curl command:

curl "http://127.0.0.1/api/transfer/unapproved?username=rick&api_key=f12d6b323872b3cef0b71be64eddd52f87b851a6"

Example result:

{
    "message": "Fetched unapproved transfers successfully.",
    "results": [{
            "directory": "MyTransfer",
           "type": "standard"
        }
    ]
}

CLI creation of administrative users¶

If you need an additional administrator user one can be created via the command-line, issue the following commands:

sudo -u archivematica bash -c " \
    set -a -e -x
    source /etc/default/archivematica-dashboard || \
        source /etc/sysconfig/archivematica-dashboard \
            || (echo 'Environment file not found'; exit 1)
    cd /usr/share/archivematica/dashboard
    /usr/share/archivematica/virtualenvs/archivematica/bin/python manage.py createsuperuser
";

CLI password resetting¶

If you’ve forgotten the password for your administrator user, or any other user, you can change it via the command-line:

sudo -u archivematica bash -c " \
    set -a -e -x
    source /etc/default/archivematica-dashboard || \
        source /etc/sysconfig/archivematica-dashboard \
            || (echo 'Environment file not found'; exit 1)
    cd /usr/share/archivematica/dashboard
    /usr/share/archivematica/virtualenvs/archivematica/bin/python manage.py changepassword <username>
";

CLI configuration pipeline and registration on the Storage Service¶

On new installations, the superuser can be configured and the pipeline registered on the Storage Service using the command-line instead of the GUI. These commands configure the pipeline and register it on the Storage Service exactly like the GUI for the initial configuration screen:

sudo -u archivematica bash -c " \
    set -a -e -x
    source /etc/default/archivematica-dashboard || \
        source /etc/sysconfig/archivematica-dashboard \
            || (echo 'Environment file not found'; exit 1)
    cd /usr/share/archivematica/dashboard
    /usr/share/python/archivematica-dashboard/bin/python manage.py install \
        --username=<username> \
        --password=<password> \
        --email=<email-address> \
        --org-name=<org-name> \
        --org-id=<org-id> \
        --api-key=<api-key>\
        --ss-url=<ss-ulr> \
        --ss-user=<ss-username> \
        --ss-api-key=<ss-api-key> \
        --whitelist=<whitelist>
";

Where:

• api-key: API key that will be added to the username <username>. For example: “test”, “4e5f32ab2aefd3577e1b19a2de5d4dd65f90101a”.
• ss-url: Archivematica Storage Service URL. For example: http://example.archivematica.org:8000.
• ss-user: The Storage Service username that will be used to register the pipeline. This username must already exist in the Storage Service.
• ss-api-key: The <ss-username> API key. This key must already exist in the Storage Service for the user <ss-username>.
• whitelist: Whitespace-separated list of IP addresses or hostnames allowed to use the API. If the whitelist is left empty, all IP addresses and hostnames will be allowed. For example: “192.168.1.3 example.archivematica.org 127.0.0.1” or “”.

This command is most suitable to use on automated installations, for example when deploying using Ansible. For manual installations, please use the web configuration method described in the Post Install Configuration sections:

• Ubuntu Post Install Configuration.
• Rocky Linux Post Install Configuration.

Security¶

Archivematica uses PBKDF2 as the default algorithm to store passwords. This should be sufficient for most users: it’s quite secure, requiring massive amounts of computing time to break. However, other algorithms could be used as the following document explains: How Django stores passwords .

Our plan is to extend this functionality in the future adding groups and granular permissions support.