EPrints Documentation - User contributions [en-gb]

YouTube Import

2026-05-08T10:42:40Z

Drn@ecs.soton.ac.uk: Added page skeleton for YouTube Import Bazaar package

[[Category:Plugins]]
[[Category:Bazaar_Package]]
[[Category:Eprints3.4]]
[[Category:Eprints3.3]]

== Overview ==

== Installing Dependencies ==
=== Python 3.11+ ===
=== Deno ===
=== yt-dlp-ejs ===
=== yt-dlp ===

== Useful Scripts ==

Issues with Installing EPrints on Ubuntu 26.04

2026-05-01T15:16:52Z

Drn@ecs.soton.ac.uk: Added issue with db creation

As of 1st May 2026, Ubuntu 26.04 is under testing to determine if EPrints can be successfully installed and if so if there are any issues with doing this, which require a different approach from the general approach for installing EPrints on Debian/Ubuntu Linux.

==== Current Issues ====
; Segfault when creating EPrints database : If you use <code>bin/epadmin create pub</code> to create a new archive, once you approve the creation of the archive's database rather than prompting you for an appropriate username and password for a superuser that can create new database you get a segfault error like below. A resolution to this issue is currently being investigated.
Segmentation fault (core dumped) bin/epadmin create pub

Issues with Installing EPrints on Ubuntu 24.04

2026-05-01T15:06:08Z

Drn@ecs.soton.ac.uk: /* Previous Issues */

'''N.B. It is assumed that you are installing the [[:Category:Eprints3.4 | latest version of 3.4]]. Earlier versions may have issues not listed here.'''

==== Previous Issues ====
; MySQL root user cannot be used : This is now explained under EPrints' [[Getting Started]] instructions. As it is typical for most modern Linux operating systems.
; <code>libncurses5</code> APT package dependency no longer exists : Install <code>libncurses6</code> instead. However, as both Ubuntu 24.04 and Ubuntu 26.04 only have libncurses6 the general instructions have been updated to use libncurses6, so this is no longer an issue.

Issues with Installing EPrints on Ubuntu 24.04

2026-05-01T15:05:00Z

Drn@ecs.soton.ac.uk: /* Previous Issues */

'''N.B. It is assumed that you are installing the [[:Category:Eprints3.4 | latest version of 3.4]]. Earlier versions may have issues not listed here.'''

==== Previous Issues ====
; MySQL root user cannot be used : This is now explained under EPrints' [[Getting Started]] instructions. As it is typical for most modern Linux operating systems.
; <code>libncurses5</code> : APT package dependency no longer exists in Ubuntu 24.04 LTS, install <code>libncurses6</code> instead. As both Ubuntu 24.04 and Ubuntu 26.04 only have libncurses6 the general instructions have been updated to use libncurses6.

Issues with Installing EPrints on Ubuntu 24.04

2026-05-01T15:04:43Z

Drn@ecs.soton.ac.uk: Moved libncurses version issue to previous issues

'''N.B. It is assumed that you are installing the [[:Category:Eprints3.4 | latest version of 3.4]]. Earlier versions may have issues not listed here.'''

==== Previous Issues ====
; MySQL root user cannot be used : This is now explained under EPrints' [[Getting Started]] instructions. As it is typical for most modern Linux operating systems.
; <code>libncurses5</code> APT package dependency no longer exists in Ubuntu 24.04 LTS, install <code>libncurses6</code> instead. As both Ubuntu 24.04 and Ubuntu 26.04 only have libncurses6 the general instructions have been updated to use libncurses6.

Issues with Installing EPrints on Ubuntu 22.04

2026-05-01T15:02:56Z

Drn@ecs.soton.ac.uk: Added issue as Ubuntu 22.04 is now only LTS that needs libncurses5 rather than libncurses6

'''N.B. It is assumed that you are installing the [[:Category:Eprints3.4 | latest version of 3.4]]. Earlier versions may have issues not listed here.'''

'''<big>NO CURRENT ISSUES</big>'''
==== Previous issues ====
; ''libsepol1'' Deb package no longer exists : This has been removed as a dependency on 29th May 2022, as it is not specifically required by EPrints.
; MySQL root user cannot be used : This is now explained under EPrints' [[Getting Started]] instructions. As it is typical for most modern Linux operating systems.
; ''libncurses6'' Deb package not available : In more recent versions of Ubuntu libncurses6 is the name for the ncurses package but as Ubuntu 22.04 is older you will need to install ''libncurses5'' instead.

Installing EPrints on Debian/Ubuntu

2026-05-01T14:59:15Z

Drn@ecs.soton.ac.uk: libncurses6 is now used by Ubuntu 24.04 and 26.04

{{manual}}
[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 11 (Bullseye) or Debian 12 (Bookworm) - These are not as comprehensively tested as Ubuntu LTS versions.

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page):

apt install perl libncurses6 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

If you are installing on Ubuntu, install MySQL server and client:

apt install mysql-server mysql-client libmysqlclient-dev

If you are installing on Debian, install MariaDB server and client:

apt install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

adduser eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.7

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/3288/1/eprints-3.4.7.tar.gz
tar -xzvf eprints-3.4.7.tar.gz

Then put in the source code in place:

mv eprints-3.4.7 /opt/eprints3
chmod 2775 /opt/eprints3
chown -R eprints:eprints /opt/eprints3

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3288/2/eprints-3.4.7-flavours.tar.gz
tar -xzvf eprints-3.4.7-flavours.tar.gz
mv eprints-3.4.7/flavours/pub_lib /opt/eprints3/flavours
chmod -R g+w /opt/eprints3/flavours/pub_lib
chown -R eprints:eprints /opt/eprints3/flavours/pub_lib

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>, if it does not already exist.

<code>EPRINTS_PATH</code> should now always be <code>/opt/eprints3</code>. However, historically other paths have been used when EPrints was available as a Deb package.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

root> a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the '''Admin''' link under the Logged in menu, then clicking on the '''System Tools''' tab and finally the '''Start Indexer''' button.

== Operating System Version Specific Requirements ==

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Ubuntu 24.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 24.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Issues with Installing EPrints on Ubuntu 26.04

2026-05-01T14:41:11Z

Drn@ecs.soton.ac.uk: Added placeholder

Category:Installation

2026-05-01T14:39:37Z

Drn@ecs.soton.ac.uk: /* Distribution Notes */ Added Ubunty 26.04 (under testing)

The default installation of EPrints is on a stand-alone linux system, but this is not the only way EPrints can (and has) been installed.

'''The EPrints team currently recommends installing EPrints in one of the following ways:'''

* '''[[Installing EPrints on Debian/Ubuntu]]'''
* '''[[Installing EPrints on_RHEL/Fedora/CentOS]]'''
* '''[[Generic_Linux_Installation|Installing from source]]'''

Here are some other ways:

* [[non-root_proxy|Proxied to a non-root user account]]: Where the server and all associated code is installed without root/admin access to anything
* [[How to set up EPrints on virtual directories other than root|Hosted on virtual directories other than root]] - sharing with other Web applications on the same server

This category contains a range of other sets of instructions for different operating systems and versions of EPrints. Most of them are not supported but may still work. {{EPrintsTech}}

If you want to write installation instructions for a system other than those listed here please do so. Remember to tag the page with <nowiki>[[Category:Installation]]</nowiki> so that it appears in this list.

'''If you use one of the installation guides below and it doesn't work, edit the page to say what went wrong and how you fixed it. This will help others (and maybe yourself) tackle these problems in the future. [[Template:Register|Here you can register for an eprints.org account]] to edit the wiki.'''

== Distribution Notes ==

Known issues and gotchas on various Linux distributions

{| class="wikitable"
|-
! Distibution
! Support
! Notes
|-
| RHEL / Centos / Rocky 8
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 8]].
|-
| RHEL / Centos / Rocky 9
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 9]]. EPrints Services test builds against this release.
|-
| RHEL / Centos / Rocky 10
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 10]].
|-
| Ubuntu 22.04 LTS
| Supported
| Some minor issues. See [[Issues with Installing EPrints on Ubuntu 22.04]].
|-
| Ubuntu 24.04 LTS
| Supported
| Some minor issues. See [[Issues with Installing EPrints on Ubuntu 24.04]].
|-
| Ubuntu 26.04 LTS
| Under testing
| Any issues will be reported at [[Issues with Installing EPrints on Ubuntu 26.04]].
|-
|}

Template:EPrints Metadata Fields Content

2026-04-30T13:05:23Z

Drn@ecs.soton.ac.uk: /* Object Methods */ Added render_name

== Metadata Field Types ==

There are many different types of metadata field. The type controls how a field is rendered, indexed, searched and so forth. A field always has a type and a name property, and usually has several more. Most properties are documented on this page, but some properties are only available to certain types of field, and they are listed on the page for that field.

Some of these subclasses provide very rich features, others very simple. For example the [[url field]] works just like the text field except that it's only valid if it looks like a url and when rendered it is a hyper-link.

A metadata field describes one field of data in one type of [[Data Object]]. For example the "title" field of an [[EPrint Object]] or the "email" field in a [[User Object]].

Every [[Data Object]] has system fields (which are set by the system, and not alterable), but the [[User Object]] and [[EPrint Object]] have additional fields which are configured on a per-repository basis.

These can be customised in the [[user_fields.pl]] and [[eprint_fields.pl]] files. Note that changing these files does not automatically modify the underlying database so should (generally) only be done before the database is created. Some metadata properties do not affect the database, and are marked as such.

If you add or remove fields, or modify a property which affects the database then you'll need to alter the database to match. In 3.0 this must be done by hand, but we have plans to build a tool to do this for you.

== Inheritance ==

This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.

Some field types inherit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.

* '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course).
** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields, e.g. author_name and author_email.
*** '''[[Dataobjref field|Dataobjref]]''' - references another data object.
*** '''[[Multilang field|Multilang]]''' - allows language variants of a field, e.g. titles in French, German and/or English.
*** '''[[Relation field|Relation]]''' - stores a typed relationship with something represented by a URI.
** '''[[Date field|Date]]''' - stores a date
*** '''[[Time field|Time]]''' - stores a date and time
**** '''[[Timestamp field|Timestamp]]''' - stores current date and time
** '''[[Float field|Float]]''' - stores a floating-point value
*** '''[[Decimal field|Decimal]]''' - stores a decimal number. Specifying the length of number before and after the decimal point.
** '''[[Id field|Id]]''' - like basic text field but search only finds exact matches
*** '''[[Idci field|Id (case-insensive)]]''' - like Id field but search find exact matches ignoring case (use for usernames, email addresses, etc.)
**** '''[[Email field|Email]]''' - an email address
*** '''[[Keywords field|Keywords]]''' - stores as longtext but searchable as exact individual keyword phrases
*** '''[[Recaptcha field|Recaptcha]]''' - virtual field to display a reCAPTCHA to prevent spamming of public input forms.
*** '''[[Text field|Text]]''' - the basic text field. Maximum 255 bytes. nb. uft-8 means some chars take more than one byte.
**** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes).
***** '''[[Longtext_counter field|Longtext counter]]''' - like longtext but with a word counter (requires [https://jquery.com/download/ jQuery])
**** '''[[Pagerange field|Pagerange]]''' - a range of page from one number to another.
**** '''[[Secret field|Secret]]''' - used to store passwords and other secrets.
**** '''[[Set field|Set]]''' - a limited set of options
***** '''[[Namedset field|Namedset]]''' - like a normal set, but takes its options from a [[namedset]] configuration file.
***** '''[[Subject field|Subject]]''' - possible values are taken from the [[Subject Object|Subject]] hierarchy.
***** '''[[Base64 field|Base64]]''' - stores Base64 encoded data.
****** '''[[Image field|Image]]''' - stores image encoded in Base64 data.
*** '''[[Url field|Url]]''' - stores a URL.
*** '''[[Uuid field|Uuid]]''' - stores a UUID.
** '''[[Int field|Int]]''' - an integer value
*** '''[[Bigint field|Bigint]]''' - a large integer value (can be greater than 2,147,483,647 or less than -2,147,483.647).
*** '''[[Counter field|Counter]]''' - an auto-incrementing integer value.
*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (e.g. a user or other eprint)
*** '''[[Pagerange field|Pagerange]]''' - a pagerange, e.g. 122-130
** '''[[Multipart field|Multipart]]''' - Stores a mutiple sub-fields like a person's name.
*** '''[[Name field|Name]]''' - Stores a person's name broken up into logical parts.
** '''[[Subobject field|Subobject]]''' - Stores another data object under a parent data object.

=== Internal-use and Deprecated Field Types ===
* '''Basic metadata field'''
** '''[[File field|File]]''' - '''DEPRECATED'''. Use [[Subobject field]] instead.
** '''Id'''
*** '''Text'''
**** '''Set'''
***** '''[[Arclanguage field|Arclanguage]]''' - as for set, but the options are the valid languages of this repository. Probably better to use [[Multilang field]].
***** '''[[Fields field|Fields]]''' - as for set, but the options are the fields in a dataset.
***** '''[[Langid field|Langid]]''' - used internally by [[Multilang field]]s to store the language ID.
**** '''Longtext'''
***** '''[[Search field|Search]]''' - a serialised search
** '''Int'''
*** '''[[Year field|Year]]''' - '''DEPRECATED'''. Use [[Date field]] instead.
** '''[[Storable field|Storable]]''' - Stores a serialization of a Perl data structure.

== Properties ==

Note that true/false properties use 1 and 0 to indicate their setting.

Some properties can be temporarily set or overridden by the [[Workflow Format]] and [[Citation Format]] files.

=== Core Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''name''' || n/a || YES || This is the internal name of the field. It should only contain alphanumeric characters and underscores. It will be used to identify this field in scripts, other configuration files, in the database, and in the XML export/import system, etc. || This property is ''not'' required when defining sub-fields of [[Compound field]]s where <tt>sub_name</tt> should be used. This property affects the database structure. It must be unique within the [[Data Object]] (so the [[EPrint Object]] cannot have two fields called <tt>email</tt> but the EPrint Object and [[User Object]] can each have a field with the same name.
|-
| '''type''' || n/a || YES || This sets the type of the metafield, which in turn affects what other properties it may have. || This property affects the database structure. The value must be one of the metafield types listed above.
|-
| '''multiple''' || <tt>0</tt> || NO || This indicates if this field is a single value or a list of values. E.g. <tt>title</tt> is only a single [[Longtext field]] but <tt>creators</tt> is a multiple [[Compound field]]. || This property affects the database structure. In the database a non-multiple field is stored in one (or more) columns in the main object table, but a multiple field gets its own table.
|-
| '''readonly''' || <tt>0</tt> || NO || Whether to not make this field editable in the workflow. || This is useful if you want to display the pre-generated value(s) for this field for reference whilst other fields are being edited.
|-
| '''sql_index''' || <tt>1</tt> || NO || When the database is created this field indicates that an SQL index should be created to speed searching. || This property affects the database structure. Different field types override the default value with the sensible option for that type of field. It is not worth putting a SQL index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields who's values are explicitly searched for, or where ranges are searched (e.g. [[Date field]]s, [[Set field]]s etc.). It is unlikely you will need to set this by hand. You could change it after the database has been created but this will not update the database nor have any other effect.
|-
| '''sub_name''' || <tt>undef</tt> || YES || This is a special property which is required ''instead'' of the <tt>name</tt> property for the sub-fields inside [[Compound field]]s. || This property affects the database structure. The actual name of these fields is then forced to be parent field <tt>name + '_' + sub_name</tt>. E.g. Compound field <tt>creators</tt> is a sub-field with <tt>sub_name => 'name'</tt>. In this case the actual name of the name field in the system, database etc. is <tt>creators_name/tt>.
|-
| '''virtual''' || <tt>0</tt> || NO || Whether this field calculates a value or stores in in the database. || [[Compound field]]s are virtual fields, whereas there sub-fields are not as they store values in the database. Other types of virtual field will require a <tt>render_value</tt> to be specified, as with no value stored the default render method will have nothing to display.
|-
| '''volatile''' || <tt>0</tt> || NO || Whether the field is liable to change frequently. || Setting <code>volatile => 1</code> will prevent new revisions being create and avoid other post commit events from being triggered, such as re-indexing.
|}

=== Rendering Properties ===

These properties affect how values of the metadata in this field are rendered.

Certain of these properties can be turned on temporarily by the [[Citation Format]] files - render_magicstop for example.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''as_list''' || <tt>undef</tt> || NO || Whether to display a collection sub-fields values as a table row or a separate list in the input form || This is only applicable for [[Compound field]]s that have <code>multiple => 1</code>. It is useful where the length of the table row would exceed the width of a typical user's window.
|-
| '''browse_link''' || <tt>undef</tt> || NO || This is the name of a view which values of this field should be linked to. || E.g. if there was a <tt>Browse by Publishers</tt> view configured named <tt>pubs</tt>, then adding <code>browse_link => 'pubs'</tt> to the <tt>publisher</tt> field would cause it to be linked into the browse view page for the named publisher whenever it is rendered.
|-
| '''render_custom''' || <tt>undef</tt> || NO || Whether to use a pre-defined way of rendering the value for this field. || E.g. for [[Name field]]s by default the name will link to the creators browse view for that name. This property can be re-used within bespoke render functions to specify whether some custom way of rendering this field' svalue (e.g. with a link) should be used.
|-
| '''render_dont_link''' || <tt>0</tt> || NO || Whether rendered field is not encapsulated in a hyperlink. || Currently only affects [[Url field]]s and [[Email field]]s.
|-
| '''render_dynamic''' || <tt>0</tt> || NO || Whether the rendering of this field can use JavaScript to make it dynamic. || [[limit_names_shown.pl]] uses this property to determine if the list of hidden creators/editors can be expanded to show all creators/editors.
|-
| '''render_limit''' || <tt>undef</tt> || NO || How many values for this field should be displayed. || [[limit_names_shown.pl]] uses this property to determine how many creators/editors to display. If <code>undef</code> just render all values.
|-
| '''render_magicstop''' || <tt>0</tt> || NO || Whether to render a full stop at the end of this field, unless the last character is a dot, question mark or exclamation mark. || This helps avoid the ugly <tt>World without Cheese?.</tt> effect you get when titles end in <tt>?</tt> or <tt>!</tt>.
|-
| '''render_noreturn''' || <tt>0</tt> || NO || Whether CR (Carriage Return) and LF (Line Feed) characters are turned into normal spaces. ||
|-
| '''render_quiet''' || <tt>0</tt> || NO || Whether to prevent a big ugly <tt>UNSPECIFIED</tt> being rendered if field is unset. || E.g. setting <code>render_quiet => 1</code> on a field means it just gets rendered as nothing if it is unset.
|-
| '''render_single_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render individual values from this field. || For a multiple field this is called once per value in the list of values. The function should take the following parameters: (<code>$session, $field, $value, $object</code>). It should return a [[XHTML DOM]] object of the rendered value.
|-
| '''render_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render the the field as a whole. || As with <tt>render_single_value</tt>, but this gets passed the entire list of values (an array reference) if it is a multiple field. Parameters passed are: ( code>$session, $self, $value, $all_langs, $no_link, $object</code> ). <code>$all_langs</code> indicates that all language variants should be shown and is only really useful for [[Multilang field]]s. <code>$no_link</code> being true is a request to place no hyperlinks in the resulting HTML. The function should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''default_value''' || <tt>undef</tt> || NO || The default value to set for this field. || This is mainly used for [[EPrints Glossary#System field|system fields]]. For custom fields it is better to use [[eprint_fields_default.pl]] or similar.
|-
| '''expanded_subjects''' || <tt>[]</tt> || NO || Subjects to show un-collapsed in the subject tree field in the workflow. || This is only applicable for [[Subject field]]s. All the fields listed will have their paths in the subject tree expanded so they can be seen, making them easier to find.
|-
| '''false_first''' || <tt>0</tt> || NO || Display the false option before the true option in the input form. || This is only applicable to [[Boolean field]]s. By default true option is always displayed before the false option.
|-
| '''fromform''' || <tt>undef</tt> || NO || The inverse of <tt>toform</tt>. This takes the value from the form and converts it into the value that will be stored in the database. || This function is passed the parameters: <tt>$value, $session, $object, $basename</tt> when <tt>$value</tt> is the value entered on the HTML form, and the return value is the value to be stored in the database. This function is not called when editing the eprint is cancelled.
|-
| '''get_item''' || <tt>undef</tt> || NO || A bespoke function for how to lookup the [[EPrints Glossary#Data object|Data object]] based on the stored value. || Only applicable to [[Itemref field]]s.
|-
| '''help_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the help text for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the help on a field. If you need to change the help text based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldhelp_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldhelp_id_number.article</code>).
|-
| '''input_add_boxes''' || <tt>2</tt> || NO || The number of rows to add when clicking the <tt>More input rows</tt> button for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_boxes''' || <tt>3</tt> || NO || The number of input rows to initially show for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_cols''' || <tt>60</tt> || NO || The number of columns in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. This in combination with the <tt>maxlength</tt> property determines the value for <tt>size</tt> attribute for <code><input></code> HTML fields or the <tt>cols</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''input_lookup_params''' || <tt>undef</tt> || NO || Additional parameters to pass to the <tt>input_lookup_url</tt>. || E.g. an indication of which autocomplete file to use.
|-
| '''input_lookup_url''' || <tt>undef</tt> || NO || The URL to use for autocompletion. || This is generally set using the workflow configuration rather than directly in the field configuration. The URL must be on the same server hostname as the repository.
|-
| '''input_ordered''' || <tt>1</tt> || NO || Whether the ordering of values needs to be captured. || In some <code>multiple => 1</code> fields, such as creators, the order of the values is important and by default numbers are shown to the left of input rows and to the right are ''move up'' and ''move down'' arrows. However, with some <code>multiple => 1</code> fields the order is not important, in which case you can set this to <tt>0</tt> to stop the arrows and numbers being shown.
|-
| '''input_rows''' || <tt>10</tt> || NO || The number of rows in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt> This property determines the value for <tt>size</tt> attribute for <code><select></code> HTML fields (used by [[Set field]]s) or the <tt>rows</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''maxlength''' || <tt>255</tt> || NO || The maximum allowed length in characters for a value. || This can be a very simple validation check. Also, it may confuse users to be allowed to type in 255 characters in a field intended for something like a postcode/zipcode.
|-
| '''maxwords''' || <tt>undef</tt> || NO || The maximum number of words that should be entered for this field. || This field is only applicable to [[Longtext_counter field]]s. It does not restrict the number of words, it just displays this limit next to a dynamic counter of the number of words already entered.
|-
| '''render_input''' || <tt>undef</tt> || NO || The name of a function which will render the input for this field. || This can be difficult to use as it must return the same CGI parameters as the default input form would have. It is easiest on simple fields. The subroutine is passed the following parameters: <code>$field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename</code> ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''required''' || <tt>0</tt> || NO || Whether the field must have a value set. || If this is set to <tt>1</tt> then the field is always marked as required, no matter what the [[Workflow Format]] configuration says.
|-
| '''separator''' || <tt>undef</tt> || NO || What character to use to separate elements of the value for the field for purposes of search || Only used by default for [[Keywords field]]s.
|-
| '''show_help''' || <tt>undef</tt> || NO || How to display the help text for this field in the input form. || Can be one of three values: <tt>always</tt>, <tt>never</tt> or <tt>toggle</tt>. Toggle (allow to expand or collapse) is used if not explicitly defined. This can only be overridden in [[Workflow Format]] configuration.
|-
| '''title_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the title for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the title of a field. If you need to change the title based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldname_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldname_id_number.article</code>).
|-
| '''toform''' || <tt>undef</tt> || NO || This function is allowed to modify the current value which appears in the form. || E.g. if your database stores <tt>userid</tt>s in a field, but you want to allow people to edit them as <tt>username</tt>s, then this function can be used to take the current value (a <tt>userid</tt>) and return the associated <tt>username</tt>. This value is what appears in the field in the search form. It is passed: <code>$value, $session, $object, $basename</code> and returns the user-facing version of <code>$value</code>.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''make_single_value_orderkey''' || <tt>undef</tt> || NO || The <tt>orderkey</tt> function (potentially language specific) used to order by this field. || This property allows you to define a function or refer to a predefined function to override the default EPrints' orderkey generation. This property is passed each value from multiple fields, in turn. It is passed: <code>$field, $value, $dataset</code> and returns an <tt>ordervalue</tt> string.
|-
| '''make_value_orderkey''' || <tt>undef</tt> || NO || Like <tt>make_single_value_orderkey</tt> but this is passed the array reference for a multiple field rather than just single values. || It should return the <tt>orderkey</tt> string for the entire value. It is passed: <code>$field, $value, $session, $langid, $dataset</code>.
|-
| '''match''' || <tt>EQ</tt> || NO || How to match the value(s) of this field against search terms. || This property can be <tt>EQ</tt>, <tt>EX</tt>, <tt>IN</tt> or <tt>SET</tt>. Default <tt>EQ</tt> means treat the search term as a single string. Match only whole search term matches the field value (or one of its values if <code>multiple => 1</code>). This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]].
|-
| '''merge''' || <tt>ALL</tt> || NO || Whether this field's values(s) has to match any or all of the search terms || This property can be <tt>ALL</tt> or <tt>ANY</tt>, Default <tt>ALL</tt> means all search terms have to match the values(s) in this field. This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]]. For certain values of <tt>match</tt> this can also be changed by the user in the search form itself.
|-
| '''text_index''' || <tt>0</tt> || NO || Whether the indexer considers this field for full-text indexing. || Some types of metadata field have a default of <tt>1</tt>, e.g. [[Text field]]s and [[Longtext field]]s.
|-
| '''search_cols''' || <tt>40</tt> || NO || How many characters (columns) wide the input field for searching this field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. If one search field searches more than one field, then the properties from the first field listed are used.
|}

=== Other Properties ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''allow_null''' || <tt>1</tt> || NO || Whether the value(s) stored in the database when no input is entered should be <tt>NULL</tt> or an appropriate default value based on its database field type. || This should generally never be set to <tt>0</tt> and certainly should not be changed to <tt>0</tt> after the field has been added to the database. You are much better off configuring a default value using <tt>[[eprint_fields_default.pl]]</tt> or similar.
|-
This may be applicable to [[Text field|text]]
| '''can_clone''' || <tt>1</tt> || NO || Whether the value(s) for this field should be cloned if a new record is created. || This property is mostly used by system fields such as <tt>dir</tt> or <tt>datestamp</tt>. It is applicable when an eprint is cloned using the <tt>Use as template</tt> or <tt>New version</tt> action buttons.
|-
| '''export_as_xml''' || <tt>1</tt> || NO || Whether the field value(s) should be exported in an XML export. || This is handy to suppress either confidential or confusing fields, like the <tt>fileinfo</file> [[EPrints Glossary#System_field|system field]].
|-
| '''import''' || <tt>1</tt> || NO || Whether new data objects create from an import can set values for the field. || E.g. <tt>eprintid</tt>, <tt>dir<tt> are determined when the eprint record is created. Imported metadata would not choose an appropriate value for such fields.
|-
| '''replace_core''' ||| <tt>0</tt> || NO || Whether the field configuration should replace the exisiting [[EPrints Glossary#Core_field|core (system) field]] with the same <tt>name</tt> || This is useful for particularly bespoke requirements. It should be used with great care, as system fields are usually hard-coded because they should not be changed.
|-
| '''show_in_fieldlist''' || <tt>1</tt> || NO || Whether to allow this field to appear in fields lists. || If set to <tt>0</tt> will prevent this field appearing in [[Fields field]] lists. This is primarily to allow you to remove it from the list of fields in the user configuration which are used to control which fields appear as columns in the Items and Review screens.
|-
| '''show_in_html''' || <tt>1</tt> || NO || Whether this field is not shown in the [[EPrints Glossary#Details_tab|Details tab]] of the [[EPrints Glossary#EPrint_control_page|eprint control page]]. || This is mostly used to hide confusing internal [[EPrints Glossary#System_field|system field]]s like <tt>dir</tt>.
|}

=== Internal Properties ===

These are set by the system. Editing them by hand will do '''''strange things'''''.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''confid''' || n/a || YES || The ID of the dataset to which this field belongs. || The value for this property is automatically set when the field is loaded. It is used to work out what phrase ids etc. it uses.
|-
| '''join_path''' || <tt>undef</tt> || NO || How to join a field that references a different [[Data Object]]. || This should never be defined within a field's configuration. This is built by search to support building a database query to perform a user's search.
|-
| '''parent''' || <tt>undef</tt> || NO || A reference to the actual parent [[Compound field]] object. || This is set automatically as a reference to the parent field object.
|-
| '''parent_name''' || <tt>undef</tt> || NO || The name of the parent [[Compound field]] to which a sub-field belongs. || This is set automatically to be the name of the parent field.
|-
| '''provenance''' || <tt>undef</tt> || NO || Where this field configuration was generated. || Typically any field configuration either defined within a [[Data Object|Data object]] or in a configuration file (in a <tt>cfg.d</tt> directory will leave this as <tt>undef</tt> by not specifying this property. However, fields created using [[Admin/Config._Tools/Manage_Metadata_Fields|Manage Metadata Fields]] will set this to <tt>user</tt> so it is clear from where this field was created.
|}

=== Deprecated Properties ===

Do not use these!

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''input_advice_below''' || <tt>undef</tt> || NO || Help text to put directly below the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_advice_right''' || <tt>undef</tt> || NO || Help text to put directly to the right of the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_assist''' || <tt>undef</tt> || NO || Provides input assistance. || Deprecated. Defined but no longer functional.
|-
| '''requiredlangs''' || <tt>[]</tt> || NO || The natural languages that should be used in the value(s) for this field || Deprecated. Defined but no longer functional.
|-
| '''sql_langid''' || <tt>undef</tt> || NO || The language ID for SQL. || Deprecated. Defined but no longer functional.
|-
| '''sql_sorted''' || <tt>0</tt> || NO || Whether SQL should be sorted. || Deprecated. Defined but no longer functional.
|}

== Methods ==
=== Constructor Methods ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !! Parameters !! Returns !! Description
|-
| '''new'''
||<code>$field = EPrints::MetaField->new( %properties )</code>
||
; $class : The sub-class of the new <code>EPrints::MetaField</code> to be created.
; %properties : A hash of the properties to be used to create this new <code>EPrints::MetaField</code> object. Also requires a <code>dataset</code> attribute to be set or otherwise both <code>confid</code> and <code>repository</code> attributes are required.
||A new instance of an <code>EPrints::MetaField</code>.

||Create a new <code>EPrints::MetaField</code> of the appropriate class.
|}

=== Class Methods ===
'''TO BE DONE'''
=== Object Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''field_defaults'''
||<code>$defaults = $field->field_defaults</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A hash reference of the default properties for the class of <code>EPrints::MetaField</code> of which this object is an instance.
||Provides the default properties of this <code>EPrints::MetaField</code> object.
|-
| '''final'''
||<code>$field->final</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''set_property'''
|| <code>$field->set_property( $property, $value )</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $property : The property to be set.
; $value : The value to set for the <code>$property</code>.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''clone'''
|| <code>$newfield = $field->clone</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A new <code>EPrints::MetaField</code> object that is a clone of the existing object.
||Clone the field, so the clone can be edited without affecting the original. Does not deep copy properties which are references - these should be set to new values, rather than the contents altered. E.g. Don't push to a cloned options list, replace it.
|
|-
| '''repository'''
|| <code>$repository = $field->repository</code>
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::Repository</code> object to which this field belongs.
|| Get the current repository object.
|
|-
| '''dataset'''
|| <code>$dataset = $field->dataset</code> (or <code>$dataset = $field->get_dataset</code>)
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::DataSet</code> object to which this field belongs.
|| Get dataset to which this field belongs.
|-
| '''render_name'''
|| <code>$xhtml = $field->render_name( [ $session ], [ $dataobj] )</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object. (No longer required but at least a placeholder required if specifying <code>$dataobj</code>).
; $dataobj : A data object belong to the <code>$dataset</code> that has the <code>$value</code> set for this field. Only required if you want to use a bespoke phrase based on the type value for the data object, (e.g. <code><epp:phrase id="eprint_fieldname_data_type.dataset">...</epp:phrase></code>).
|| A <code>XML::LibXML::DocumentFragment</code> containing the help text for the field.
|| Get the help information for a user inputting some data for this field as an XHTML chunk. Either from a phrase defined for the field or under the field property <code>help_xhtml</code>.
|-
| '''render_help'''
|| <code>$xhtml = $field->render_help</code>
||
; $self : A <code>EPrints::MetaField</code> object.
|| A <code>XML::LibXML::DocumentFragment</code> containing the help text for the field.
|| Get the help information for a user inputting some data for this field as an XHTML chunk. Either from a phrase defined for the field or under the field property <code>help_xhtml</code>.
|-
| '''render_input_field'''
|| <code>$xhtml = $field->render_input_field( $session, $value, $dataset, $staff, $hidden_fields, $obj, $basename, $one_field_component )
</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object.
; $value : The value from the database to be rendered within this field.
; $dataset : The <code>EPrints::Dataset</code> to which the field belongs. (Does not always need to be defined)
; $staff : A boolean (typically <code>0</code> or <code>1</code>) for whether the but usually set to <code>0</code> as this should be managed through a conditional statement in the workflow.
; $hidden_fields : Extra fields associated with this field but rendered so they cannot be seen by the user (e.g. <code><input type="hidden" ... /></code>).
; $obj : A data object belong to the <code>$dataset</code> that has the <code>$value</code> set for this field.
; $basename : The basename for this field for uses as a prefix when a compound field that contains sub-fields.
; $one_field_component : A boolean (typically <code>0</code> or <code>1</code>) defining whether the workflow component that the field is being rendered has just this field or multiple fields in it.
|| A <code>XML::LibXML::DocumentFragment</code> containing an XHTML rendering of the field for input.
|| Get an XHTML rendering of the field for input. May be overridden with <code>render_input</code> property for this field.
|}

=== Utility Methods ===
'''TO BE DONE'''

=== Deprecated Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''display_name'''
|| <code>$dataset = $field->dataset</code> or <code>$dataset = $field->get_dataset</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object.
|| The UTF-8 encoded name of this field, in the language of the <code>$session</code> object.
|| Get the human-readable name for this field.
|}

== Required Phrases ==

These are phrases which you need to define in the local repository phrases file to control how this field renders. Some types of field (eg. [[set field]]s) have additional phrases in addition to the ones listed below.

The actual name of the field, as it will appear to users is stored in

datasetid + "_fieldname_" + fieldname

The default help to display, when the field is being input, is stored in

datasetid + "_fieldhelp_" + fieldname

For example:

<epp:phrase id="eprint_fieldname_abstract">Abstract</epp:phrase>
<epp:phrase id="eprint_fieldhelp_abstract">A summary of the items content.
If the item has a formal abstract then that is what should be entered
here. No complicated text formatting is possible.</epp:phrase>

== Database ==

Most fields have a representation in the SQL database using one or more columns. The sub-pages for each field type give the details.

== API ==

When you request (or set) a value of a metadata field, it is usually handled as a perl scalar (which is a string or number).

ALL values passed around in the API should be encoded in utf-8 or BAD THINGS may happen.

For example,

$eprint->set_value( "title", "For Us, The Living" );

Sets the title to the given string.

my $foo = $eprint->get_value( "title" );

Sets $foo to the string of the title, eg. "For Us, The Living".

=== Multiple Fields ===

If a field is set to multiple, then instead of a single value, a reference to an array of values is used. Eg.

$eprint->set_value( "corp_creators", [ "Jims Research", "Jones Research ] );

=== Other Exceptions ===

See the specific page for the full details.

* [[name field]]s are represented as a hash of the parts.

* [[compound field]]s do something a bit clever.

== Examples ==
Example field definitions that can be copied into an configuration file and edited as appropriates.

Template:EPrints Metadata Fields Content

2026-04-30T12:48:26Z

Drn@ecs.soton.ac.uk: /* Object Methods */ Added more object methods

== Metadata Field Types ==

There are many different types of metadata field. The type controls how a field is rendered, indexed, searched and so forth. A field always has a type and a name property, and usually has several more. Most properties are documented on this page, but some properties are only available to certain types of field, and they are listed on the page for that field.

Some of these subclasses provide very rich features, others very simple. For example the [[url field]] works just like the text field except that it's only valid if it looks like a url and when rendered it is a hyper-link.

A metadata field describes one field of data in one type of [[Data Object]]. For example the "title" field of an [[EPrint Object]] or the "email" field in a [[User Object]].

Every [[Data Object]] has system fields (which are set by the system, and not alterable), but the [[User Object]] and [[EPrint Object]] have additional fields which are configured on a per-repository basis.

These can be customised in the [[user_fields.pl]] and [[eprint_fields.pl]] files. Note that changing these files does not automatically modify the underlying database so should (generally) only be done before the database is created. Some metadata properties do not affect the database, and are marked as such.

If you add or remove fields, or modify a property which affects the database then you'll need to alter the database to match. In 3.0 this must be done by hand, but we have plans to build a tool to do this for you.

== Inheritance ==

This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.

Some field types inherit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.

* '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course).
** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields, e.g. author_name and author_email.
*** '''[[Dataobjref field|Dataobjref]]''' - references another data object.
*** '''[[Multilang field|Multilang]]''' - allows language variants of a field, e.g. titles in French, German and/or English.
*** '''[[Relation field|Relation]]''' - stores a typed relationship with something represented by a URI.
** '''[[Date field|Date]]''' - stores a date
*** '''[[Time field|Time]]''' - stores a date and time
**** '''[[Timestamp field|Timestamp]]''' - stores current date and time
** '''[[Float field|Float]]''' - stores a floating-point value
*** '''[[Decimal field|Decimal]]''' - stores a decimal number. Specifying the length of number before and after the decimal point.
** '''[[Id field|Id]]''' - like basic text field but search only finds exact matches
*** '''[[Idci field|Id (case-insensive)]]''' - like Id field but search find exact matches ignoring case (use for usernames, email addresses, etc.)
**** '''[[Email field|Email]]''' - an email address
*** '''[[Keywords field|Keywords]]''' - stores as longtext but searchable as exact individual keyword phrases
*** '''[[Recaptcha field|Recaptcha]]''' - virtual field to display a reCAPTCHA to prevent spamming of public input forms.
*** '''[[Text field|Text]]''' - the basic text field. Maximum 255 bytes. nb. uft-8 means some chars take more than one byte.
**** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes).
***** '''[[Longtext_counter field|Longtext counter]]''' - like longtext but with a word counter (requires [https://jquery.com/download/ jQuery])
**** '''[[Pagerange field|Pagerange]]''' - a range of page from one number to another.
**** '''[[Secret field|Secret]]''' - used to store passwords and other secrets.
**** '''[[Set field|Set]]''' - a limited set of options
***** '''[[Namedset field|Namedset]]''' - like a normal set, but takes its options from a [[namedset]] configuration file.
***** '''[[Subject field|Subject]]''' - possible values are taken from the [[Subject Object|Subject]] hierarchy.
***** '''[[Base64 field|Base64]]''' - stores Base64 encoded data.
****** '''[[Image field|Image]]''' - stores image encoded in Base64 data.
*** '''[[Url field|Url]]''' - stores a URL.
*** '''[[Uuid field|Uuid]]''' - stores a UUID.
** '''[[Int field|Int]]''' - an integer value
*** '''[[Bigint field|Bigint]]''' - a large integer value (can be greater than 2,147,483,647 or less than -2,147,483.647).
*** '''[[Counter field|Counter]]''' - an auto-incrementing integer value.
*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (e.g. a user or other eprint)
*** '''[[Pagerange field|Pagerange]]''' - a pagerange, e.g. 122-130
** '''[[Multipart field|Multipart]]''' - Stores a mutiple sub-fields like a person's name.
*** '''[[Name field|Name]]''' - Stores a person's name broken up into logical parts.
** '''[[Subobject field|Subobject]]''' - Stores another data object under a parent data object.

=== Internal-use and Deprecated Field Types ===
* '''Basic metadata field'''
** '''[[File field|File]]''' - '''DEPRECATED'''. Use [[Subobject field]] instead.
** '''Id'''
*** '''Text'''
**** '''Set'''
***** '''[[Arclanguage field|Arclanguage]]''' - as for set, but the options are the valid languages of this repository. Probably better to use [[Multilang field]].
***** '''[[Fields field|Fields]]''' - as for set, but the options are the fields in a dataset.
***** '''[[Langid field|Langid]]''' - used internally by [[Multilang field]]s to store the language ID.
**** '''Longtext'''
***** '''[[Search field|Search]]''' - a serialised search
** '''Int'''
*** '''[[Year field|Year]]''' - '''DEPRECATED'''. Use [[Date field]] instead.
** '''[[Storable field|Storable]]''' - Stores a serialization of a Perl data structure.

== Properties ==

Note that true/false properties use 1 and 0 to indicate their setting.

Some properties can be temporarily set or overridden by the [[Workflow Format]] and [[Citation Format]] files.

=== Core Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''name''' || n/a || YES || This is the internal name of the field. It should only contain alphanumeric characters and underscores. It will be used to identify this field in scripts, other configuration files, in the database, and in the XML export/import system, etc. || This property is ''not'' required when defining sub-fields of [[Compound field]]s where <tt>sub_name</tt> should be used. This property affects the database structure. It must be unique within the [[Data Object]] (so the [[EPrint Object]] cannot have two fields called <tt>email</tt> but the EPrint Object and [[User Object]] can each have a field with the same name.
|-
| '''type''' || n/a || YES || This sets the type of the metafield, which in turn affects what other properties it may have. || This property affects the database structure. The value must be one of the metafield types listed above.
|-
| '''multiple''' || <tt>0</tt> || NO || This indicates if this field is a single value or a list of values. E.g. <tt>title</tt> is only a single [[Longtext field]] but <tt>creators</tt> is a multiple [[Compound field]]. || This property affects the database structure. In the database a non-multiple field is stored in one (or more) columns in the main object table, but a multiple field gets its own table.
|-
| '''readonly''' || <tt>0</tt> || NO || Whether to not make this field editable in the workflow. || This is useful if you want to display the pre-generated value(s) for this field for reference whilst other fields are being edited.
|-
| '''sql_index''' || <tt>1</tt> || NO || When the database is created this field indicates that an SQL index should be created to speed searching. || This property affects the database structure. Different field types override the default value with the sensible option for that type of field. It is not worth putting a SQL index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields who's values are explicitly searched for, or where ranges are searched (e.g. [[Date field]]s, [[Set field]]s etc.). It is unlikely you will need to set this by hand. You could change it after the database has been created but this will not update the database nor have any other effect.
|-
| '''sub_name''' || <tt>undef</tt> || YES || This is a special property which is required ''instead'' of the <tt>name</tt> property for the sub-fields inside [[Compound field]]s. || This property affects the database structure. The actual name of these fields is then forced to be parent field <tt>name + '_' + sub_name</tt>. E.g. Compound field <tt>creators</tt> is a sub-field with <tt>sub_name => 'name'</tt>. In this case the actual name of the name field in the system, database etc. is <tt>creators_name/tt>.
|-
| '''virtual''' || <tt>0</tt> || NO || Whether this field calculates a value or stores in in the database. || [[Compound field]]s are virtual fields, whereas there sub-fields are not as they store values in the database. Other types of virtual field will require a <tt>render_value</tt> to be specified, as with no value stored the default render method will have nothing to display.
|-
| '''volatile''' || <tt>0</tt> || NO || Whether the field is liable to change frequently. || Setting <code>volatile => 1</code> will prevent new revisions being create and avoid other post commit events from being triggered, such as re-indexing.
|}

=== Rendering Properties ===

These properties affect how values of the metadata in this field are rendered.

Certain of these properties can be turned on temporarily by the [[Citation Format]] files - render_magicstop for example.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''as_list''' || <tt>undef</tt> || NO || Whether to display a collection sub-fields values as a table row or a separate list in the input form || This is only applicable for [[Compound field]]s that have <code>multiple => 1</code>. It is useful where the length of the table row would exceed the width of a typical user's window.
|-
| '''browse_link''' || <tt>undef</tt> || NO || This is the name of a view which values of this field should be linked to. || E.g. if there was a <tt>Browse by Publishers</tt> view configured named <tt>pubs</tt>, then adding <code>browse_link => 'pubs'</tt> to the <tt>publisher</tt> field would cause it to be linked into the browse view page for the named publisher whenever it is rendered.
|-
| '''render_custom''' || <tt>undef</tt> || NO || Whether to use a pre-defined way of rendering the value for this field. || E.g. for [[Name field]]s by default the name will link to the creators browse view for that name. This property can be re-used within bespoke render functions to specify whether some custom way of rendering this field' svalue (e.g. with a link) should be used.
|-
| '''render_dont_link''' || <tt>0</tt> || NO || Whether rendered field is not encapsulated in a hyperlink. || Currently only affects [[Url field]]s and [[Email field]]s.
|-
| '''render_dynamic''' || <tt>0</tt> || NO || Whether the rendering of this field can use JavaScript to make it dynamic. || [[limit_names_shown.pl]] uses this property to determine if the list of hidden creators/editors can be expanded to show all creators/editors.
|-
| '''render_limit''' || <tt>undef</tt> || NO || How many values for this field should be displayed. || [[limit_names_shown.pl]] uses this property to determine how many creators/editors to display. If <code>undef</code> just render all values.
|-
| '''render_magicstop''' || <tt>0</tt> || NO || Whether to render a full stop at the end of this field, unless the last character is a dot, question mark or exclamation mark. || This helps avoid the ugly <tt>World without Cheese?.</tt> effect you get when titles end in <tt>?</tt> or <tt>!</tt>.
|-
| '''render_noreturn''' || <tt>0</tt> || NO || Whether CR (Carriage Return) and LF (Line Feed) characters are turned into normal spaces. ||
|-
| '''render_quiet''' || <tt>0</tt> || NO || Whether to prevent a big ugly <tt>UNSPECIFIED</tt> being rendered if field is unset. || E.g. setting <code>render_quiet => 1</code> on a field means it just gets rendered as nothing if it is unset.
|-
| '''render_single_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render individual values from this field. || For a multiple field this is called once per value in the list of values. The function should take the following parameters: (<code>$session, $field, $value, $object</code>). It should return a [[XHTML DOM]] object of the rendered value.
|-
| '''render_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render the the field as a whole. || As with <tt>render_single_value</tt>, but this gets passed the entire list of values (an array reference) if it is a multiple field. Parameters passed are: ( code>$session, $self, $value, $all_langs, $no_link, $object</code> ). <code>$all_langs</code> indicates that all language variants should be shown and is only really useful for [[Multilang field]]s. <code>$no_link</code> being true is a request to place no hyperlinks in the resulting HTML. The function should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''default_value''' || <tt>undef</tt> || NO || The default value to set for this field. || This is mainly used for [[EPrints Glossary#System field|system fields]]. For custom fields it is better to use [[eprint_fields_default.pl]] or similar.
|-
| '''expanded_subjects''' || <tt>[]</tt> || NO || Subjects to show un-collapsed in the subject tree field in the workflow. || This is only applicable for [[Subject field]]s. All the fields listed will have their paths in the subject tree expanded so they can be seen, making them easier to find.
|-
| '''false_first''' || <tt>0</tt> || NO || Display the false option before the true option in the input form. || This is only applicable to [[Boolean field]]s. By default true option is always displayed before the false option.
|-
| '''fromform''' || <tt>undef</tt> || NO || The inverse of <tt>toform</tt>. This takes the value from the form and converts it into the value that will be stored in the database. || This function is passed the parameters: <tt>$value, $session, $object, $basename</tt> when <tt>$value</tt> is the value entered on the HTML form, and the return value is the value to be stored in the database. This function is not called when editing the eprint is cancelled.
|-
| '''get_item''' || <tt>undef</tt> || NO || A bespoke function for how to lookup the [[EPrints Glossary#Data object|Data object]] based on the stored value. || Only applicable to [[Itemref field]]s.
|-
| '''help_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the help text for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the help on a field. If you need to change the help text based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldhelp_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldhelp_id_number.article</code>).
|-
| '''input_add_boxes''' || <tt>2</tt> || NO || The number of rows to add when clicking the <tt>More input rows</tt> button for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_boxes''' || <tt>3</tt> || NO || The number of input rows to initially show for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_cols''' || <tt>60</tt> || NO || The number of columns in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. This in combination with the <tt>maxlength</tt> property determines the value for <tt>size</tt> attribute for <code><input></code> HTML fields or the <tt>cols</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''input_lookup_params''' || <tt>undef</tt> || NO || Additional parameters to pass to the <tt>input_lookup_url</tt>. || E.g. an indication of which autocomplete file to use.
|-
| '''input_lookup_url''' || <tt>undef</tt> || NO || The URL to use for autocompletion. || This is generally set using the workflow configuration rather than directly in the field configuration. The URL must be on the same server hostname as the repository.
|-
| '''input_ordered''' || <tt>1</tt> || NO || Whether the ordering of values needs to be captured. || In some <code>multiple => 1</code> fields, such as creators, the order of the values is important and by default numbers are shown to the left of input rows and to the right are ''move up'' and ''move down'' arrows. However, with some <code>multiple => 1</code> fields the order is not important, in which case you can set this to <tt>0</tt> to stop the arrows and numbers being shown.
|-
| '''input_rows''' || <tt>10</tt> || NO || The number of rows in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt> This property determines the value for <tt>size</tt> attribute for <code><select></code> HTML fields (used by [[Set field]]s) or the <tt>rows</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''maxlength''' || <tt>255</tt> || NO || The maximum allowed length in characters for a value. || This can be a very simple validation check. Also, it may confuse users to be allowed to type in 255 characters in a field intended for something like a postcode/zipcode.
|-
| '''maxwords''' || <tt>undef</tt> || NO || The maximum number of words that should be entered for this field. || This field is only applicable to [[Longtext_counter field]]s. It does not restrict the number of words, it just displays this limit next to a dynamic counter of the number of words already entered.
|-
| '''render_input''' || <tt>undef</tt> || NO || The name of a function which will render the input for this field. || This can be difficult to use as it must return the same CGI parameters as the default input form would have. It is easiest on simple fields. The subroutine is passed the following parameters: <code>$field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename</code> ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''required''' || <tt>0</tt> || NO || Whether the field must have a value set. || If this is set to <tt>1</tt> then the field is always marked as required, no matter what the [[Workflow Format]] configuration says.
|-
| '''separator''' || <tt>undef</tt> || NO || What character to use to separate elements of the value for the field for purposes of search || Only used by default for [[Keywords field]]s.
|-
| '''show_help''' || <tt>undef</tt> || NO || How to display the help text for this field in the input form. || Can be one of three values: <tt>always</tt>, <tt>never</tt> or <tt>toggle</tt>. Toggle (allow to expand or collapse) is used if not explicitly defined. This can only be overridden in [[Workflow Format]] configuration.
|-
| '''title_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the title for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the title of a field. If you need to change the title based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldname_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldname_id_number.article</code>).
|-
| '''toform''' || <tt>undef</tt> || NO || This function is allowed to modify the current value which appears in the form. || E.g. if your database stores <tt>userid</tt>s in a field, but you want to allow people to edit them as <tt>username</tt>s, then this function can be used to take the current value (a <tt>userid</tt>) and return the associated <tt>username</tt>. This value is what appears in the field in the search form. It is passed: <code>$value, $session, $object, $basename</code> and returns the user-facing version of <code>$value</code>.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''make_single_value_orderkey''' || <tt>undef</tt> || NO || The <tt>orderkey</tt> function (potentially language specific) used to order by this field. || This property allows you to define a function or refer to a predefined function to override the default EPrints' orderkey generation. This property is passed each value from multiple fields, in turn. It is passed: <code>$field, $value, $dataset</code> and returns an <tt>ordervalue</tt> string.
|-
| '''make_value_orderkey''' || <tt>undef</tt> || NO || Like <tt>make_single_value_orderkey</tt> but this is passed the array reference for a multiple field rather than just single values. || It should return the <tt>orderkey</tt> string for the entire value. It is passed: <code>$field, $value, $session, $langid, $dataset</code>.
|-
| '''match''' || <tt>EQ</tt> || NO || How to match the value(s) of this field against search terms. || This property can be <tt>EQ</tt>, <tt>EX</tt>, <tt>IN</tt> or <tt>SET</tt>. Default <tt>EQ</tt> means treat the search term as a single string. Match only whole search term matches the field value (or one of its values if <code>multiple => 1</code>). This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]].
|-
| '''merge''' || <tt>ALL</tt> || NO || Whether this field's values(s) has to match any or all of the search terms || This property can be <tt>ALL</tt> or <tt>ANY</tt>, Default <tt>ALL</tt> means all search terms have to match the values(s) in this field. This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]]. For certain values of <tt>match</tt> this can also be changed by the user in the search form itself.
|-
| '''text_index''' || <tt>0</tt> || NO || Whether the indexer considers this field for full-text indexing. || Some types of metadata field have a default of <tt>1</tt>, e.g. [[Text field]]s and [[Longtext field]]s.
|-
| '''search_cols''' || <tt>40</tt> || NO || How many characters (columns) wide the input field for searching this field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. If one search field searches more than one field, then the properties from the first field listed are used.
|}

=== Other Properties ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''allow_null''' || <tt>1</tt> || NO || Whether the value(s) stored in the database when no input is entered should be <tt>NULL</tt> or an appropriate default value based on its database field type. || This should generally never be set to <tt>0</tt> and certainly should not be changed to <tt>0</tt> after the field has been added to the database. You are much better off configuring a default value using <tt>[[eprint_fields_default.pl]]</tt> or similar.
|-
This may be applicable to [[Text field|text]]
| '''can_clone''' || <tt>1</tt> || NO || Whether the value(s) for this field should be cloned if a new record is created. || This property is mostly used by system fields such as <tt>dir</tt> or <tt>datestamp</tt>. It is applicable when an eprint is cloned using the <tt>Use as template</tt> or <tt>New version</tt> action buttons.
|-
| '''export_as_xml''' || <tt>1</tt> || NO || Whether the field value(s) should be exported in an XML export. || This is handy to suppress either confidential or confusing fields, like the <tt>fileinfo</file> [[EPrints Glossary#System_field|system field]].
|-
| '''import''' || <tt>1</tt> || NO || Whether new data objects create from an import can set values for the field. || E.g. <tt>eprintid</tt>, <tt>dir<tt> are determined when the eprint record is created. Imported metadata would not choose an appropriate value for such fields.
|-
| '''replace_core''' ||| <tt>0</tt> || NO || Whether the field configuration should replace the exisiting [[EPrints Glossary#Core_field|core (system) field]] with the same <tt>name</tt> || This is useful for particularly bespoke requirements. It should be used with great care, as system fields are usually hard-coded because they should not be changed.
|-
| '''show_in_fieldlist''' || <tt>1</tt> || NO || Whether to allow this field to appear in fields lists. || If set to <tt>0</tt> will prevent this field appearing in [[Fields field]] lists. This is primarily to allow you to remove it from the list of fields in the user configuration which are used to control which fields appear as columns in the Items and Review screens.
|-
| '''show_in_html''' || <tt>1</tt> || NO || Whether this field is not shown in the [[EPrints Glossary#Details_tab|Details tab]] of the [[EPrints Glossary#EPrint_control_page|eprint control page]]. || This is mostly used to hide confusing internal [[EPrints Glossary#System_field|system field]]s like <tt>dir</tt>.
|}

=== Internal Properties ===

These are set by the system. Editing them by hand will do '''''strange things'''''.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''confid''' || n/a || YES || The ID of the dataset to which this field belongs. || The value for this property is automatically set when the field is loaded. It is used to work out what phrase ids etc. it uses.
|-
| '''join_path''' || <tt>undef</tt> || NO || How to join a field that references a different [[Data Object]]. || This should never be defined within a field's configuration. This is built by search to support building a database query to perform a user's search.
|-
| '''parent''' || <tt>undef</tt> || NO || A reference to the actual parent [[Compound field]] object. || This is set automatically as a reference to the parent field object.
|-
| '''parent_name''' || <tt>undef</tt> || NO || The name of the parent [[Compound field]] to which a sub-field belongs. || This is set automatically to be the name of the parent field.
|-
| '''provenance''' || <tt>undef</tt> || NO || Where this field configuration was generated. || Typically any field configuration either defined within a [[Data Object|Data object]] or in a configuration file (in a <tt>cfg.d</tt> directory will leave this as <tt>undef</tt> by not specifying this property. However, fields created using [[Admin/Config._Tools/Manage_Metadata_Fields|Manage Metadata Fields]] will set this to <tt>user</tt> so it is clear from where this field was created.
|}

=== Deprecated Properties ===

Do not use these!

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''input_advice_below''' || <tt>undef</tt> || NO || Help text to put directly below the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_advice_right''' || <tt>undef</tt> || NO || Help text to put directly to the right of the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_assist''' || <tt>undef</tt> || NO || Provides input assistance. || Deprecated. Defined but no longer functional.
|-
| '''requiredlangs''' || <tt>[]</tt> || NO || The natural languages that should be used in the value(s) for this field || Deprecated. Defined but no longer functional.
|-
| '''sql_langid''' || <tt>undef</tt> || NO || The language ID for SQL. || Deprecated. Defined but no longer functional.
|-
| '''sql_sorted''' || <tt>0</tt> || NO || Whether SQL should be sorted. || Deprecated. Defined but no longer functional.
|}

== Methods ==
=== Constructor Methods ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !! Parameters !! Returns !! Description
|-
| '''new'''
||<code>$field = EPrints::MetaField->new( %properties )</code>
||
; $class : The sub-class of the new <code>EPrints::MetaField</code> to be created.
; %properties : A hash of the properties to be used to create this new <code>EPrints::MetaField</code> object. Also requires a <code>dataset</code> attribute to be set or otherwise both <code>confid</code> and <code>repository</code> attributes are required.
||A new instance of an <code>EPrints::MetaField</code>.

||Create a new <code>EPrints::MetaField</code> of the appropriate class.
|}

=== Class Methods ===
'''TO BE DONE'''
=== Object Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''field_defaults'''
||<code>$defaults = $field->field_defaults</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A hash reference of the default properties for the class of <code>EPrints::MetaField</code> of which this object is an instance.
||Provides the default properties of this <code>EPrints::MetaField</code> object.
|-
| '''final'''
||<code>$field->final</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''set_property'''
|| <code>$field->set_property( $property, $value )</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $property : The property to be set.
; $value : The value to set for the <code>$property</code>.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''clone'''
|| <code>$newfield = $field->clone</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A new <code>EPrints::MetaField</code> object that is a clone of the existing object.
||Clone the field, so the clone can be edited without affecting the original. Does not deep copy properties which are references - these should be set to new values, rather than the contents altered. E.g. Don't push to a cloned options list, replace it.
|
|-
| '''repository'''
|| <code>$repository = $field->repository</code>
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::Repository</code> object to which this field belongs.
|| Get the current repository object.
|
|-
| '''dataset'''
|| <code>$dataset = $field->dataset</code> (or <code>$dataset = $field->get_dataset</code>)
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::DataSet</code> object to which this field belongs.
|| Get dataset to which this field belongs.
|-
| '''render_help'''
|| <code>$xhtml = $field->render_help</code>
||
; $self : A <code>EPrints::MetaField</code> object.
|| A <code>XML::LibXML::DocumentFragment</code> containing the help text for the field.
|| Get the help information for a user inputting some data for this field as an XHTML chunk. Either from a phrase defined for the field or under the field property <code>help_xhtml</code>.
|-
| '''render_input_field'''
|| <code>$xhtml = $field->render_input_field( $session, $value, $dataset, $staff, $hidden_fields, $obj, $basename, $one_field_component )
</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object.
; $value : The value from the database to be rendered within this field.
; $dataset : The <code>EPrints::Dataset</code> to which the field belongs. (Does not always need to be defined)
; $staff : A boolean (typically <code>0</code> or <code>1</code>) for whether the but usually set to <code>0</code> as this should be managed through a conditional statement in the workflow.
; $hidden_fields : Extra fields associated with this field but rendered so they cannot be seen by the user (e.g. <code><input type="hidden" ... /></code>).
; $obj : A data object belong to the <code>$dataset</code> that has the <code>$value</code> set for this field.
; $basename : The basename for this field for uses as a prefix when a compound field that contains sub-fields.
; $one_field_component : A boolean (typically <code>0</code> or <code>1</code>) defining whether the workflow component that the field is being rendered has just this field or multiple fields in it.
|| A <code>XML::LibXML::DocumentFragment</code> containing an XHTML rendering of the field for input.
|| Get an XHTML rendering of the field for input. May be overridden with <code>render_input</code> property for this field.
|}

=== Utility Methods ===
'''TO BE DONE'''

=== Deprecated Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''display_name'''
|| <code>$dataset = $field->dataset</code> or <code>$dataset = $field->get_dataset</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object.
|| The UTF-8 encoded name of this field, in the language of the <code>$session</code> object.
|| Get the human-readable name for this field.
|}

== Required Phrases ==

These are phrases which you need to define in the local repository phrases file to control how this field renders. Some types of field (eg. [[set field]]s) have additional phrases in addition to the ones listed below.

The actual name of the field, as it will appear to users is stored in

datasetid + "_fieldname_" + fieldname

The default help to display, when the field is being input, is stored in

datasetid + "_fieldhelp_" + fieldname

For example:

<epp:phrase id="eprint_fieldname_abstract">Abstract</epp:phrase>
<epp:phrase id="eprint_fieldhelp_abstract">A summary of the items content.
If the item has a formal abstract then that is what should be entered
here. No complicated text formatting is possible.</epp:phrase>

== Database ==

Most fields have a representation in the SQL database using one or more columns. The sub-pages for each field type give the details.

== API ==

When you request (or set) a value of a metadata field, it is usually handled as a perl scalar (which is a string or number).

ALL values passed around in the API should be encoded in utf-8 or BAD THINGS may happen.

For example,

$eprint->set_value( "title", "For Us, The Living" );

Sets the title to the given string.

my $foo = $eprint->get_value( "title" );

Sets $foo to the string of the title, eg. "For Us, The Living".

=== Multiple Fields ===

If a field is set to multiple, then instead of a single value, a reference to an array of values is used. Eg.

$eprint->set_value( "corp_creators", [ "Jims Research", "Jones Research ] );

=== Other Exceptions ===

See the specific page for the full details.

* [[name field]]s are represented as a hash of the parts.

* [[compound field]]s do something a bit clever.

== Examples ==
Example field definitions that can be copied into an configuration file and edited as appropriates.

EPrints 3.4.7

2026-04-29T17:11:33Z

Drn@ecs.soton.ac.uk: /* Known Issues */ Added issue about error when looking up cache table UUID.

{{releasenotes}}

This page contains information about the EPrints v3.4.7 tag and release on GitHub.

== Release Notes ==
EPrints 3.4.7 is now available on [https://github.com/eprints/eprints3.4/releases/tag/v3.4.7 GitHub].
* '''Zero codename:''' ''Granita Gregale''
* '''Publications flavour codename:''' ''Tiramisu Tramontane''

=== New Dependencies ===
Check earlier dependencies for [[EPrints 3.4.6]] and before.

=== Upgrade Considerations ===
* If you are upgrading from an earlier version of EPrints 3.4.x and have the the [https://github.com/eprints/metatags metatags] ingredient enabled, as well as disabling this by removing it from your flavour's inc file, if your archive has its own '''cfg/cfg.d/eprint_render.pl''' file, you will need to make sure that the following lines are added to it after similar lines for <code>Export::Simple</code> and <code>Export::DC</code>:
$links->appendChild( $repository->plugin( "Export::HighwirePress" )->dataobj_to_html_header( $eprint ) );
$links->appendChild( $repository->plugin( "Export::Prism" )->dataobj_to_html_header( $eprint ) );

=== Changes Since 3.4.6 ===

==== New Functionality ====
* Adds <code>check_config</code> optioion to <code>tools/epm</code> allowing configuration files (under <code>cfg/</code>) to be compared between the EPM and the archive and potentially copied to the latter if the file is not already present.
* [https://github.com/eprints/eprints3.4/issues/425 Allows <code>bin/epadmin</code> to logout all users (possibly with 1 or more exclusions)]
* [https://github.com/eprints/eprints3.4/pull/434 Implements missing triggers <code>EP_TRIGGER_BEGIN</code> and <code>EP_TRIGGER_END</code>]
* Allows [https://github.com/eprints/eprints3.4/issues/445 browse view variation ordering by number]
* Adds [https://github.com/eprints/eprints3.4/pull/450 citation cache management script]
* [https://github.com/eprints/eprints3.4/issues/456 Allows static pages to be put behind login (with exceptions)]
* [https://github.com/eprints/eprints3.4/pull/462 Allows custom sort to be applied at a browse menu level]
* [https://github.com/eprints/eprints3.4/pull/490 Adds Highwire Press and PRISM meta tags to head of abstract pages] as favoured by Google Scholar

==== Security and Privacy Improvements ====
* [https://github.com/eprints/eprints3.4/pull/429 Fixes vulnerability in PrototypeJS]
** Severity: Low | By default EPrints does not make use of PrototypeJS in a way that actively exposes CVE-2020-27511. EPrints only allows an administrator to modify the JavaScript EPrints serves, such that the vulnerability could be exposed.
* [https://github.com/eprints/eprints3.4/issues/465 Uses different identifier for recalling search result caches so it cannot be guessed]
** Severity: Low | Change is only intended to partially mitigate certain excessive search queries, which can sometimes be processor intensive.
* [https://github.com/eprints/eprints3.4/issues/502 Ups to latest versions of jQuery and JQuery UI available in jquery ingredient]
** Severity: Low | jquery ingredient is not enabled by default. Minor upgrade of JQuery libraries is mainly to ensure versions do not fall too far behind the latest, as they may be needed to provide a repository's branding imported from another website.

==== General Improvements ====
* Tidies up comments under <code>lib/cfg.d/security.pl</code> to only refer to <code>EPrints::Repository->ip</code> function for getting the IP address of the request
* [https://github.com/eprints/eprints3.4/pull/416 Update Recaptcha3 to work with non-request workflows e.g. registration]
* [https://github.com/eprints/eprints3.4/issues/417 Improves <code>EPrints::Repository->remote_ip</code> to disregard invalid IP addresses in <code>X-Forwarded-For</code>]
* [https://github.com/eprints/eprints3.4/pull/436 Makes document thumbnails use long URL format]
* [https://github.com/eprints/eprints3.4/issues/439 Removes no longer supported <code>cgi/paracite</code> script]
* [https://github.com/eprints/eprints3.4/issues/443 Improve <code>restrict_paths</code> by only allowing some IP rather than just disallowing others]
* [https://github.com/eprints/eprints3.4/pull/451 Various improvements to citation caching]
* [https://github.com/eprints/eprints3.4/issues/454 Partially addresses spurious use of <code>X-Forwarded-For</code> header to pollute stats]
* [https://github.com/eprints/eprints3.4/pull/460 Prevents 'Manage Deposits' taking a long time to load with a lot of items]
* [https://github.com/eprints/eprints3.4/issues/463 Removes references to <code>secure.xml</code> template and <code>secure_auto.js</code>]
* Adds place as a <code>related_url</code> type
* [https://github.com/eprints/eprints3.4/pull/482/ Tides up use of <code>get_citaiton_id</code> in search screens]
* [https://github.com/eprints/eprints3.4/issues/475 Allows any item that has ever been in the live archive to be retired]
* [https://github.com/eprints/eprints3.4/issues/486 Allows <code>EPrints::Document</code> <code>search_related</code> to be ordered and limited to reduce number of cache tables generated]
* [https://github.com/eprints/eprints3.4/issues/476 Allows placeholder to be optionally displayed for un-named subjects in browse views]
* [https://github.com/eprints/eprints3.4/issues/479 Supports disabling of auto re-searching of cache ID for search has expired]
* [https://github.com/eprints/eprints3.4/issues/492 Supports plugins exporting as attachment rather that in-browser]
* [https://github.com/eprints/eprints3.4/pull/493 Adds 'export_file_as_attachment' option to force exports to be downloaded]
* [https://github.com/eprints/eprints3.4/pull/500 Add view option to suppress 'feeds']

==== Bug Fixes ====
* Fixes [https://github.com/eprints/eprints3.4/issues/399 <code>generate_apacheconf</code> has issues if archive missing <code>cfg/static/javascript/auto/</code>]
* Fixes [https://github.com/eprints/eprints3.4/issues/415 <code>Boolean</code> field has inconsistent phrase names]
* Fixes [https://github.com/eprints/eprints3.4/issues/418<code>tools/epm</code>'s <code>link_lib</code> and <code>unlink_lib</code> command so they only remove files referenced in the EPM directory's <code>.epm</code> / <code>.epmi</code> file]
* Fixes [https://github.com/eprints/eprints3.4/issues/420 UX/Accessibility issue with <code>Import</code> plugin actions]
* Fixes [https://github.com/eprints/eprints3.4/issues/421 History records not retaining formatting of email reasons]
* Fixes [https://github.com/eprints/eprints3.4/issues/422 disabling an EPM removes database tables and fields (and counters) it added to an archive]
* Better handles [https://github.com/eprints/eprints3.4/issues/419 <code>EPrint::MetaField->ordervalue_single</code> returning undefined]
* Fixes [https://github.com/eprints/eprints3.4/issues/427 long values in initial dataobj creation leading to empty rows in their database tables]
* [https://github.com/eprints/eprints3.4/issues/432 Updates URLs for GPL/GPL licences to point at GNU rather than Creative Commons website]
* Fixes [https://github.com/eprints/eprints3.4/pull/435 typos is template Accessibility report]
* Fixes [https://github.com/eprints/eprints3.4/issues/442 <code>EPrint::MetaField::Multipart->ordervalues_basic</code> does not forward all parameters]
* Fixes [https://github.com/eprints/eprints3.4/pull/426 Applying subtitle to <code>book_title</code> for book chapter items]
* [https://github.com/eprints/eprints3.4/pull/441 Aligns <code>basic-auth</code> in Sword and Auth modules] so passwords can contain non-word characters
* Fixes [https://github.com/eprints/eprints3.4/pull/449 Increment of data-row-cell-index for compound field header rows]
* Fixes [https://github.com/eprints/eprints3.4/issues/447 citation caching: non-linked cached citations]
* Fixes [https://github.com/eprints/eprints3.4/pull/438 before commit trigger changes not appearing in revision files]
* Fixes [https://github.com/eprints/eprints3.4/issues/452 <code>EPrints::Plugin::Search::Xapian->_get_records</code> cannot handle 0 results]
* Fixes [https://github.com/eprints/eprints3.4/issues/453 issues with ReCAPTCHAv3 form being able to submit]
* Fixes [https://github.com/eprints/eprints3.4/issues/455 <code>login_required_for_X</code> functionality not be able to redirect user to a specific page after login]
* [https://github.com/eprints/eprints3.4/pull/444 Fixes aspect ratio for video thumbnails if rotation matrix used]
* [https://github.com/eprints/eprints3.4/issues/457 Only crypt passwords that only contain printable ASCII]
* [https://github.com/eprints/eprints3.4/issues/458 Prevents other sub-field default occasionally be using for another compound field sub-field]
* [https://github.com/eprints/eprints3.4/pull/468 Fixes lightbox popup preview of a video]
* Fixes [https://github.com/eprints/eprints3.4/issues/470 Subobject <code>to_sax</code> causes 500 error if there are multiple and subobject is null]
* [https://github.com/eprints/eprints3.4/issues/470 Sets more sensible <code>maxlength</code> default for MetaFields that are <code>SQL_CLOB</code> to avoid truncation]
* Ensures depositable should be <code>TRUE</code> not <code>1</code> on initial subject creation through <code>Edit::Subject</code>
* Fixes [https://github.com/eprints/eprints3.4/issues/472 HTML citation export fails if export citation style for eprint exists]
* Ensures output from get_custom_view_header user-defined function can appear before or after the browse view navigation bar
* Removes no longer support <code>use encoding...</code> from random data generator
* [https://github.com/eprints/eprints3.4/pull/480 Makes 'Move' positions unique]
* [https://github.com/eprints/eprints3.4/pull/485 Retains attribute order in <code>build_attributes</code>]
* Fixes [https://github.com/eprints/eprints3.4/issues/459 Horizontal scrollbar when zoomed to 400%]
* Fixes [https://github.com/eprints/eprints3.4/issues/469 default values for search get re-enabled if field left empty]
* Fixes [https://github.com/eprints/eprints3.4/issues/473 broken aria reference if help phrase exists, but help isn't shown]
* [https://github.com/eprints/eprints3.4/issues/474 Adds cgi/register to accessibility check]
* Fixes logic support complex page ranges (e.g. A-2-B-4)
* Removes <code>rev_number</code> from eprints in test import data to prevent missing revisions when imported.
* Fixes [https://github.com/eprints/eprints3.4/issues/60 issues when splitting complex page ranges originally implemented for 3.4.2]
* Fixes [https://github.com/eprints/eprints3.4/issues/479 historic cache param causing excessive new cache tables]
* Removes eprint rev_number from test data this cause odd behaviour when importing
* [https://github.com/eprints/eprints3.4/pull/495 Prevents double presses on search buttons sending multiple requests]

== Known Issues ==
=== Session Initialisation and Close Bespoke Configuration ===
EPrints 3.4.7 replaces <code>$c->{session_init}</code> and <code>$c->{session_close}</code> configuration in '''lib/cfg.d/session.pl''' with <code>EP_TRIGGER_BEGIN</code> and <code>EP_TRIGGER_END</code> triggers. Although uncommon, if you have modified <code>session_init</code> in a later configuration file than session.pl and your session_init function requires the <code>EPrints::Repository</code>'s <code>offline</code> parameter then will not be sent to the function. Similarly, if you have modified the <code>session_close</code> function and this requires and <code>EPrints::Repository</code> object as a parameter, this will not be sent. These can be fixed with '''[https://github.com/eprints/eprints3.4/commit/cff8a57e643c230215279f187764fa6ec8d00a99.patch this patch]'''.

=== Error When Looking up UUID for Since Deleted Cache Table ===
When a repository receive a lot of searches or just a user bookmarks a search results URL. If this URL is requested again, the cache table it references may have already been deleted. Rather than checking this first it assume the CacheMap object exists and returns the error message
Can't call method "get_value" on an undefined value at /opt/eprints3/perl_lib/EPrints/Database.pm line 2258.
This can be fixed with the following patch: https://github.com/eprints/eprints3.4/commit/937487175b1cc3e6fc9f7cfbcca87d0dfec6e0ee.patch

== Further Planned Features and Improvements ==
See [https://github.com/eprints/eprints3.4/milestone/9 3.4.8 milestone on GitHub] for more details.

[[Category:Eprints3.4]]
[[Category:Releases]]

Template:EPrints Metadata Fields Content

2026-04-29T15:08:22Z

Drn@ecs.soton.ac.uk: Added some methods of main MetaField class

== Metadata Field Types ==

There are many different types of metadata field. The type controls how a field is rendered, indexed, searched and so forth. A field always has a type and a name property, and usually has several more. Most properties are documented on this page, but some properties are only available to certain types of field, and they are listed on the page for that field.

Some of these subclasses provide very rich features, others very simple. For example the [[url field]] works just like the text field except that it's only valid if it looks like a url and when rendered it is a hyper-link.

A metadata field describes one field of data in one type of [[Data Object]]. For example the "title" field of an [[EPrint Object]] or the "email" field in a [[User Object]].

Every [[Data Object]] has system fields (which are set by the system, and not alterable), but the [[User Object]] and [[EPrint Object]] have additional fields which are configured on a per-repository basis.

These can be customised in the [[user_fields.pl]] and [[eprint_fields.pl]] files. Note that changing these files does not automatically modify the underlying database so should (generally) only be done before the database is created. Some metadata properties do not affect the database, and are marked as such.

If you add or remove fields, or modify a property which affects the database then you'll need to alter the database to match. In 3.0 this must be done by hand, but we have plans to build a tool to do this for you.

== Inheritance ==

This is the list of ''useful'' field types. Under it is listed the other field types which are just included for completeness and are not intended to be used as part of the configuration.

Some field types inherit the properties of another, and then modify them in some way. For example the [[namedset field]] works like a [[set field]] except that it gets its options from a namedsets file not from the options=>[] in the field properties.

* '''Basic metadata field''' - this is abstract, fields must be one of the types listed below...
** '''[[Boolean field|Boolean]]''' - TRUE or FALSE (or can be unset, of course).
** '''[[Compound field|Compound]]''' - virtual field, joins together several "multiple" fields, e.g. author_name and author_email.
*** '''[[Dataobjref field|Dataobjref]]''' - references another data object.
*** '''[[Multilang field|Multilang]]''' - allows language variants of a field, e.g. titles in French, German and/or English.
*** '''[[Relation field|Relation]]''' - stores a typed relationship with something represented by a URI.
** '''[[Date field|Date]]''' - stores a date
*** '''[[Time field|Time]]''' - stores a date and time
**** '''[[Timestamp field|Timestamp]]''' - stores current date and time
** '''[[Float field|Float]]''' - stores a floating-point value
*** '''[[Decimal field|Decimal]]''' - stores a decimal number. Specifying the length of number before and after the decimal point.
** '''[[Id field|Id]]''' - like basic text field but search only finds exact matches
*** '''[[Idci field|Id (case-insensive)]]''' - like Id field but search find exact matches ignoring case (use for usernames, email addresses, etc.)
**** '''[[Email field|Email]]''' - an email address
*** '''[[Keywords field|Keywords]]''' - stores as longtext but searchable as exact individual keyword phrases
*** '''[[Recaptcha field|Recaptcha]]''' - virtual field to display a reCAPTCHA to prevent spamming of public input forms.
*** '''[[Text field|Text]]''' - the basic text field. Maximum 255 bytes. nb. uft-8 means some chars take more than one byte.
**** '''[[Longtext field|Longtext]]''' - like text but allows much longer text (65,000 bytes).
***** '''[[Longtext_counter field|Longtext counter]]''' - like longtext but with a word counter (requires [https://jquery.com/download/ jQuery])
**** '''[[Pagerange field|Pagerange]]''' - a range of page from one number to another.
**** '''[[Secret field|Secret]]''' - used to store passwords and other secrets.
**** '''[[Set field|Set]]''' - a limited set of options
***** '''[[Namedset field|Namedset]]''' - like a normal set, but takes its options from a [[namedset]] configuration file.
***** '''[[Subject field|Subject]]''' - possible values are taken from the [[Subject Object|Subject]] hierarchy.
***** '''[[Base64 field|Base64]]''' - stores Base64 encoded data.
****** '''[[Image field|Image]]''' - stores image encoded in Base64 data.
*** '''[[Url field|Url]]''' - stores a URL.
*** '''[[Uuid field|Uuid]]''' - stores a UUID.
** '''[[Int field|Int]]''' - an integer value
*** '''[[Bigint field|Bigint]]''' - a large integer value (can be greater than 2,147,483,647 or less than -2,147,483.647).
*** '''[[Counter field|Counter]]''' - an auto-incrementing integer value.
*** '''[[Itemref field|Itemref]]''' - a reference to another [[Data Object]] (e.g. a user or other eprint)
*** '''[[Pagerange field|Pagerange]]''' - a pagerange, e.g. 122-130
** '''[[Multipart field|Multipart]]''' - Stores a mutiple sub-fields like a person's name.
*** '''[[Name field|Name]]''' - Stores a person's name broken up into logical parts.
** '''[[Subobject field|Subobject]]''' - Stores another data object under a parent data object.

=== Internal-use and Deprecated Field Types ===
* '''Basic metadata field'''
** '''[[File field|File]]''' - '''DEPRECATED'''. Use [[Subobject field]] instead.
** '''Id'''
*** '''Text'''
**** '''Set'''
***** '''[[Arclanguage field|Arclanguage]]''' - as for set, but the options are the valid languages of this repository. Probably better to use [[Multilang field]].
***** '''[[Fields field|Fields]]''' - as for set, but the options are the fields in a dataset.
***** '''[[Langid field|Langid]]''' - used internally by [[Multilang field]]s to store the language ID.
**** '''Longtext'''
***** '''[[Search field|Search]]''' - a serialised search
** '''Int'''
*** '''[[Year field|Year]]''' - '''DEPRECATED'''. Use [[Date field]] instead.
** '''[[Storable field|Storable]]''' - Stores a serialization of a Perl data structure.

== Properties ==

Note that true/false properties use 1 and 0 to indicate their setting.

Some properties can be temporarily set or overridden by the [[Workflow Format]] and [[Citation Format]] files.

=== Core Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''name''' || n/a || YES || This is the internal name of the field. It should only contain alphanumeric characters and underscores. It will be used to identify this field in scripts, other configuration files, in the database, and in the XML export/import system, etc. || This property is ''not'' required when defining sub-fields of [[Compound field]]s where <tt>sub_name</tt> should be used. This property affects the database structure. It must be unique within the [[Data Object]] (so the [[EPrint Object]] cannot have two fields called <tt>email</tt> but the EPrint Object and [[User Object]] can each have a field with the same name.
|-
| '''type''' || n/a || YES || This sets the type of the metafield, which in turn affects what other properties it may have. || This property affects the database structure. The value must be one of the metafield types listed above.
|-
| '''multiple''' || <tt>0</tt> || NO || This indicates if this field is a single value or a list of values. E.g. <tt>title</tt> is only a single [[Longtext field]] but <tt>creators</tt> is a multiple [[Compound field]]. || This property affects the database structure. In the database a non-multiple field is stored in one (or more) columns in the main object table, but a multiple field gets its own table.
|-
| '''readonly''' || <tt>0</tt> || NO || Whether to not make this field editable in the workflow. || This is useful if you want to display the pre-generated value(s) for this field for reference whilst other fields are being edited.
|-
| '''sql_index''' || <tt>1</tt> || NO || When the database is created this field indicates that an SQL index should be created to speed searching. || This property affects the database structure. Different field types override the default value with the sensible option for that type of field. It is not worth putting a SQL index on a field that is only ever searched for words in it (like title or abstract) but it is worth indexing fields who's values are explicitly searched for, or where ranges are searched (e.g. [[Date field]]s, [[Set field]]s etc.). It is unlikely you will need to set this by hand. You could change it after the database has been created but this will not update the database nor have any other effect.
|-
| '''sub_name''' || <tt>undef</tt> || YES || This is a special property which is required ''instead'' of the <tt>name</tt> property for the sub-fields inside [[Compound field]]s. || This property affects the database structure. The actual name of these fields is then forced to be parent field <tt>name + '_' + sub_name</tt>. E.g. Compound field <tt>creators</tt> is a sub-field with <tt>sub_name => 'name'</tt>. In this case the actual name of the name field in the system, database etc. is <tt>creators_name/tt>.
|-
| '''virtual''' || <tt>0</tt> || NO || Whether this field calculates a value or stores in in the database. || [[Compound field]]s are virtual fields, whereas there sub-fields are not as they store values in the database. Other types of virtual field will require a <tt>render_value</tt> to be specified, as with no value stored the default render method will have nothing to display.
|-
| '''volatile''' || <tt>0</tt> || NO || Whether the field is liable to change frequently. || Setting <code>volatile => 1</code> will prevent new revisions being create and avoid other post commit events from being triggered, such as re-indexing.
|}

=== Rendering Properties ===

These properties affect how values of the metadata in this field are rendered.

Certain of these properties can be turned on temporarily by the [[Citation Format]] files - render_magicstop for example.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''as_list''' || <tt>undef</tt> || NO || Whether to display a collection sub-fields values as a table row or a separate list in the input form || This is only applicable for [[Compound field]]s that have <code>multiple => 1</code>. It is useful where the length of the table row would exceed the width of a typical user's window.
|-
| '''browse_link''' || <tt>undef</tt> || NO || This is the name of a view which values of this field should be linked to. || E.g. if there was a <tt>Browse by Publishers</tt> view configured named <tt>pubs</tt>, then adding <code>browse_link => 'pubs'</tt> to the <tt>publisher</tt> field would cause it to be linked into the browse view page for the named publisher whenever it is rendered.
|-
| '''render_custom''' || <tt>undef</tt> || NO || Whether to use a pre-defined way of rendering the value for this field. || E.g. for [[Name field]]s by default the name will link to the creators browse view for that name. This property can be re-used within bespoke render functions to specify whether some custom way of rendering this field' svalue (e.g. with a link) should be used.
|-
| '''render_dont_link''' || <tt>0</tt> || NO || Whether rendered field is not encapsulated in a hyperlink. || Currently only affects [[Url field]]s and [[Email field]]s.
|-
| '''render_dynamic''' || <tt>0</tt> || NO || Whether the rendering of this field can use JavaScript to make it dynamic. || [[limit_names_shown.pl]] uses this property to determine if the list of hidden creators/editors can be expanded to show all creators/editors.
|-
| '''render_limit''' || <tt>undef</tt> || NO || How many values for this field should be displayed. || [[limit_names_shown.pl]] uses this property to determine how many creators/editors to display. If <code>undef</code> just render all values.
|-
| '''render_magicstop''' || <tt>0</tt> || NO || Whether to render a full stop at the end of this field, unless the last character is a dot, question mark or exclamation mark. || This helps avoid the ugly <tt>World without Cheese?.</tt> effect you get when titles end in <tt>?</tt> or <tt>!</tt>.
|-
| '''render_noreturn''' || <tt>0</tt> || NO || Whether CR (Carriage Return) and LF (Line Feed) characters are turned into normal spaces. ||
|-
| '''render_quiet''' || <tt>0</tt> || NO || Whether to prevent a big ugly <tt>UNSPECIFIED</tt> being rendered if field is unset. || E.g. setting <code>render_quiet => 1</code> on a field means it just gets rendered as nothing if it is unset.
|-
| '''render_single_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render individual values from this field. || For a multiple field this is called once per value in the list of values. The function should take the following parameters: (<code>$session, $field, $value, $object</code>). It should return a [[XHTML DOM]] object of the rendered value.
|-
| '''render_value''' || <tt>undef</tt> || NO || The value of this property is the name of a function to call to render the the field as a whole. || As with <tt>render_single_value</tt>, but this gets passed the entire list of values (an array reference) if it is a multiple field. Parameters passed are: ( code>$session, $self, $value, $all_langs, $no_link, $object</code> ). <code>$all_langs</code> indicates that all language variants should be shown and is only really useful for [[Multilang field]]s. <code>$no_link</code> being true is a request to place no hyperlinks in the resulting HTML. The function should return an [[XHTML DOM]] object of the rendered value.
|}

=== Input and Validation Properties ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''default_value''' || <tt>undef</tt> || NO || The default value to set for this field. || This is mainly used for [[EPrints Glossary#System field|system fields]]. For custom fields it is better to use [[eprint_fields_default.pl]] or similar.
|-
| '''expanded_subjects''' || <tt>[]</tt> || NO || Subjects to show un-collapsed in the subject tree field in the workflow. || This is only applicable for [[Subject field]]s. All the fields listed will have their paths in the subject tree expanded so they can be seen, making them easier to find.
|-
| '''false_first''' || <tt>0</tt> || NO || Display the false option before the true option in the input form. || This is only applicable to [[Boolean field]]s. By default true option is always displayed before the false option.
|-
| '''fromform''' || <tt>undef</tt> || NO || The inverse of <tt>toform</tt>. This takes the value from the form and converts it into the value that will be stored in the database. || This function is passed the parameters: <tt>$value, $session, $object, $basename</tt> when <tt>$value</tt> is the value entered on the HTML form, and the return value is the value to be stored in the database. This function is not called when editing the eprint is cancelled.
|-
| '''get_item''' || <tt>undef</tt> || NO || A bespoke function for how to lookup the [[EPrints Glossary#Data object|Data object]] based on the stored value. || Only applicable to [[Itemref field]]s.
|-
| '''help_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the help text for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the help on a field. If you need to change the help text based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldhelp_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldhelp_id_number.article</code>).
|-
| '''input_add_boxes''' || <tt>2</tt> || NO || The number of rows to add when clicking the <tt>More input rows</tt> button for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_boxes''' || <tt>3</tt> || NO || The number of input rows to initially show for a field that sets <code>multiple => 1</code>. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>.
|-
| '''input_cols''' || <tt>60</tt> || NO || The number of columns in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. This in combination with the <tt>maxlength</tt> property determines the value for <tt>size</tt> attribute for <code><input></code> HTML fields or the <tt>cols</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''input_lookup_params''' || <tt>undef</tt> || NO || Additional parameters to pass to the <tt>input_lookup_url</tt>. || E.g. an indication of which autocomplete file to use.
|-
| '''input_lookup_url''' || <tt>undef</tt> || NO || The URL to use for autocompletion. || This is generally set using the workflow configuration rather than directly in the field configuration. The URL must be on the same server hostname as the repository.
|-
| '''input_ordered''' || <tt>1</tt> || NO || Whether the ordering of values needs to be captured. || In some <code>multiple => 1</code> fields, such as creators, the order of the values is important and by default numbers are shown to the left of input rows and to the right are ''move up'' and ''move down'' arrows. However, with some <code>multiple => 1</code> fields the order is not important, in which case you can set this to <tt>0</tt> to stop the arrows and numbers being shown.
|-
| '''input_rows''' || <tt>10</tt> || NO || The number of rows in an HTML form field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt> This property determines the value for <tt>size</tt> attribute for <code><select></code> HTML fields (used by [[Set field]]s) or the <tt>rows</tt> attribute for <code><textarea></code> HTML fields (used by [[Longtext field]]s).
|-
| '''maxlength''' || <tt>255</tt> || NO || The maximum allowed length in characters for a value. || This can be a very simple validation check. Also, it may confuse users to be allowed to type in 255 characters in a field intended for something like a postcode/zipcode.
|-
| '''maxwords''' || <tt>undef</tt> || NO || The maximum number of words that should be entered for this field. || This field is only applicable to [[Longtext_counter field]]s. It does not restrict the number of words, it just displays this limit next to a dynamic counter of the number of words already entered.
|-
| '''render_input''' || <tt>undef</tt> || NO || The name of a function which will render the input for this field. || This can be difficult to use as it must return the same CGI parameters as the default input form would have. It is easiest on simple fields. The subroutine is passed the following parameters: <code>$field, $session, $current_value, $dataset, $staff, $hidden_fields, $object, $basename</code> ). It should return the [[XHTML DOM]] object of the chunk of HTML form.
|-
| '''required''' || <tt>0</tt> || NO || Whether the field must have a value set. || If this is set to <tt>1</tt> then the field is always marked as required, no matter what the [[Workflow Format]] configuration says.
|-
| '''separator''' || <tt>undef</tt> || NO || What character to use to separate elements of the value for the field for purposes of search || Only used by default for [[Keywords field]]s.
|-
| '''show_help''' || <tt>undef</tt> || NO || How to display the help text for this field in the input form. || Can be one of three values: <tt>always</tt>, <tt>never</tt> or <tt>toggle</tt>. Toggle (allow to expand or collapse) is used if not explicitly defined. This can only be overridden in [[Workflow Format]] configuration.
|-
| '''title_xhtml''' || <tt>undef</tt> || NO || An [[XHTML DOM]] object to use for the title for this field. || This can only be set via the [[Workflow Format]] configuration not via the metadata field directly. This is so that the workflow can conditionally change the title of a field. If you need to change the title based on the eprint type, then you can just create a bespoke phrase with the format <code>"eprint_fieldname_" + fieldname + "." + eprint_type</code> (e.g. <code>eprint_fieldname_id_number.article</code>).
|-
| '''toform''' || <tt>undef</tt> || NO || This function is allowed to modify the current value which appears in the form. || E.g. if your database stores <tt>userid</tt>s in a field, but you want to allow people to edit them as <tt>username</tt>s, then this function can be used to take the current value (a <tt>userid</tt>) and return the associated <tt>username</tt>. This value is what appears in the field in the search form. It is passed: <code>$value, $session, $object, $basename</code> and returns the user-facing version of <code>$value</code>.
|}

=== Ordering, Indexing and Searching ===

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''make_single_value_orderkey''' || <tt>undef</tt> || NO || The <tt>orderkey</tt> function (potentially language specific) used to order by this field. || This property allows you to define a function or refer to a predefined function to override the default EPrints' orderkey generation. This property is passed each value from multiple fields, in turn. It is passed: <code>$field, $value, $dataset</code> and returns an <tt>ordervalue</tt> string.
|-
| '''make_value_orderkey''' || <tt>undef</tt> || NO || Like <tt>make_single_value_orderkey</tt> but this is passed the array reference for a multiple field rather than just single values. || It should return the <tt>orderkey</tt> string for the entire value. It is passed: <code>$field, $value, $session, $langid, $dataset</code>.
|-
| '''match''' || <tt>EQ</tt> || NO || How to match the value(s) of this field against search terms. || This property can be <tt>EQ</tt>, <tt>EX</tt>, <tt>IN</tt> or <tt>SET</tt>. Default <tt>EQ</tt> means treat the search term as a single string. Match only whole search term matches the field value (or one of its values if <code>multiple => 1</code>). This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]].
|-
| '''merge''' || <tt>ALL</tt> || NO || Whether this field's values(s) has to match any or all of the search terms || This property can be <tt>ALL</tt> or <tt>ANY</tt>, Default <tt>ALL</tt> means all search terms have to match the values(s) in this field. This can be modified for the [[API:EPrints/Search/Field|field in the search form configuration]]. For certain values of <tt>match</tt> this can also be changed by the user in the search form itself.
|-
| '''text_index''' || <tt>0</tt> || NO || Whether the indexer considers this field for full-text indexing. || Some types of metadata field have a default of <tt>1</tt>, e.g. [[Text field]]s and [[Longtext field]]s.
|-
| '''search_cols''' || <tt>40</tt> || NO || How many characters (columns) wide the input field for searching this field. || The default value for this property is taken from <tt>cfg.d/[[field_property_defaults.pl]]</tt>. If one search field searches more than one field, then the properties from the first field listed are used.
|}

=== Other Properties ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''allow_null''' || <tt>1</tt> || NO || Whether the value(s) stored in the database when no input is entered should be <tt>NULL</tt> or an appropriate default value based on its database field type. || This should generally never be set to <tt>0</tt> and certainly should not be changed to <tt>0</tt> after the field has been added to the database. You are much better off configuring a default value using <tt>[[eprint_fields_default.pl]]</tt> or similar.
|-
This may be applicable to [[Text field|text]]
| '''can_clone''' || <tt>1</tt> || NO || Whether the value(s) for this field should be cloned if a new record is created. || This property is mostly used by system fields such as <tt>dir</tt> or <tt>datestamp</tt>. It is applicable when an eprint is cloned using the <tt>Use as template</tt> or <tt>New version</tt> action buttons.
|-
| '''export_as_xml''' || <tt>1</tt> || NO || Whether the field value(s) should be exported in an XML export. || This is handy to suppress either confidential or confusing fields, like the <tt>fileinfo</file> [[EPrints Glossary#System_field|system field]].
|-
| '''import''' || <tt>1</tt> || NO || Whether new data objects create from an import can set values for the field. || E.g. <tt>eprintid</tt>, <tt>dir<tt> are determined when the eprint record is created. Imported metadata would not choose an appropriate value for such fields.
|-
| '''replace_core''' ||| <tt>0</tt> || NO || Whether the field configuration should replace the exisiting [[EPrints Glossary#Core_field|core (system) field]] with the same <tt>name</tt> || This is useful for particularly bespoke requirements. It should be used with great care, as system fields are usually hard-coded because they should not be changed.
|-
| '''show_in_fieldlist''' || <tt>1</tt> || NO || Whether to allow this field to appear in fields lists. || If set to <tt>0</tt> will prevent this field appearing in [[Fields field]] lists. This is primarily to allow you to remove it from the list of fields in the user configuration which are used to control which fields appear as columns in the Items and Review screens.
|-
| '''show_in_html''' || <tt>1</tt> || NO || Whether this field is not shown in the [[EPrints Glossary#Details_tab|Details tab]] of the [[EPrints Glossary#EPrint_control_page|eprint control page]]. || This is mostly used to hide confusing internal [[EPrints Glossary#System_field|system field]]s like <tt>dir</tt>.
|}

=== Internal Properties ===

These are set by the system. Editing them by hand will do '''''strange things'''''.

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''confid''' || n/a || YES || The ID of the dataset to which this field belongs. || The value for this property is automatically set when the field is loaded. It is used to work out what phrase ids etc. it uses.
|-
| '''join_path''' || <tt>undef</tt> || NO || How to join a field that references a different [[Data Object]]. || This should never be defined within a field's configuration. This is built by search to support building a database query to perform a user's search.
|-
| '''parent''' || <tt>undef</tt> || NO || A reference to the actual parent [[Compound field]] object. || This is set automatically as a reference to the parent field object.
|-
| '''parent_name''' || <tt>undef</tt> || NO || The name of the parent [[Compound field]] to which a sub-field belongs. || This is set automatically to be the name of the parent field.
|-
| '''provenance''' || <tt>undef</tt> || NO || Where this field configuration was generated. || Typically any field configuration either defined within a [[Data Object|Data object]] or in a configuration file (in a <tt>cfg.d</tt> directory will leave this as <tt>undef</tt> by not specifying this property. However, fields created using [[Admin/Config._Tools/Manage_Metadata_Fields|Manage Metadata Fields]] will set this to <tt>user</tt> so it is clear from where this field was created.
|}

=== Deprecated Properties ===

Do not use these!

{| cellpadding="3" cellspacing="0" border="1"
! Name !! Default Value !! Required !! Description !! Notes
|-
| '''input_advice_below''' || <tt>undef</tt> || NO || Help text to put directly below the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_advice_right''' || <tt>undef</tt> || NO || Help text to put directly to the right of the form input field || Deprecated. Defined but no longer functional.
|-
| '''input_assist''' || <tt>undef</tt> || NO || Provides input assistance. || Deprecated. Defined but no longer functional.
|-
| '''requiredlangs''' || <tt>[]</tt> || NO || The natural languages that should be used in the value(s) for this field || Deprecated. Defined but no longer functional.
|-
| '''sql_langid''' || <tt>undef</tt> || NO || The language ID for SQL. || Deprecated. Defined but no longer functional.
|-
| '''sql_sorted''' || <tt>0</tt> || NO || Whether SQL should be sorted. || Deprecated. Defined but no longer functional.
|}

== Methods ==
=== Constructor Methods ===
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !! Parameters !! Returns !! Description
|-
| '''new'''
||<code>$field = EPrints::MetaField->new( %properties )</code>
||
; $class : The sub-class of the new <code>EPrints::MetaField</code> to be created.
; %properties : A hash of the properties to be used to create this new <code>EPrints::MetaField</code> object. Also requires a <code>dataset</code> attribute to be set or otherwise both <code>confid</code> and <code>repository</code> attributes are required.
||A new instance of an <code>EPrints::MetaField</code>.

||Create a new <code>EPrints::MetaField</code> of the appropriate class.
|}

=== Class Methods ===
'''TO BE DONE'''
=== Object Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''field_defaults'''
||<code>$defaults = $field->field_defaults</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A hash reference of the default properties for the class of <code>EPrints::MetaField</code> of which this object is an instance.
||Provides the default properties of this <code>EPrints::MetaField</code> object.
|-
| '''final'''
||<code>$field->final</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''set_property'''
|| <code>$field->set_property( $property, $value )</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $property : The property to be set.
; $value : The value to set for the <code>$property</code>.
||n/a
||Tells the <code>EPrints::MetaField</code> that it is now read only. Any call to <code>set_property</code> will produce a abort error.
|-
| '''clone'''
|| <code>$newfield = $field->clone</code>
||
; $self : A <code>EPrints::MetaField</code> object.
||A new <code>EPrints::MetaField</code> object that is a clone of the existing object.
||Clone the field, so the clone can be edited without affecting the original. Does not deep copy properties which are references - these should be set to new values, rather than the contents altered. E.g. Don't push to a cloned options list, replace it.
|
|-
| '''repository'''
|| <code>$repository = $field->repository</code>
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::Repository</code> object to which this field belongs.
|| Get the current repository object.
|
|-
| '''dataset'''
|| <code>$dataset = $field->dataset</code> (or <code>$dataset = $field->get_dataset</code>)
||
; $self : A <code>EPrints::MetaField</code> object.
|| The <code>EPrints::DataSet</code> object to which this field belongs.
|| Get dataset to which this field belongs.
|}
=== Utility Methods ===
'''TO BE DONE'''

=== Deprecated Methods ===
'''TO BE COMPLETED'''
{| cellpadding="3" cellspacing="0" border="1"
! Name !! Exemplar !!Parameters !! Returns !! Description
|-
| '''display_name'''
|| <code>$dataset = $field->dataset</code> or <code>$dataset = $field->get_dataset</code>
||
; $self : A <code>EPrints::MetaField</code> object.
; $session : A <code>EPrints::Repository</code> object.
|| The UTF-8 encoded name of this field, in the language of the <code>$session</code> object.
|| Get the human-readable name for this field.
|}

== Required Phrases ==

These are phrases which you need to define in the local repository phrases file to control how this field renders. Some types of field (eg. [[set field]]s) have additional phrases in addition to the ones listed below.

The actual name of the field, as it will appear to users is stored in

datasetid + "_fieldname_" + fieldname

The default help to display, when the field is being input, is stored in

datasetid + "_fieldhelp_" + fieldname

For example:

<epp:phrase id="eprint_fieldname_abstract">Abstract</epp:phrase>
<epp:phrase id="eprint_fieldhelp_abstract">A summary of the items content.
If the item has a formal abstract then that is what should be entered
here. No complicated text formatting is possible.</epp:phrase>

== Database ==

Most fields have a representation in the SQL database using one or more columns. The sub-pages for each field type give the details.

== API ==

When you request (or set) a value of a metadata field, it is usually handled as a perl scalar (which is a string or number).

ALL values passed around in the API should be encoded in utf-8 or BAD THINGS may happen.

For example,

$eprint->set_value( "title", "For Us, The Living" );

Sets the title to the given string.

my $foo = $eprint->get_value( "title" );

Sets $foo to the string of the title, eg. "For Us, The Living".

=== Multiple Fields ===

If a field is set to multiple, then instead of a single value, a reference to an array of values is used. Eg.

$eprint->set_value( "corp_creators", [ "Jims Research", "Jones Research ] );

=== Other Exceptions ===

See the specific page for the full details.

* [[name field]]s are represented as a hash of the parts.

* [[compound field]]s do something a bit clever.

== Examples ==
Example field definitions that can be copied into an configuration file and edited as appropriates.

EPrints 3.4.6

2026-02-17T07:40:29Z

Drn@ecs.soton.ac.uk: /* General Improvements */

{{releasenotes}}

This page contains information about the EPrints v3.4.6 tag and release on GitHub.

== Release Notes ==
EPrints 3.4.6 is now available on [https://github.com/eprints/eprints3.4/releases/tag/v3.4.6 GitHub].
* '''Zero codename:''' Creme Brulee Cryoseism
* '''Publications flavour codename:''' Affogato Snowmelt

=== New Dependencies ===
Check earlier dependencies for [[EPrints 3.4.5]] and before.

=== Changes Since 3.4.5 ===

==== New Functionality ====
* Adds <code>unlink_lib</code> option to <code>tools/epm</code>.
* Adds <code>--to-link</code> flag to <code>unpack</code> option of <code>tools/epm</code> to allow an EPM file to be unpack so it can subsequently be deployed by <code>link_lib</code> option.
* [https://github.com/eprints/eprints3.4/issues/340 Provide support for converting HEIC and WEBP thumbnails]
* Adds support for setting default reply-to when separate <code>$c->{adminemail}</code> and <code>$c->{sendermail}</code>
* [https://github.com/eprints/eprints3.4/issues/388 Allows certain URL paths to be blocked for certain IPs]
* [https://github.com/eprints/eprints3.4/pull/387 Initial Signposting integration]

==== Security and Privacy Improvements ====
* [https://github.com/eprints/eprints3.4/issues/347 Implement stronger password hashing]
* [https://github.com/eprints/eprints3.4/issues/344 Creates and enables <code>export_privacy</code> setting to prevent export formats that include email addresses to be publicly accessible by default].
* Ensure <code>ga.js</code> is always served on HTTPS
* Makes sure <code>cache</code> parameter value provided by search form is a number to prevent URL injection.

==== General Improvements ====
* [https://github.com/eprints/eprints3.4/issues/336 Implement Recaptcha field to work with Google ReCAPTCHA v3]
* [https://github.com/eprints/eprints3.4/issues/339 Sets <code>ignore_login_ip = 1</code> by default if HTTPS is enabled]
* [https://github.com/eprints/eprints3.4/issues/345 Improvements Accessibility based on issues raised by axe DevTools]
* [https://github.com/eprints/eprints3.4/issues/348 Improves message when file retrieval fails]
* Adds <code>.gitignore</code> for ingredients other than those included, so those deploying EPrints using Git do not see new ingredients as uncommitted.
* Updates and tidies <code>SystemSettings.pm</code> and <code>SystemSettings.pm.in</code>
* [https://github.com/eprints/eprints3.4/issues/355 Adds function to get local path on disk for file object]
* [https://github.com/eprints/eprints3.4/pull/357 Overwrites media video stream if incoming stream is higher res]
* Uses <code>export</code> version of citation if exists (rather than <code>default</code>) for HTML export of data objects
* [https://github.com/eprints/eprints3.4/pull/359 Adds title attribute for preview images to display on hover]
* Adds function to test if citation style file exists
* Allows truncated URL linls to set a <code>target</code> attribute
* Provide large icons to be printed by EPC <code>icon</code> function
* Added EPC <code>text</code> function to print out phrases into HTML attributes values
* [https://github.com/eprints/eprints3.4/issues/362 Allows certain HTML formatting tags in imports, (e.g. from PubMed)]
* Adds title for action button image
* Allows fields of various types to be more customisable in search forms
* Reports useful error message if user tries to remove subject that has children
* [https://github.com/eprints/eprints3.4/issues/353 Allows way to pass timeout to indexer daemon]
* [https://github.com/eprints/eprints3.4/pull/351 Aligns headings when Itemref occurs within Compound Metafield]
* Log failure if email attempts send with <code>to_email</code> or <code>to_list</code> set
* Allows <code>EPrints::Repository::render_option_list</code> to render select box as disabled
* Ensures more consistent use of space for results listings where div rather than table rows are now used for better Accessibility
* Better margin for search results toolbar (e.g. Batch Edit)
* [https://github.com/eprints/eprints3.4/issues/367 Organise fields under stage in EPrint::View screen by workflow rather than data object]
* [https://github.com/eprints/eprints3.4/issues/370 Rewrite CitationCache code to use EPrints API rather than SQL query]
* [https://github.com/eprints/eprints3.4/issues/360 Allow "make open access" on request copy responses a disable-able field]
* [https://github.com/eprints/eprints3.4/issues/376 Allow signed in user to be logged in Apache access logs]
* [https://github.com/eprints/eprints3.4/pull/382 Adds lastmod attributes to entries in sitemap]
* [https://github.com/eprints/eprints3.4/issues/381 Add <code>threads</code> option to ffmpeg invocations]
* [https://github.com/eprints/eprints3.4/issues/392 Stop unnecessarily generating list of user's eprints twice for Manage Deposits page load]
* [https://github.com/eprints/eprints3.4/issues/374 Uses <code>Text::Unidecode</code> primarily to tokenize input for indexing] (rather than manually defining mappings)
* [https://github.com/eprints/eprints3.4/issues/373 Rework cpan_modules.pl to install all required Perl modules]
* Allows EPC to render icon without a link
* Adds commented out config option <code>show_ids_in_log</code>
* Removes long since deprecated pagehooks functionality
* Removes irrelevant <code>dbsid</code> config setting
* Improvements to simplify login monitoring configuration
* Remove reference to defunct <code>quiet</code> config setting

==== Bug Fixes ====
* Fixes [https://github.com/eprints/eprints3.4/issues/332 Downloading document from preview image does not work for some filenames]
* Fixes [https://github.com/eprints/eprints3.4/issues/333 Do not add <code>requester_userid</code> by default as access table can take a long time to add new fields. However, ensure if field exists it is set to current user ID, if set].
* Fixes serialization of EPM for <code>build</code> option of <code>tools/epm</code>.
* Fixes issues with <code>disable</code> and <code>unpack</code> options for <code>tools/epm</code>.
* [https://github.com/eprints/eprints3.4/issues/342 Duplicated "_label" span id]
* Fixes [https://github.com/eprints/eprints3.4/issues/341 Tab children deemed decorative]
* Fixes bug preventing user password updates from command line.
* Fixes intermittent issue with <code>xmlns:xsi</code> attribute being defined twice on some <code>/cgi/oai2/...</code> pages.
* Check that <code>uri</code> of relation is set before comparing its value for <code>EPrints::DataObj::remove_dataobj_relations</code>
* Check that <code>uri</code> of relation is set before comparing its value for <code>EPrints::MetaField::Relation::to_sax_basic</code>
* Check URL is set before testing its length in <code>EPrints::Extras::render_url_truncate_end</code>
* Fixes <code>EPrints::XML::SAX::Writer::escape</code> to make sure <code>$str</code> is set before applying regular expression
* Export bar form should use <code>rel_cgipath</code> not <code>http_cgiroot</code>
* Actually use <code>size</code> when calling <code>EPrints::DataObj::Document::render_icon_link</code>
* Ensure lookup of keyname is set before using it in <code>EPrints::Database::get_dataobjs</code>
* Testing an import should set the <code>filename</code> parameter like it would in a real import
* Checks <code>$c->{oai}->{comments}</code> is set before iterating over it.
* Prevents bin script from complaining about email-less users.
* Fixed EPC <code>contains</code> function to return a boolean value rather than a TRUE/FALSE string.
* [https://github.com/eprints/eprints3.4/pull/365 Allows documents to <code>redo_thumbnails</code> even if they have no parent eprint]
* Fixes wrong optione name for loading external DTDs in XML
* [https://github.com/eprints/eprints3.4/issues/366 Fixes overloading of etaField <code>render_quiet</code> attribute by introducing <code>render_column_quiet</code> attribute
* [https://github.com/eprints/eprints3.4/issues/369 Fixes unsecure request when uploading file]
* [https://github.com/eprints/eprints3.4/issues/371 Fix encoding issues for bespoke Export plugins]
* [https://github.com/eprints/eprints3.4/issues/334 Using page_id pin in page templates breaks editing static pages in web interface]
* Checks value is set before performing a regular expression replace in <code>EPrints::MetaField::Search::form_value_basi</code>
* [https://github.com/eprints/eprints3.4/issues/375 Return more appropriate <code>500</code> rather than <code>404</code> HTTP code if document present but database query fails]
* [https://github.com/eprints/eprints3.4/issues/377 Fixes drag 'n' drop issues leading to zero byte files]
* [https://github.com/eprints/eprints3.4/issues/378 Fixes "More input rows" button affecting layout of Compound field tables in workflow]
* Ensures clicking tabs on abstract pages does not reload page
* [https://github.com/eprints/eprints3.4/pull/380 Ensures fields sent in autocompleter requests are encoded]
* [https://github.com/eprints/eprints3.4/issues/383 Allows phrase editor to add phrases for alternative languages]
* [https://github.com/eprints/eprints3.4/issues/385 Fixes bug with edit subjects if ID field value is too long]
* Fixes warnings produced when <code>readonly</code> or <code>show_help</code> MetaField attributes are not defined when expected
* [https://github.com/eprints/eprints3.4/issues/48 Fixes further issue with <code>toform</code> attribute for <code>itemref</code> MetaField]
* Fixes warnings when using <codeEPrints::UTils::compare_version function
* [https://github.com/eprints/eprints3.4/issues/323 Fixes ancestor numbers (of items) in subject-based browse views]
* [https://github.com/eprints/eprints3.4/issues/390 Fixes slow page loads when user has lots of items under Manage Deposits]
* [https://github.com/eprints/eprints3.4/issues/249 Reverts changes to implement subject MetaField's <code>top</code> attribute as a function] (Best done through conditional in the workflow)
* Fixes XSLT import/export plugins so they no longer prevent EPrints being run using Apache MPM Event (i.e. threaded)
* [https://github.com/eprints/eprints3.4/issues/384 Ensure search pages respect <code>template</code> specified in their configuration]
* Makes sure XML converted to string does not contain any control/non characters that might break if they attempt to be rendered within XML.
* Fixes wrong config variable loads for <code>citation_default</code> for Dublin Core and simple export.
* Extends sanitization invalid characters for values of ID metadata fields and their subclasses.
* Fixes various typos
* [https://github.com/eprints/eprints3.4/issues/395 Fixes broken <code>eprint_status</code> filters when <code>get_users_owned_eprints</code> configuration function is defined]
* [https://github.com/eprints/eprints3.4/issues/394 Fixes incorrect white space in citations rendered in emails]

== Known Issues ==
=== Running generate_apacheconf with an archive without a cfg/static/javascript/auto/ directory ===
If you are upgrading an EPrints repository and your archive(s) do not have a <code>cfg/static/javascript/auto/</code> directory then <code>bin/generate_apacheconf</code> will fail. This is because 3.4.5 [https://github.com/eprints/eprints3.4/issues/286 introduces] code that makes sure that the maximum upload limit is configured to be the same in the Apache configuration and in EPrints' JavaScript, which prevents you from trying to upload files larger than a certain size. This is useful because if you just updated the JavaScript, EPrints would allow the upload to start but would then fail when the Apache limit was reached. So not only would you not be able to upload the file but you would waste a load of time and possibly not understand why the upload failed.

To fix this issue for this version of EPrints, just make sure your archive (or archives) all have a <code>cfg/static/javascript/auto/</code> before running <code>bin/generate_apacheconf</code>. Future versions of EPrints will automatically create this directory if it does not already exist.

=== Subject search does not work in workflows ===
If you have a subject field which renders as a subject tree in a workflow, the search form will not work. This is due to the [https://github.com/eprints/eprints3.4/issues/246 fix for ensuring Xapian respect a MetaField's <tt>text_index</tt> value]. This has the consequence of not indexing the <tt>ancestors</tt> field for subjects. This is used by the search to filter out subjects that are not part of the subject sub-tree for a particular MetaField. [https://github.com/eprints/eprints3.4/commit/3fbd47ccc0d9e66514455c693b62b902790e3326 This patch] fixes [https://github.com/eprints/eprints3.4/issues/411 the issue]. However, you will also need to re-index all subjects:
EPRINTS_PATH/bin/epadmin reindex ARCHIVE_ID subject

=== Approved document requests still force user to login ===
This issue was caused by setting the <code>samesite</code> attribute for the <code>eprints_doc_request</code> cookie to <code>Strict</code>, this cookie is intended to allow the user to access the restricted document for the remainder of their session. Changing this attributes means some browsers (e.g. Firefox) still send the user to a login page even when clicking the approved request link in the email they received. This is because the change made to the cookie prevents its from being stored because <code>/cgi/process_request</code> never fully serves a page. [https://github.com/eprints/eprints3.4/commit/278b5e599dc9f6aa1e4a20f3b211afabb2a4ea9a This patch] fixes the [https://github.com/eprints/eprints3.4/issues/413 the issue].

=== File uploads not check for size ===
If you use the "Browse..." or "Choose File" button to upload files using the file dialogue (drag 'n' drop is unaffected) it will not check if the size is above the maximum permitted according to <code>$c->{max_upload_filesize}</code>. If you do it will reach 100% but then it won't ever say it is complete and teh file won't actually have successfully uploaded. [https://github.com/eprints/eprints3.4/commit/2467b680373ac7be831e729a50c632ba7ec15e85This patch] fixes the [https://github.com/eprints/eprints3.4/issues/406 the issue].

== Further Planned Features and Improvements ==
See [https://github.com/eprints/eprints3.4/milestone/8 3.4.7 milestone on GitHub] for more details.

[[Category:Eprints3.4]]
[[Category:Releases]]

Shibboleth

2026-02-04T18:01:19Z

Drn@ecs.soton.ac.uk: Changed from sp_metadata.xml to sp-metadata.xml for better filename convention

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will just be different package names and different commands to manage applications.

Generally, it is a good idea to run EPrints with '''HTTPS''' when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP). Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an '''ssl/securevhost.conf''' under the archive directory structure.

== Installing Shibboleth ==
* First, add the Shibboleth repository to your list of YUM repositories (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use Yum to install all package dependencies:
root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling

* You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
overall configuration is loadable, check console for non-fatal problems

* If there are no other warning or error messages from ''shibd -t'', you can start it properly and check to make sure it is running. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
root> systemctl start shibd.service
root> ps aux | grep shib
shibd 29338 0.4 0.7 419784 15024 ? Ssl 11:16 0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
root 29345 0.0 0.0 112640 940 pts/2 S+ 11:17 0:00 grep --color=auto -i shib
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>

<Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
<MetadataProvider type="XML" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>

</ApplicationDefaults>

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>

* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
root> mkdir /etc/shibboleth/foo

* Copy '''attribute-map.xml''' into this new directory.
cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/

* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-cert.pem.old
root> mv sp-key.pem sp-key.pem.old

* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.
root> cd /etc/shibboleth
root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth

* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' and move the ''.old'' files back in place:
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-key.pem foo/
root> mv sp-cert.pem.old sp-cert.pem
root> mv sp-key.pem.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''shibd'''.
root> ls -l /etc/shibboleth/foo/sp-*
-rw-r--r-- 1 shibd shibd 1192 May 6 19:04 /etc/shibboleth/foo/sp-cert.pem
-rw------- 1 shibd shibd 1708 May 6 19:04 /etc/shibboleth/foo/sp-key.pem

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp-metadata.xml

* Modify ''' foo/sp-metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t
This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== Configuring Apache and EPrints ==
'''N.B. All these actions should be carried out by the ''eprints'' user, except when prepended with ''root>'' which means the command should be run as the ''root'' user.'''
* Add the following configuration to your archive's '''ssl/securevhost.conf''', after the '''Include /opt/eprints3/cfg/apache_ssl/foo.conf''', substituting '''foo''' for your archive's name where appropriate. (This assumes you are running Apache 2.4 or greater). See [[#Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration |Troubleshooting]] for instructions on the configuration to use for Apache 2.2. or lower.

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Location "/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

* Copy the following code into your archive (e.g. /opt/eprints3/archives/foo/) as '''cgi/shibboleth'''.
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );

$session->send_http_header( "content_type" => "text/html" );

print "<html><head/><body><code>\n";

foreach my $key (sort keys(%ENV)) {
print "<p>$key = $ENV{$key}</p>";
}

print "</code></body></html>";
$session->terminate;
exit;

* Now restart Shibboleth and Apache:
root> systemctl restart shibd.service
root> apachectl restart

* In a web browser go the '''/cgi/shibboleth''' page for your repository, (e.g. ''https://foo.eprints.org/cgi/shibboleth''). You should be redirected to an error page for your your Shibboleth IdP (e.g. ''https://shib.foo.example.org/idp/profile/SAML2/Redirect/SSO?...'').

* If instead you are displayed with a list of key values or are forbidden to access the page, you have not configured Apache properly, if so, see [[#Apache_Configuration_Issues|Apache_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]]. If you see an error message like the one below, you have not set up Shibboleth properly, if so, see [[#Shibboleth_Configuration_Issues|Shibboleth_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].
opensaml::saml2md::MetadataException
The system encountered an error at Wed May 6 15:19:27 2015
To report this problem, please contact the site administrator at root@localhost.
Please include the following message in any email:
opensaml::saml2md::MetadataException at (http://foo.eprints.org/cgi/shibboleth)
Unable to locate metadata for identity provider (https://shib.foo.example.org/idp/shibboleth)

* Next, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''cfg/cfg.d/zz_shibboleth.pl'''. This is needed to redirect login and logout to use Shibboleth rather than local login.
$c->{get_login_url} = sub {
my( $session, $target ) = @_;

# preserve CGI params
$session->read_params;
$target = $session->get_url(
host => 1,
path => "auto",
query => 1,
);

my $url = URI->new( $session->config( "https_url" ) . "/shibboleth/login" );
$url->query_form( target => "$target" );
return "$url";
};

$c->{on_logout} = sub {
my( $session ) = @_;
my $query = $session->query;
return unless defined $query;

# remove _shibsession_ cookie
my( $shibname, $shibvalue );
for( $query->cookie() ) {
if( $_ =~ /^_shibsession/ ) {
$shibname = $_;
$shibvalue = $query->cookie( $shibname );
}
}

my $cookie = $query->cookie(
-name => $shibname,
-path => "/",
-value => "",
-host => $session->config("cookie_domain"),
-expires => "-1d",
);
EPrints::Apache::AnApache::header_out(
$session->{request},
"Set-Cookie" => $cookie
);
};

push @{$c->{rewrite_exceptions}}, "/shibboleth/";

* Create a folder at the top level of your archive (e.g. ''/opt/eprints3/archives/foo/'') called '''shibboleth''' and copy the main CSS file for Shibboleth into this folder:
eprints> mkdir /opt/eprints3/archives/foo/shibboleth/
eprints> cp /usr/share/shibboleth/main.css /opt/eprints3/archives/foo/shibboleth/

* Now, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''shibboleth/login'''. This is the most basic login script that should work with the minimal attributes any Shibboleth IdP returns and '''only logging in users with existing accounts'''. Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your requirements, such as creation user accounts on-the-fly.
use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ( $username, $email ) = ( undef, "" );
if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
$email = $ENV{eppn};
}
return unless EPrints::Utils::is_set( $username );
my $user = $session->user_by_username( $username );
if( defined $user && defined $email )
{
$user->set_value( "email", $email );
$user->commit;
}
return $user;
}

* Next, add the following markup to '''cfg/lang/en/static/account_required.xpage''' under your archive (e.g. ''/opt/eprints3/archives/foo/''). Substituting ''staff and students of the University of Foo'' to describe to which particular group of people logged in access is restricted.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
<xpage:title>Login Failed</xpage:title>
<xpage:body>
<p style='text-align: center;'>Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" /></p>
</xpage:body>
</xpage:page>

* Now, reload Apache.
root> apachectl reload

* In a web browser go to the '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login''). Like before with ''/cgi/shibboleth'' you should be taken to your Shibboleth IdP's site albeit displaying an error message.

* The Shibboleth IdP shows an error message because EPrints as a Shibboleth Service Provider is not yet registered with it. To do this you need to send the administrator of the Shibboleth IdP the metadata for your Service Provider. You will have generated this earlier when you ran <code>metagen.sh</code>. Copy off your EPrints server the file that this wrote (e.g. to <tt>/etc/shibboleth/foo/sp-metadata.xml</tt>) and send it to the Shibboleth IdP administrator. They should be able to upload this to register EPrints as a Service Provider application.

* Once registered, use a web browser to go to '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'') again. This time you should be prompted for a username and password on the Shibboleth IdP site. Once you have typed this in and clicked to login, you should be returned to EPrints on the '''/cgi/users/home''' page for your repository. If not, see [[#Login_Issues|Login Issues]] under [[#Troubleshooting|Troubleshooting]] below.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just '''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case. The Shibboleth Service Provider can be [[Shibboleth Debug Logging|run in debug mode]], which may help your figure out what attributes are being mapped..

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ($username, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== Further Information ==
* Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available [[Shibboleth authentication|here]].

* For general information about installing and configuring Shibboleth [http://shibboleth.internet2.edu/ click here].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

EPrints Flavours

2026-01-27T10:09:04Z

Drn@ecs.soton.ac.uk:

Since EPrints 3.4 flavours have been introduced into EPrints. Flavours provide customisation for different types of EPrints. The following four flavours are currently exist:
# '''Publications''' - This is the original EPrints for research publications. Its flavours sub-directory is '''[[flavours/pub_lib/|pub_lib]]''', which comes as part of the core codebase but is provided separately on [https://files.eprints.org files.eprints.org].
# '''Research Data''' - This provides specific customisations for research data. Its flavours sub-directory is '''[[flavours/data_lib/|data_lib]]'''.
# '''Open Education''' - This provides specific customisations for open education, previously known as EdShare. Its flavours sub-directory is '''[[flavours/edu_lib/|edu_lib]]'''.
# '''Research Impact''' - This provides specific customisations for capturing research impact. Its flavours sub-directory is '''[[flavours/impact_lib/|impact_lib]]''' and can be checked out from [https://github.com/eprints/impact_lib GitHub].

== Installing a Flavour ==
If you install EPrints from [https://files.eprints.org files.eprints.org] instead of before when you could just download a single tarball, you will need to:

# Download the '''EPrints Zero''' tarball which is a base version of EPrints without any specializations for publications, like was the case for EPrints 3.3 and earlier.
# Unpack the '''EPrints Zero''' tarball to '''[[EPrints_Directory_Structure_Tree|/opt/eprints3/]]'''
# Download the flavour you want, such as the publication flavour tarball, and unpack it into '''[[EPrints_Directory_Structure/eprints3/flavours|/opt/eprints3/flavours/]]'''.

After you have finished installing EPrints as a flavour, you may also want to add [[EPrints Ingredients|Ingredients]]. Ingredients are often similar to [https://bazaar.eprints.org Bazaar] plug-ins and intend to replace some of the more complex Bazaar plug-ins, which are not really suited to a one-click installation as they need extensive configuration and/or non-EPrints dependencies.

[[Category:Customisation]]

Flavours/impact lib/

2026-01-27T10:08:43Z

Drn@ecs.soton.ac.uk: Added impact_lib directory

{{dirs}}
{{noeditdir}}

The '''flavours/impact_lib/''' directory contains configuration and code for the [[EPrints Flavours|impact flavour]]. Like the [[EPrints_Directory_Structure/eprints3/lib|lib/]] directory, files under this directory should not be modified but instead copied to the equivalent archive level directory and modified there.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/[[EPrints_Directory_Structure/eprints3/flavours|flavours]]/impact_lib'''
** ''TO BE ADDED''

EPrints Flavours

2026-01-27T10:07:34Z

Drn@ecs.soton.ac.uk: Added impact flavour

Since EPrints 3.4 flavours have been introduced into EPrints. Flavours provide customisation for different types of EPrints. The following four flavours are currently exist:
# '''Publications''' - This is the original EPrints for research publications. Its flavours sub-directory is '''[[flavours/pub_lib/|pub_lib]]''', which comes as part of the core codebase but is provided separately on [https://files.eprints.org files.eprints.org].
# '''Research Data''' - This provides specific customisations for research data. Its flavours sub-directory is '''[[flavours/data_lib/|data_lib]]'''.
# '''Open Education''' - This provides specific customisations for open education, previously known as EdShare. Its flavours sub-directory is '''[[flavours/edu_lib/|edu_lib]]'''.
# '''Research Impact''' - This provides specific customisations for capturing research impact. Its flavours sub-directory is '''[[flavours/impact_lib/|impact_lib]]''' and can be checked out from [https://github.com/eprints/impact_lib|GitHub].

== Installing a Flavour ==
If you install EPrints from [https://files.eprints.org files.eprints.org] instead of before when you could just download a single tarball, you will need to:

# Download the '''EPrints Zero''' tarball which is a base version of EPrints without any specializations for publications, like was the case for EPrints 3.3 and earlier.
# Unpack the '''EPrints Zero''' tarball to '''[[EPrints_Directory_Structure_Tree|/opt/eprints3/]]'''
# Download the flavour you want, such as the publication flavour tarball, and unpack it into '''[[EPrints_Directory_Structure/eprints3/flavours|/opt/eprints3/flavours/]]'''.

After you have finished installing EPrints as a flavour, you may also want to add [[EPrints Ingredients|Ingredients]]. Ingredients are often similar to [https://bazaar.eprints.org Bazaar] plug-ins and intend to replace some of the more complex Bazaar plug-ins, which are not really suited to a one-click installation as they need extensive configuration and/or non-EPrints dependencies.

[[Category:Customisation]]

Main Page

2026-01-27T08:37:18Z

Drn@ecs.soton.ac.uk: /* Add-ons, patches and translations */

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://pub.demo.eprints-hosting.org/ examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]] - Videos showing how to use, configure, maintain and develop EPrints repository software.
* [[EPrints_Manual|Documentation]] - Written documentation for how to use, configure, maintain and develop EPrints repository software.
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==[[New_Repository | Getting Started]]==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/eprints-services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==
* As of version 3.4 EPrints can be deployed in one of a number of [[EPrints Flavours|flavours]]. The flavours can be supplemented with [[EPrints Ingredients|ingredients]]. These ingredients are [https://github.com/search?q=topic%3Aingredient+org%3Aeprints+org%3Aeprintsug&type=repositories available from GitHub].
* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

Main Page

2026-01-27T08:36:16Z

Drn@ecs.soton.ac.uk: /* Add-ons, patches and translations */ Added point about 3.4 ingredients

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://pub.demo.eprints-hosting.org/ examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]] - Videos showing how to use, configure, maintain and develop EPrints repository software.
* [[EPrints_Manual|Documentation]] - Written documentation for how to use, configure, maintain and develop EPrints repository software.
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==[[New_Repository | Getting Started]]==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/eprints-services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==
* As of version 3.4 EPrints can be deployed in one of a number of [[EPrints FLavours|flavours]]. The flavours can be supplemented with [[EPrints Ingredients|ingredients]]. These ingredients are [https://github.com/search?q=topic%3Aingredient+org%3Aeprints+org%3Aeprintsug&type=repositories available from GitHub].
* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

Main Page

2026-01-27T08:03:27Z

Drn@ecs.soton.ac.uk: /* New to EPrints? */ Added descriptions for videos and documentation. Removed link to working groups

[[Category:Howto]]__NOTOC__
= Welcome to the EPrints Wiki =

This wiki contains technical and user-contributed documentation for the [[Introduction|EPrints repository software]].

[http://tryme.demo.eprints-hosting.org/ Demoprints] is our live, online server that allows anyone to try EPrints without having to install it first. There are also [http://pub.demo.eprints-hosting.org/ examples] of various 'flavours' of EPrints available to view as well as some more information on the [https://eprints.org/ EPrints project] and related activities.

==New to EPrints?==

Found out more through our:
* [[EPrints Glossary]] - Descriptions of the terminology used within EPrints repository software.
* [[:Category:Training Video|Video Training Course]] - Videos showing how to use, configure, maintain and develop EPrints repository software.
* [[EPrints_Manual|Documentation]] - Written documentation for how to use, configure, maintain and develop EPrints repository software.
* Mailing lists - There are two mail lists that you might like to join and where you can ask for help and share ideas:
** '''[[eprints-tech Mailing List|The EPrints Technical Mailing List]]'''
*** If you have technical questions, or a part of your EPrints installation is not working properly, this group has people who might be able to help!
*** [[eprints-tech Mailing List|Click here]] for information about [[eprints-tech Mailing List#Subscription_Options|subscribing to this list]] or [[eprints-tech Mailing List#List_Archives|reading its archives]].
** '''[https://groups.google.com/forum/#!forum/eprints-uk-user-group The EPrints User Group Google Group]'''
*** This group is for anyone involved in using EPrints. Ask questions, share ideas, hear about forthcoming meetings.
* How to [[Main_Page#Contributing_to_the_Wiki|contribute to the EPrints wiki]]
* EPrints source code on GitHub:
** Core and major plugins - https://github.com/eprints
** Community code sharing - https://eprintsug.github.io and the repositories at https://github.com/eprintsug

== Download EPrints ==

{{Download}}

==Installation==

* [[:Category:Installation|Installing]] EPrints on various platforms

==[[New_Repository | Getting Started]]==

* [[EPrints Manual|EPrints 3 Documentation]]
* [[Perl 101 for EPrints]]
* [[Frequently Asked Questions]]
* [[:Category:Howto|How to ...]]
* [[:Category:Plugins|Plugins and Bazaar packages for EPrints]]
* [[:Category:Training Video|EPrints Training Course]]

==Getting Support==

* [https://www.eprints.org/eprints-services/ EPrints Services] - premium support, training and hosting from EPrints experts
* [[Contact]] - mailing lists, bug reports etc.
* [[User group meetings]] - regional meetings for users, which often have notes, presentations and information of general interest

==Add-ons, patches and translations==

* As of version 3.3 EPrints can now install plugins and translations through the [https://bazaar.eprints.org EPrints Bazaar] the wiki also has information about [[:Category:EPrints Bazaar|packaging plugins for the Bazaar]].
* The [https://files.eprints.org/ EPrints Files Repository] contains add-on and 3rd party scripts, patches and translations. This also provides an archive of all previous EPrints releases (3.0 onwards).
* [[:Category:Plugins|Plugins]]: Some Wiki pages about scripts and patches.

{{Register}}

==Contributing to EPrints==

* [[Usability|EPrints usability]]
* New features in EPrints - [[:Category:Releases|released]] and [[:Category:Planned Releases|proposed]]
* [[How to contribute|How to contribute to EPrints development]]
* [https://github.com/eprints/eprints3.4 EPrints 3.4 on GitHub] - Codebase, releases and issues tracker for EPrints 3.4.
* [https://github.com/eprints/eprints3 EPrints 3.3 on GitHub] - Codebase, releases and issues tracker for EPrints 3.3 (legacy).

== Content management ==

* [[Digital preservation]]: managing content for longer-term access and use

MediaWiki:Sidebar

2026-01-26T16:21:00Z

Drn@ecs.soton.ac.uk: Added glossary to sidebar

Manual

2026-01-26T16:14:27Z

Drn@ecs.soton.ac.uk: /* Installation */ upped version numbers for OS

__NOTOC__
See the [[Main Page]] for other areas of this wiki.

* [[Introduction|Introduction to EPrints]] and [[History|History of EPrints]]

<table cellpadding="10"><tr><td width="33%" valign="top">
= Releases =
{{releasenotes}}
''See also the note on [[EPrints Version Numbering]]''

= Download =
{{Download}}

= Installation =
* [[Recommended Platforms]]
* [[Required software]]
* Install Guides
** [[Installing EPrints on RHEL/Fedora/CentOS]]
*** Primarily RedHat Enterprise Linux (RHEL) and Rocky Linux 8 or 9 (and latterly 10)
*** Guides for installing from RPM package and from source.
** [[Installing EPrints on Debian/Ubuntu]]
*** Primarily Ubuntu 22.04 LTS and 24.04 LTS.
*** Guides for installing from Deb package and from source.
* [[Installation|Generic EPrints installation instructions]]
* [[How to use EPrints with HTTPS]]
** [[Setting up HTTPS using Let's Encrypt]]
** [[HTTPS-only and HSTS]]
* [[Installing EPrints using Docker]]

= Post Installation =
* [[Getting Started with EPrints 3]]

= Maintenance =
* [[Backups]]
* [[Generate Scripts]]
* [[Alerts]]
* [[Log Files]]
* [[Automating your maintenance]]
* [[Troubleshooting]]
* [[Apache Hardening]]
</td>

<td width="33%" valign="top" style="border-left: solid 1px #ccc; border-right: solid 1px #ccc;">

= Training Materials =
* [[:Category:Training Video|EPrints Training Course]]
* [http://www.eprints.org/software/training/ Training materials] provided by EPrints Services.

= How-to Guides =
''[http://en.wikipedia.org/wiki/Howto What is a how-to?]

* [[:Category:Howto|Orientation/Overview]] <span style="color: #f94; font-size: 130%">(Start here)</span>
** [[Configuration orientation|New to EPrints 3?]] - ''before diving into the how-tos, take some time to read through this brief orientation guide and familiarise yourself with the EPrints configuration landscape ...''
* [[Front Page Warning | Removing the Front Page Warning]] - Your first go at branding
* [[Branding with confidence]] - ''one of the most common EPrints customisations is to add your own institution's branding and "look and feel" to the interface...''
** [[Branding, the next level]] - ''how to completely change the interface to your own design''
* [[OAI]]
* [[Adding new views]]
* Workflow
* Deposit Types
** [[Removing types]]
* Metadata
* Subjects (fold in with Organisation Hierarchy under "controled vocabularies")
* [[EPrints_3_Organisation_Hierarchy|Organisation Hierarchy]] - ''how to put your own organisation's Hierarchy into EPrints 3''
* Searches
* [[Autocompletion and Authority Files (Romeo Autocomplete)]] - ''add autocomplete functionality to the Publication Title input field based on an authority file downloaded from EPrints Romeo...''
* [[Create Export Plugins]] - ''create a Perl Module that will export your data...''
* [[Login-Only Repository]] - ''require a username and password to access all pages (including search, browse, and the front page)...''
* [[Change Deposit Status in Bulk]] - ''move a large number of deposits from inbox to archive.''
* [[SWORD]] - ''how to configure the SWORD protocol on EPrints.''
* [[Custom handlers]] - ''how to add a custom handler for intergration with third-party applications.''
* [[User Deposit Agreement]] - ''How to add a user deposit agreement to the workflow.''
* [[ORCID]]
** [[Import From ORCID]]
* Javascript
** [[Include Javascript in the workflow]]
* DKIM email verification
** [[How to configure DKIM email verification (using sendmail on Rocky9)]]

= How to contribute =
There's a number of different ways you can contribute to the EPrints project. This section covers all the ones we can think of...

Always make an entry on http://files.eprints.org/ for your contribution, even if you don't upload the files. This will make it the one-stop place for people to find EPrints extensions.

* [[:Category:Documentation Needed| Create some of the missing documentation]]
* [[Contribute: Plugins | Plugins]]
* [[Contribute: Scripts | Scripts]]
* [[Contribute: Themes | Themes]]
* [[Contribute: Translations | Translations]]
* [[Contribute: Other | Other neighbourly things to do]]
* [[Extension Packages]]

= Misc =
* [[Preservation Support]] in EPrints 3
* [[:Category:Languages|Language support and translations]]
</td><td valign="top" width="33%">

= Technical Reference =
* [[EPrints Directory Structure]] - How code and configuation files are organised.
* [[EPrints Glossary]] - A listing of terminology used within EPrints.
* [[User Menu]] - Explaining the menu options available to an EPrints user.
* [[Admin|Admin Menu]] - Explaining the tools available to a repository administrator.
* [[Metadata]] - configuring metadata fields.
* [[Archives/ARCHIVEID/cfg/|Repository Configuration]]
* [[XML Configuration]] Files
** [[EPScript]] - documentation for the EP3 Scripting language (for use in citations and workflow files).
** [[EPrints Control Format]] - the structure used to embed EPScript in an XML configuration file.
** [[Citation Format]]
** [[Workflow Format]] - the structure of the EP3 workflow files
** [[Phrase Format]]
** [[Template Format]]
** [[XPAGE Format]]
* [[XML Export Format]]
* EPrints data structure
** of the software
** of the database (relating the dataobjects to each other using eprints fields)
* [[Data Object]]s and data sets
** The [[EPrint Object]]
** The [[User Object]]
** The [[Document Object]]
** The [[Subject Object]]
** The [[Saved Search Object]]
** The [[History Object]]
** The [[Access Object]]
** The [[Request Object]]
* [[:Category:Plugins|Plugins]]
** [[Create Export Plugins|Export]]
** Import
** [[Screen Plugins|Screen]]
* [[Autocompletion]]
** [[Understanding IDs in Workflow Forms]]
* [[API]]
* [[Dynamic Template System]]
* [[Config Options by File]]
* [[Triggers|Trigger functions]]

= The EPrints Bazaar =
* [[:Category:EPrints_Bazaar|The EPrints Bazaar]] (Start Here)
* The [[EPM Specification]]
* [[:Category:Bazaar_Package|Bazaar Packages]]

</td></tr></table>

Installation

2026-01-26T16:12:23Z

Drn@ecs.soton.ac.uk:

{{manual}}
[[Category:Installation]]

*<big><big>[[Installing EPrints on RHEL/Fedora/CentOS|Installation on Red Hat Enterprise based Linux]]</big></big>

*<big><big>[[Installing_EPrints_on_Debian/Ubuntu|Installation on Debian/Ubuntu]]</big></big>

*<big><big>[[Generic Linux Installation|Installation on Generic Linux Operating System]]</big></big>

<hr/>

{{:Category:Installation}}

Installation

2026-01-26T16:11:55Z

Drn@ecs.soton.ac.uk:

Installation

2026-01-26T16:11:16Z

Drn@ecs.soton.ac.uk:

{{manual}}
[[Category:Installation]]

*<big><big><big>[[Installing EPrints on RHEL/Fedora/CentOS|Installation on Red Hat Enterprise based Linux]]</big></big></big>

*<big><big><big>[[Installing_EPrints_on_Debian/Ubuntu|Installation on Debian/Ubuntu]]</big></big></big>

*<big><big><big>[[Generic Linux Installation|Installation on Generic Linux Operating System]]</big></big></big>
<br/>
<hr/>

{{:Category:Installation}}

Installation

2026-01-26T16:10:45Z

Drn@ecs.soton.ac.uk:

MediaWiki:Sidebar

2026-01-26T16:10:25Z

Drn@ecs.soton.ac.uk: Switch to main installation page not category

Installation

2026-01-26T09:10:09Z

Drn@ecs.soton.ac.uk:

Installation

2026-01-26T09:09:58Z

Drn@ecs.soton.ac.uk:

Installing EPrints on Debian/Ubuntu

2026-01-26T09:04:16Z

Drn@ecs.soton.ac.uk: Added to manual

{{manual}}
[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 11 (Bullseye) or Debian 12 (Bookworm) - These are not as comprehensively tested as Ubuntu LTS versions.

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page):

apt install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

If you are installing on Ubuntu, install MySQL server and client:

apt install mysql-server mysql-client libmysqlclient-dev

If you are installing on Debian, install MariaDB server and client:

apt install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

adduser eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.7

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/3288/1/eprints-3.4.7.tar.gz
tar -xzvf eprints-3.4.7.tar.gz

Then put in the source code in place:

mv eprints-3.4.7 /opt/eprints3
chmod 2775 /opt/eprints3
chown -R eprints:eprints /opt/eprints3

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3288/2/eprints-3.4.7-flavours.tar.gz
tar -xzvf eprints-3.4.7-flavours.tar.gz
mv eprints-3.4.7/flavours/pub_lib /opt/eprints3/flavours
chmod -R g+w /opt/eprints3/flavours/pub_lib
chown -R eprints:eprints /opt/eprints3/flavours/pub_lib

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>, if it does not already exist.

<code>EPRINTS_PATH</code> should now always be <code>/opt/eprints3</code>. However, historically other paths have been used when EPrints was available as a Deb package.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

root> a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the '''Admin''' link under the Logged in menu, then clicking on the '''System Tools''' tab and finally the '''Start Indexer''' button.

== Operating System Version Specific Requirements ==

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Ubuntu 24.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 24.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on RHEL/Fedora/CentOS

2026-01-26T09:03:52Z

Drn@ecs.soton.ac.uk: Added to manual

{{manual}}
[[Category:Installation]]

== Requirements ==
* Red Hat Enterprise (RHEL) / CentOS / Rocky Linux 8 or 9. (EPrints can be installed on RHEL / CentOS / Rocky Linux 10 but there are currently a [[#RHEL / CentOS / Rocky 10|number of issues]], some which should be resolved in later version of these Linux OSs).

== Prerequisites ==
* Pre-install and enable the EPEL DNF repository.
**: <code>dnf install epel-release</code>
* Pre-install and enable the CodeReady Builder DNF repository.
** RHEL
**: <code>subscription-manager repos --enable "codeready-builder-for-rhel-$(releasever)-$(arch)-rpms"</code>
** CentOS Stream / Rocky Linux 8
**: <code>dnf config-manager --set-enabled powertools</code>
** CentOS Stream / Rocky Linux 9 and 10
**: <code>dnf config-manager --set-enabled crb</code>
* Pre-install MySQL server and client and make sure the former is enabled and running.
** RHEL / Fedora:
**: <code>dnf install mysql-server mysql mysql-devel<br/> systemctl enable --now mysqld</code>
** CentOS / Rocky Linux:
**: <code>dnf install mariadb-server mariadb mariadb-devel<br/> systemctl enable --now mariadb</code>
* From the MySQL command prompt, pre-configure an eprints user with password for MariaDB/MySQL, which can be used as the Database super user when creating the database for an archive. (Be sure to change the password from "changeme"):
*: <code>CREATE USER 'eprints'@'localhost' IDENTIFIED by 'changeme';<br/> GRANT ALL PRIVILEGES ON *.* TO 'eprints'@'localhost' WITH GRANT OPTION;</code>
* As root, from a command prompt add the <tt>eprints</tt> user:
*: <code>adduser eprints</code>

== Dependencies ==
The following RPMs need to be installed using the dnf command:
dnf install libxml2 libxslt httpd mod_perl perl-Apache-DBI perl-DBI perl-DBD-MySQL perl-IO-Socket-SSL \
perl-Time-HiRes perl-CGI perl-Digest-MD5 perl-Digest-SHA perl-Digest-SHA1 perl-JSON perl-XML-LibXML \
perl-XML-LibXSLT perl-XML-SAX perl-MIME-Lite perl-Text-Unidecode perl-JSON perl-Unicode-Collate \
perl-LWP-Protocol-https perl-IO-String tetex-latex wget gzip tar ImageMagick poppler-utils \
chkconfig unzip cpan python3-html2text expat-devel libxslt-devel

'''N.B.''' If you are running RHEL / CentOS / Rocky Linux 10, '''perl-Apache-DBI''' is no longer available and will need to be installed with CPAN and '''python3-html2text''' will not be available until RHEL / CentOS / Rocky Linux 10.1. You should exclude these when running the dnf command above. (See [[#RHEL_.2F_CentOS_.2F_Rocky_10|Operating System Version Specific Requirements for RHEL / CentOS / Rocky Linux 10]] below for more details).

== Installing EPrints 3.4.7 from Source ==
'''Ideally you will install from source from [https://github.com/eprints/eprints3.4 EPrints Core Git repository], which includes the core codebase and the publications flavour. However, you may choose to download tarballs of the EPrints core codebase and publications flavour from files.eprints.org as an alternative means of installation.

=== From GitHub ===
Clone the Git repository from GitHub to <tt>/opt/</tt> and set the <tt>eprints</tt> user as the owner. It is probably best to checkout the latest release rather than using HEAD, which may have known issues:

dnf install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.7

=== From files.eprints.org ===
Download and unpack the core codebase tarball for files.eprints.org.
cd /tmp/
wget https://files.eprints.org/3288/1/eprints-3.4.7.tar.gz
tar -xzvf eprints-3.4.7.tar.gz

Then move in the source code into place:
mv eprints-3.4.7 /opt/eprints3
chmod 2775 /opt/eprints3
chown -R eprints:eprints /opt/eprints3

If you want a publications flavoured repository, then you will also need to download, unpack and move that into the appropriate location:
wget https://files.eprints.org/3288/2/eprints-3.4.7-flavours.tar.gz
tar -xzvf eprints-3.4.7-flavours.tar.gz
mv eprints-3.4.7/flavours/pub_lib /opt/eprints3/flavours
chmod -R g+w /opt/eprints3/flavours/pub_lib
chown -R eprints:eprints /opt/eprints3/flavours/pub_lib

== Configuration ==
<span id="getting_started_and_apache">EPrints</span> is now fully installed at <tt>/opt/eprints3</tt>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

== Post-configuration ==
Add the <tt>eprints</tt> user to the <tt>apache</tt> group and vice-versa.
usermod -aG apache eprints
usermod -aG eprints apache

Finally, restart Apache:
service httpd restart

=== SELinux ===
There is a fair chance your operating system will have SELinux enabled. If so, follow the advice at [[EPrints and SELinux]] for how to let EPrints do what it needs to do through SELinux. Otherwise, you could disable SELinux with the following:
setenforce 0
However, that will only disable it until the next reboot. You should also edit '''/etc/selinux/config''' and make sure the <code>SELINUX=enforcing</code> is set to:
SELINUX=disabled

== Non-critical Dependencies ==
Some of EPrints non-core functionality may not work out of the box as these dependencies are not included as part of the installation process. Here is a list of known additional packages (and the DNF repositories in which they can be found) or CPAN modules than can be installed. The latter should be installed using the ''cpan'' command as the root user.

* '''perl-Geo-IP (epel)''' - Allows IRstats2 to determine the location of views/downloads for publications. (RHEL/CentOS/Rocky Linux 8 only)
* '''perl-GeoIP2 (@System and epel)''' - Allows IRstats2 to determine the location of views/downloads for publications. (RHEL/CentOS/Rocky Linux 9+)
* '''perl-Spreadsheet-WriteExcel (epel)''' - To allow Multiline Excel export.
* '''CPAN module Text::Refer''' - Required for EndNote import.
* '''CPAN module TeX::Encode''' - Required for BibTex export needed for publications flavour.
* '''perl-Image-ExifTool (epel)''' - Sometimes needed to support generation of thumbnails for uploaded documents/images.
* '''perl-LWP-Protocol-https (base)''' - Needed by DataCite plugin to register repository DOIs.

== Operating System Version Specific Requirements ==

=== RHEL / CentOS / Rocky 8 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 8}}

=== RHEL / CentOS / Rocky 9 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 9}}

=== RHEL / CentOS / Rocky 10 ===
{{:Issues with installing EPrints on RHEL / CentOS / Rocky 10}}

== Troubleshooting ==
* If setup is successful but then you cannot access EPrints through your web browser this is often due to firewalld being enabled by default on recent versions of RHEL, Fedora and CentOS. If firewalld is running either disable it (<tt>systemctl disable --now firewalld</tt>) or [https://docs.rackspace.com/support/how-to/allow-web-traffic-in-a-firewalld-software-firewall/ configure it to allow HTTP/HTTPS traffic].
* If you are running a version of EPrints below 3.4.6 you cannot run Apache in MPM event mode and you need to use MPM prefork instead. This is due to Perl's <tt>XML::LibXSLT</tt> being initiated at the wrong time leading earlier version of EPrints to cause Apache (httpd) to segfault when started. If you are running an earlier version and want to run Apache in MPM event mode, you can uninstall <tt>XML::LibXSLT</tt> either as the RPM perl-XML-LibXSLT or possible from CPAN using <code>cpanm --uninstall XML::LibXSLT</code>.
* If you are having problems uploading files or similar functional issues, this may be due to SELinux being enabled. [[EPrints and SELinux|See advice for enabling SELinux with EPrints]].
* If you are having trouble getting additional subdomains beyond username.eprints-hosting.org working, then it could be you need wildcards enabled on the DNS records to facilitate the likes of somethingcoolhere.username.eprints-hosting.org urls.

Template:Manual

2026-01-26T09:03:31Z

Drn@ecs.soton.ac.uk: Added links to installation of EPrints on different linux OS

{{box|title=Manual Sections|content=
* [[Introduction]]
** [[Contact|How to Get Help/Support]]
** [[History]]
* Installing EPrints & Getting Started
** [[Recommended Platforms]]
** [[Required software|Installing Required Software]]
** [[Installation|Installing EPrints]]
*** [[Installing EPrints on RHEL/Fedora/CentOS|Installation on RHEL-based Linux]]
*** [[Installing_EPrints_on_Debian/Ubuntu|Installation on Debian/Ubuntu]]
*** [[Generic Linux Installation|Installation on Generic Linux OS]]
** [[Upgrading|Upgrading EPrints]]
** [[Getting Started]]
** [[Backups]]
** [[Troubleshooting]]
** Advanced Installation
*** [[How to use EPrints with HTTPS]]
*** [[Setting up email]]
* Configuring EPrints
** [[Branding/Logos]]
** [[Metadata|Deposit Types and Metadata]]
** [[Organisation Hierarchy]]
** [[Searches]]
* Advanced Configuration/Howtos
** [[Setting up HTTPS using Let's Encrypt]]
** [[HTTPS-only and HSTS]]
** [[Shibboleth|User Authentication using Shibboleth]]
* Technical Reference
** [[EPrints configuration|EPrints Configuration Reference]]
** [[Repository configuration|Repository Configuration Reference]]
** [[Metadata|Metadata Reference]] (also [[Functions]])
** [[API Overview]]
* [[Entire Manual]] (for printing)
}}
[[Category:Manual]]

Template:Manual

2026-01-26T09:02:57Z

Drn@ecs.soton.ac.uk: Added links to installation of EPrints on different linux OS

{{box|title=Manual Sections|content=
* [[Introduction]]
** [[Contact|How to Get Help/Support]]
** [[History]]
* Installing EPrints & Getting Started
** [[Recommended Platforms]]
** [[Required software|Installing Required Software]]
** [[Installation|Installing EPrints]]
*** [[Installing EPrints on RHEL/Fedora/CentOS|Installation on Red Hat Enterprise based Linux]]
*** [[Installing_EPrints_on_Debian/Ubuntu|Installation on Debian/Ubuntu]]
*** [[Generic Linux Installation|Installation on Generic Linux Operating System]]
** [[Upgrading|Upgrading EPrints]]
** [[Getting Started]]
** [[Backups]]
** [[Troubleshooting]]
** Advanced Installation
*** [[How to use EPrints with HTTPS]]
*** [[Setting up email]]
* Configuring EPrints
** [[Branding/Logos]]
** [[Metadata|Deposit Types and Metadata]]
** [[Organisation Hierarchy]]
** [[Searches]]
* Advanced Configuration/Howtos
** [[Setting up HTTPS using Let's Encrypt]]
** [[HTTPS-only and HSTS]]
** [[Shibboleth|User Authentication using Shibboleth]]
* Technical Reference
** [[EPrints configuration|EPrints Configuration Reference]]
** [[Repository configuration|Repository Configuration Reference]]
** [[Metadata|Metadata Reference]] (also [[Functions]])
** [[API Overview]]
* [[Entire Manual]] (for printing)
}}
[[Category:Manual]]

Installation

2026-01-26T09:00:35Z

Drn@ecs.soton.ac.uk: Added generic linux link

Installation

2026-01-26T08:59:18Z

Drn@ecs.soton.ac.uk: Added links to different flavours of Linux

Generic Linux Installation

2026-01-26T08:54:46Z

Drn@ecs.soton.ac.uk: Drn@ecs.soton.ac.uk moved page Installation to Generic Linux Installation without leaving a redirect: Reorganise to point people towards supported Linux OS

{{manual}}
[[Category:Installation]]
'''Below describes installing EPrints on a generic Linux distribution. It is recommended that EPrints is installed on either [[Installing EPrints on RHEL/Fedora/CentOS|Red Hat based]] or [[Installing EPrints on Debian/Ubuntu|Debian based]] Linux.'''

==Download==
EPrints can be downloaded from https://files.eprints.org/

==Installation==
''If you are upgrading an existing installation of eprints please see the section on [[Upgrading]] section of this manual.''

EPrints needs to be installed as the same user as the apache webserver runs as. We suggest you install it as user "eprints" and group "eprints". Under some UNIX platforms, creating a user and group can be done using the "adduser" command. Otherwise refer to your operating system documentation.

Unpack the eprints tar.gz file:

% gunzip eprints-3.something.tar.gz
% tar xf eprints-3.something.tar

Now run the "configure" script. This is a /bin/sh script which will attempt to locate various parts of your system such as the perl binary. It will also check your system for required components.

% cd eprints-3.something
% ./configure

By default the system installs as user and group "eprints". You will need to change this if you are not installing as either "root" or "eprints".

The configure script accepts a number of options.

; --help : List all the options (many are intended for compiled software and are ignored).

Recommended:

; --prefix=PREFIX : Where to install EPrints (or look for a version to upgrade). By default <tt>/opt/eprints3/</tt>
; --with-smtp-server=[HOST] : Use HOST to deliver mail. If the server running EPrints has an MTA such as <tt>exim</tt> or <tt>sendmail</tt>, you can specify '''localhost'''. If you do not specify this option, you will get a warning to configure it later.
; --with-user=[USER] : Install eprints to run as USER. By default "eprints".
; --with-group=[GROUP] : Install eprints to run as GROUP. By default "eprints".

Optional:

; --with-perl=[PATH] : Path of perl interpreter (in case configure can't find it, or you have more than one and want to use a specific one).
; --with-virtualhost=[VIRTUALHOST] : Use VIRTUALHOST rather than * for apache VirtualHost directives.
; --with-toolpath=[PATH] : An alternate path to search for the required binaries.
; --disable-diskfree : Disable disk free space calls. These can cause problems on some platforms, notably 64-bit.

Deprecated:

; --with-apache=1 : Use Apache 1.x.x instead of 2.x.x, but EPrints 3 does not support this.

Once you are happy with your configuration you may install eprints by running install.pl:

% ./install.pl

Now you should edit the configuration file for your copy of apache. This is often <tt>/usr/local/apache/conf/http.conf</tt> or <tt>/etc/httpd/conf/httpd.conf</tt>

Add this line: (If you didn't install eprints in <tt>/opt/eprints3/</tt> replace that with the location on your system).
Include /opt/eprints3/cfg/apache.conf
Note that this file is only available after you created your archive via <tt>epadmin create</tt>. See [[Getting_Started_with_EPrints_3#Running_epadmin|Running epadmin]] for more information on creating an archive.

You need to make sure the apache user have read/write access to the installation directory (/opt/eprints3). The user ''must'' be the same as the user you installed eprints as. We recommend to configure your apache to run as:

User eprints
Group eprints

Recommended Platforms

2026-01-26T08:53:02Z

Drn@ecs.soton.ac.uk: Updated recommended OS versions

{{manual}}
[[Category:Installation]]
[[Category: Out of Date]]

* '''Red Hat based Linux''' - [[Installing EPrints on RHEL/Fedora/CentOS|Installation Guide]]
** Red Hat Enterprise Linux (RHEL) (http://www.redhat.com/rhel/): Red Hat Enterprise Linux (RHEL) 9 is currently recommended. However, RHEL 10 should now be suitable as long as you are running at least version 10.1.
** Fedora Core (http://fedora.redhat.com/): Fedora 42 or later currently recommended. However, Fedora version move on quickly, so go out of support quickly and are not regularly tested and therefore Fedora is not recommended for production EPrints repositories.
** Rocky Linux (https://www.rockylinux.org/): Rocky Linux 9 is currently recommended. However, Rocky Linux 10 should now be suitable as long as you are running at least version 10.1.
** Alma Linux, Oracle Linux and other derived versions of RHEL should also be suitable. Version 9 of these Linuxes are currently recommended but version 10 should be suitable as long as you are running at least version 10.1.

* '''Debian based Linux''' - [[Installing EPrints on Debian/Ubuntu|Installation Guide]]
** Debian (https://www.debian.org/) - 11 (Bullseye), 12 (Bookworm) or 13 (Trixie) are currently recommended.
** Ubuntu (https://www.ubuntu.com/) - Ubuntu 22.04 LTS or 24.04 LTS are currently recommended. Non-LTS Ubuntu versions are not recommended.

Cgi/

2026-01-09T17:03:55Z

Drn@ecs.soton.ac.uk:

{{dirs}}

These scripts handle the dynamic parts of the website.

*'''[[EPrints_Directory_Structure/eprints3|eprints3]]/cgi'''
** '''[[cgi/ajax/|ajax/]] -
** '''cal''' - Provides a calendar layout that could be used for selecting dates or time spans.
** '''confirm''' - Provide a shim to /cgi/register to allow changes to a user's password or email address to be confirmed through an email link.
** '''counter''' - Provides some simple machine-readable stats on the repository.
** '''dataset_dictionary''' - Provides a dictionary of all fields associated woth a dataset, including their name, type, label and help text.
** '''embed_player''' - Embeds an HTML5 video element to preview video files.
** '''export''' - Export a data object, multiple data objects or the repository in a particular format.
** '''exportview''' - Exports a list of publications from a browse view listing in a particular format.
** '''google_site''' - Searches the repository host with given search terms using Google.
** '''handle_404''' - Ensure a properly branded 404 Not Found page is displayed when an EPrint is missing.
** '''history_search''' - Allows search for all records where a particular field has been changed in certain time frame.
** '''latest''' - Display the latest EPrints deposited to the repository's live archive.
** '''latest_tool''' - More customisable tool for displaying latest EPrints deposited to the repository's live archive.
** '''logout''' - Logs a user out and redirects to logged out page
** '''oai2''' - The OAI interface.
** '''oai_accesslogs''' -
** '''opensearch''' -
** '''opensearchdescription''' -
** '''openurl''' -
** '''process_request''' -
** '''register''' -
** '''request_doc''' -
** '''reset_password''' -
** '''saved_search''' -
** '''schema''' -
** '''search''' -
** '''set_lang''' -
** '''[[cgi/toolbox/|toolbox/]]''' -
** '''[[cgi/users/|users/]]''' - Contains scripts which require a valid login.

Accessibility Timeline and Roadmap

2026-01-05T15:08:04Z

Drn@ecs.soton.ac.uk: Added page about Accessibility timeline/roadmap

This page describes the timeline of Accessibility developments for EPrints and the further plans for improving Accessibility into the future.

== EPrints 3.4.2 released (July 2020) ==
Ensures all pages accessible without login are accessibility compliant, except where this would directly affect them from fulfilling their function as an Open Access archive, (e.g. links to PDF documents). This includes:
# Fully static pages. Such as the Home, About, About EPrints, Repository Policies, Accessibility, etc. pages.
# Standard form-based pages. Such as Simple Search, Advanced Search, Create Account pages.
# Pages generated from user-generated content. Such as browse views, abstract pages, result pages from searches, etc. Assuming typical user-generated content.

== EPrints 3.4.3 released (April 2021) ==
Ensures all commonly used pages accessible to only logged in users are accessibility compliant, when using typical user-generated content. This includes:
# Manage deposits page
# View and edit pages for deposits
# Review pages for deposits
# Manage records page and its subsidiary "Manage [dataset]" pages
# Admin Menu
# Create, view and edit pages for users
# View and edit pages for saved searches
# Admin search pages for items, issues, users and history
# Repository status page
# Create user page
# EPrints Bazaar
# Send test email page
# Database schema page
# Storage manager page
# Phrase editor and editing phrases pages
# Edit subject pages
# Manage metadata fields pages

== EPrints 3.4.4 released (August 2022) ==
Incremental modifications to further improve accessibility changes made in 3.4.2 and 3.4.3 and fixes any snags associated with these changes. In particular, improving the functionality to allow the number of names displayed in a citation to be limited but expanded on request.

== EPrints 3.4.5 released (May 2023) ==
Further incremental changes and snag fixes. In particular, the use of fieldsets and legends in search and input forms to make them easier to style with CSS.

== EPrints 3.4.6 released (August 2024) ==
Further incremental changes and snag fixes. Including increased usage or appropriate ARIA attributes for elements.

== EPrints 3.4.7 released (August 2025) ==
Further incremental changes and snag fixes.
# Removing dangling ARIA describedby attributes for fields with no help text.
# Ensuring unique element IDs for common actions in different tabs.
# Adding /cgi/register to the Accessibility report.

== EPrints 3.5 (Coming soon) ==
Improving the accessibility of PDF documents uploaded to EPrints repositories. In particular, tools to insert metadata and accessibility features into uploaded files.

EPrints 3.4.8

2025-12-29T19:43:19Z

Drn@ecs.soton.ac.uk: /* Release Notes (Provisional) */ All changes up to 29th December 2025

This page contains information about the provisional EPrints v3.4.8 tag and release on GitHub. A date for this release is yet to be scheduled.

== Release Notes (Provisional) ==
EPrints 3.4.8 is planned to be released in the Summer of 2026.
* '''Zero codename:''' ''TO BE DETERMINED''
* '''Publications flavour codename:''' ''TO BE DETERMINED''

=== New Dependencies ===
Check earlier dependencies for [[EPrints 3.4.7]] and before.

If you wish to set a timezone of the dates and times displayed on your repository, you will need to make sure the <code>DateTime</code> Perl module is installed. For RHEL-based Linux this can be installed with the <code>perl-DateTime</code> RPM. For Debian-based Linux this requires <code>libdatetime-perl</code>.

=== Changes Since 3.4.7 ===

==== New Functionality ====
* [https://github.com/eprints/eprints3.4/commit/be86f99b3662083a4f35034f14776d86bcc9e087 Adds <code>export_file_as_attachment</code> option to force exports to be downloaded]
* [https://github.com/eprints/eprints3.4/pull/513 Adds an export plugin for document URLs]
* [https://github.com/eprints/eprints3.4/pull/512 Adds clear buttons to multiple <code>Compound</code> fields]
* [https://github.com/eprints/eprints3.4/pull/525 Adds support for rendering time with a given timezone]

==== Security and Privacy Improvements ====
* [https://github.com/eprints/eprints3.4/pull/511 Prevents 'javascript:' URLs from being saved in URL fields]
* [https://github.com/eprints/eprints3.4/commit/c5884562ed72b31681d3f0308b5987b2564052ad Modifies fix for SetLang referrer misuse]

==== General Improvements ====
* Updates metatags functionality to equivalent to [https://github.com/eprints/metatags/releases/tag/v1.4 v1.4] plus further improvements to ensure its export plugins are compliant with unit tests
* [https://github.com/eprints/eprints3.4/pull/515 Removes the progress bar even if the upload fails]
* [https://github.com/eprints/eprints3.4/commit/5fe2b24938ed19c38b0ffa6a5bc5d67253cfb514 Remove no longer required <code>progressid</code> from file uploads]
* [https://github.com/eprints/eprints3.4/pull/519 Adds support for number format months to BibTex import]
* [https://github.com/eprints/eprints3.4/pull/518 Makes the default encoding of imports 'UTF-8']
* [https://github.com/eprints/eprints3.4/pull/520 Adds labels connecting to radio buttons for <code>Boolean</code> and <code>Set</code>]
* [https://github.com/eprints/eprints3.4/commit/21687bd917244717674e613ce0d0e372fffcf619 Improves <code>Longtext_counter</code> <code>MetaField</code>]
* [https://github.com/eprints/eprints3.4/issues/530 Removes MPM event warning message]
* [https://github.com/eprints/eprints3.4/issues/527 Improves CRUD API fault tolerance]
* [https://github.com/eprints/eprints3.4/issues/536 Better specifies MetaField property defaults]

==== Bug Fixes ====
* [https://github.com/eprints/eprints3.4/pull/503 Fixes sample <code>EP_TRIGGER_BEGIN</code> and <code>EP_TRIGGER_END</code> subroutines]
* [https://github.com/eprints/eprints3.4/pull/521 Checks that <code>$id->{id_type}</code> is set before comparing it]
* [https://github.com/eprints/eprints3.4/issues/531 Fixes issues with <code>Convert::PlainText</code> handling large DOCX]
* [https://github.com/eprints/eprints3.4/commit/d1777a5a3170afed02f727b989cb8ebc009c3549 Makes unsupported packaging format a bad request (400) not server error (500)]
* [https://github.com/eprints/eprints3.4/pull/534 Don't add export link elements to deleted item page head]
* [https://github.com/eprints/eprints3.4/issues/535 Specifies more appropriate <code>empty_value</code>s for <code>Int</code> and <code>Float</code> MetaFields]
* [https://github.com/eprints/eprints3.4/issues/508 Fixes <code>eval</code> blocks calling user-defined <code>toform</code> or <code>fromform</code> functions to work as effective try/catch blocks.

== Planned Features and Improvements ==
See [https://github.com/eprints/eprints3.4/milestone/9 3.4.8 milestone on GitHub] for more details.

[[Category:Eprints3.4]]
[[Category:Planned Releases]]

EPrints 3.4.8

2025-12-29T18:52:10Z

Drn@ecs.soton.ac.uk: /* Bug Fixes */ Added changes up to 2nd September 2025

Issues with installing EPrints on RHEL / CentOS / Rocky 10

2025-11-26T23:48:24Z

Drn@ecs.soton.ac.uk: 10.1 is now out so python3-html2text should now be installable with dnf

No other known issues beyond those below if running at least EPrints 3.4.6.

==== mod_perl cannot handle dir_perms parameter ====
By default EPrints is configures its <tt>dir_perms</tt> parameter to <code>02775</code> in <tt>perl_lib/EPrints/SystemSettings.pm</tt> and <tt>lib/syscfg.d/core.pl</tt>. This is used when creating a new directory with <tt>EPrints::System::mkdir</tt>, which call <tt>CORE::mkdir</tt>. Previously this core Perl function has ignored the mask for the setuid/setgid/sticky bit so it did not matter^ if <tt>dir_perms</tt> was <code>02775</code> or <code>0775</code> but the version of mod_perl used on RHEL-based Linux 10 now gets confused by this and will fail to create directory. To fix this you will need to modify <tt>lib/syscfg.d/core.pl</tt> and set <code>$c->{dir_perms}</code> as follows:
$c->{dir_perms} = '0775';
In addition, to make sure that the setgid bit gets set the same as it would before, it is advised you make sure all the sub-directories in your archive have the setgid bit set:
find EPRINTS_PATH/archives/ARCHIVE_ID -type d -exec chmod g+s {} \;
Technically, it should not be necessary to do this to all directories, it might be sufficient to do this only to the html and documents directories, as well as their sub-directories but there should not be any problem updating all the archive's directories.

^This is why <tt>EPrints::System::mkdir</tt> would subsequently called <tt>CORE::chmod</tt> to update setuid/setgid/sticky bits on the newly created directories.

==== perl-Apache-DBI not available through DNF package manager ====
RHEL / CentOS / Rocky 10 does not include perl-Apache-DBI in their DNF package managers. Therefore, you will need to install afterwards using cpan:
cpan Apache::DBI

Category:Installation

2025-11-26T23:46:57Z

Drn@ecs.soton.ac.uk: /* Distribution Notes */

The default installation of EPrints is on a stand-alone linux system, but this is not the only way EPrints can (and has) been installed.

'''The EPrints team currently recommends installing EPrints in one of the following ways:'''

* '''[[Installing EPrints on Debian/Ubuntu]]'''
* '''[[Installing EPrints on_RHEL/Fedora/CentOS]]'''
* '''[[Installation|Installing from source]]'''

Here are some other ways:

* [[non-root_proxy|Proxied to a non-root user account]]: Where the server and all associated code is installed without root/admin access to anything
* [[How to set up EPrints on virtual directories other than root|Hosted on virtual directories other than root]] - sharing with other Web applications on the same server

This category contains a range of other sets of instructions for different operating systems and versions of EPrints. Most of them are not supported but may still work. {{EPrintsTech}}

If you want to write installation instructions for a system other than those listed here please do so. Remember to tag the page with <nowiki>[[Category:Installation]]</nowiki> so that it appears in this list.

'''If you use one of the installation guides below and it doesn't work, edit the page to say what went wrong and how you fixed it. This will help others (and maybe yourself) tackle these problems in the future. [[Template:Register|Here you can register for an eprints.org account]] to edit the wiki.'''

== Distribution Notes ==

Known issues and gotchas on various Linux distributions

{| class="wikitable"
|-
! Distibution
! Support
! Notes
|-
| RHEL / Centos / Rocky 8
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 8]].
|-
| RHEL / Centos / Rocky 9
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 9]]. EPrints Services test builds against this release.
|-
| RHEL / Centos / Rocky 10
| Supported
| Some minor issues. See [[Issues with installing EPrints on RHEL / CentOS / Rocky 10]].
|-
| Ubuntu 22.04 LTS
| Supported
| Some minor issues. See [[Issues with Installing EPrints on Ubuntu 22.04]].
|-
| Ubuntu 24.04 LTS
| Supported
| Some minor issues. See [[Issues with Installing EPrints on Ubuntu 24.04]].
|-
|}

Shibboleth Debug Logging

2025-11-17T13:27:02Z

Drn@ecs.soton.ac.uk: /* Decoding a CipherValue */

As described on the main [[Shibboleth]] page. EPrints uses the Shibboleth Service Provider (SP) provided by shibboleth.net. This includes a logger that can be configured at '''/etc/shibboleth/shibd.logger''' and which logs to '''/var/log/shibboleth/shibd.log'''. This typically only logs errors and warnings and the occasionally informationl log message, typically when starting or stopping. However, if you are having problems with the Shibboleth SP, particularly when setting up, it may be useful to enable debug. To do this

1. Edit the '''/etc/shibboleth/shibd.logger''' and uncomment the following lines:
# tracing of SAML messages and security policies
#log4j.category.OpenSAML.MessageDecoder=DEBUG
#log4j.category.OpenSAML.MessageEncoder=DEBUG
#log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
#log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
#log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
#log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
#log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
#log4j.category.XMLTooling.StorageService=DEBUG
So they look like
# tracing of SAML messages and security policies
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
log4j.category.XMLTooling.StorageService=DEBUG

2. Test the Shibboleth SP is correctly configured
shibd -t

3. Restart the Shibboleth SP
systemctl restart shibd

There is various debugging that has been enabled by these changes. Particularly useful are the first two line:
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
This will allow you to see the XML messages sent to and from the Shibboleth Identity Provider (IdP), such as MicroSoft Entra or OpenAthens.

== Debugging User Attributes Mapping Issues ==
This debugging can be particularly useful if you are trying to work attributes in your attribute-map.xml are not being mapped as expected. If you tail the log file '''/var/log/shibboleth/shibd.log''' and then try to login using the Shibboleth, you should see a line in the logs that starts:
<samlp:Response ...
If you copy the whole of that line into a text file in /tmp/ and save it. Then you can run xmllint on it to format the output. E.g.
xmllint --format /tmp/saml-response.xml
If attributes are being mapped, in the formatted output you should be able to see section that starts with an '''AttributeStatment''' XML tag (However, if you don't see this, then your data may be encrypted as a '''CipherValue''' under '''CipherData'''. if so, follow the instructions under [[#Decoding a CipherValue|Decoding a CipherValue]] . E.g.
<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
<AttributeValue>01234567-89ab-cdef-0123-456789abcdef</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
<AttributeValue>fedcba98-7654-3210-fedc-ba9876543210</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
<AttributeValue>https://sts.windows.net/89abcdef-0123-4567-89ab-cdef01234567/</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
<AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
<AttributeValue>http://schemas.microsoft.com/claims/multipleauthn</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">
<AttributeValue>j.bloggs@example.org</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.4">
<AttributeValue>Bloggs</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.42">
<AttributeValue>Joe</AttributeValue>
</Attribute>
</AttributeStatement>
If you cannot find users attributes you are expecting to see based on what you have configurured in your Shibboleth SP's attribute-map.xml, then you will need to get the maintainer of Shibboleth IdP to make sure these attributes are released or otherwise release attributes that store the sane user metadata. At this point you can re-run this debugging to see what user attributes you are now getting and update your Shibboleth SP's attribute-map.xml as appropriate.

'''When you have finished debugging. It is sensible to comment out the debug lines in '''/etc/shibboleth/shibd.logger''' again and restart the Shibboleth SP.'''

== Decoding a CipherValue ==
1. Download [https://gist.github.com/orimanabu/b2a7afcc6b6f59e475cad918914eb4b9|this Python script]:
cd /tmp/
wget https://gist.githubusercontent.com/orimanabu/b2a7afcc6b6f59e475cad918914eb4b9/raw/99e4f6e9c71fc5d2a9f4021d3336f28dab0927a7/decrypt_saml_response.py

2. Create a Python virtual environment, activate it and make sure pip is upgraded:
python -m venv venv
source venv/bin/activate
pip install --upgrade pip

3. Install Python modules required by the script
pip install lxml
pip install PyCryptodome

4. Now you can run the script. (It is assumed that your key is in the default location for the Shibboleth SP. Check this is correct according to the CredentialResolver tag in /etc/shibboleth/shibboleth2.xml. If you have a separate encryption and signing key, be sure to use the encryption one in the command below).
cat /tmp/saml-response.xml | python decrypt_saml_response.py -k /etc/shibboleth/sp-key.pem -p

Shibboleth Debug Logging

2025-11-17T13:26:05Z

Drn@ecs.soton.ac.uk: Added instructions for how to decode SAML message

As described on the main [[Shibboleth]] page. EPrints uses the Shibboleth Service Provider (SP) provided by shibboleth.net. This includes a logger that can be configured at '''/etc/shibboleth/shibd.logger''' and which logs to '''/var/log/shibboleth/shibd.log'''. This typically only logs errors and warnings and the occasionally informationl log message, typically when starting or stopping. However, if you are having problems with the Shibboleth SP, particularly when setting up, it may be useful to enable debug. To do this

1. Edit the '''/etc/shibboleth/shibd.logger''' and uncomment the following lines:
# tracing of SAML messages and security policies
#log4j.category.OpenSAML.MessageDecoder=DEBUG
#log4j.category.OpenSAML.MessageEncoder=DEBUG
#log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
#log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
#log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
#log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
#log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
#log4j.category.XMLTooling.StorageService=DEBUG
So they look like
# tracing of SAML messages and security policies
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
log4j.category.XMLTooling.StorageService=DEBUG

2. Test the Shibboleth SP is correctly configured
shibd -t

3. Restart the Shibboleth SP
systemctl restart shibd

There is various debugging that has been enabled by these changes. Particularly useful are the first two line:
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
This will allow you to see the XML messages sent to and from the Shibboleth Identity Provider (IdP), such as MicroSoft Entra or OpenAthens.

== Debugging User Attributes Mapping Issues ==
This debugging can be particularly useful if you are trying to work attributes in your attribute-map.xml are not being mapped as expected. If you tail the log file '''/var/log/shibboleth/shibd.log''' and then try to login using the Shibboleth, you should see a line in the logs that starts:
<samlp:Response ...
If you copy the whole of that line into a text file in /tmp/ and save it. Then you can run xmllint on it to format the output. E.g.
xmllint --format /tmp/saml-response.xml
If attributes are being mapped, in the formatted output you should be able to see section that starts with an '''AttributeStatment''' XML tag (However, if you don't see this, then your data may be encrypted as a '''CipherValue''' under '''CipherData'''. if so, follow the instructions under [[#Decoding a CipherValue|Decoding a CipherValue]] . E.g.
<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
<AttributeValue>01234567-89ab-cdef-0123-456789abcdef</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
<AttributeValue>fedcba98-7654-3210-fedc-ba9876543210</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
<AttributeValue>https://sts.windows.net/89abcdef-0123-4567-89ab-cdef01234567/</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
<AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
<AttributeValue>http://schemas.microsoft.com/claims/multipleauthn</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">
<AttributeValue>j.bloggs@example.org</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.4">
<AttributeValue>Bloggs</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.42">
<AttributeValue>Joe</AttributeValue>
</Attribute>
</AttributeStatement>
If you cannot find users attributes you are expecting to see based on what you have configurured in your Shibboleth SP's attribute-map.xml, then you will need to get the maintainer of Shibboleth IdP to make sure these attributes are released or otherwise release attributes that store the sane user metadata. At this point you can re-run this debugging to see what user attributes you are now getting and update your Shibboleth SP's attribute-map.xml as appropriate.

'''When you have finished debugging. It is sensible to comment out the debug lines in '''/etc/shibboleth/shibd.logger''' again and restart the Shibboleth SP.'''

== Decoding a CipherValue ==
1. Download [https://gist.github.com/orimanabu/b2a7afcc6b6f59e475cad918914eb4b9|this Python script]:
cd /tmp/
wget https://gist.githubusercontent.com/orimanabu/b2a7afcc6b6f59e475cad918914eb4b9/raw/99e4f6e9c71fc5d2a9f4021d3336f28dab0927a7/decrypt_saml_response.py

2. Create a Python virtual environment, activate it and make sure pip is upgraded:
python -m venv venv
source venv/bin/activate
pip install --upgrade pip

3. Install Python modules required by the script
pip install lxml
pip install PyCryptodome

4. Now you can run the script. (It is assumed that your key is in the default location for the Shibboleth SP. Check this is correct according to the CredentialResolver tag in /etc/shibboleth/shibboleth2.xml).
cat /tmp/saml-response.xml | python decrypt_saml_response.py -k /etc/shibboleth/sp-key.pem -p

Shibboleth Debug Logging

2025-11-17T11:10:24Z

Drn@ecs.soton.ac.uk: /* Debugging User Attributes Mapping Issues */

As described on the main [[Shibboleth] page. EPrints uses the Shibboleth Service Provider (SP) provided by shibboleth.net. This includes a logger that can be configured at '''/etc/shibboleth/shibd.logger''' and which logs to '''/var/log/shibboleth/shibd.log'''. This typically only logs errors and warnings and the occasionally informationl log message, typically when starting or stopping. However, if you are having problems with the Shibboleth SP, particularly when setting up, it may be useful to enable debug. To do this

1. Edit the '''/etc/shibboleth/shibd.logger''' and uncomment the following lines:
# tracing of SAML messages and security policies
#log4j.category.OpenSAML.MessageDecoder=DEBUG
#log4j.category.OpenSAML.MessageEncoder=DEBUG
#log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
#log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
#log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
#log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
#log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
#log4j.category.XMLTooling.StorageService=DEBUG
So they look like
# tracing of SAML messages and security policies
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
log4j.category.XMLTooling.SOAPClient=DEBUG
# interprocess message remoting
log4j.category.Shibboleth.Listener=DEBUG
# mapping of requests to applicationId
log4j.category.Shibboleth.RequestMapper=DEBUG
# high level session cache operations
log4j.category.Shibboleth.SessionCache=DEBUG
# persistent storage and caching
log4j.category.XMLTooling.StorageService=DEBUG

2. Test the Shibboleth SP is correctly configured
shibd -t

3. Restart the Shibboleth SP
systemctl restart shibd

There is various debugging that has been enabled by these changes. Particularly useful are the first two line:
log4j.category.OpenSAML.MessageDecoder=DEBUG
log4j.category.OpenSAML.MessageEncoder=DEBUG
This will allow you to see the XML messages sent to and from the Shibboleth Identity Provider (IdP), such as MicroSoft Entra or OpenAthens.

== Debugging User Attributes Mapping Issues ==
This debugging can be particularly useful if you are trying to work attributes in your attribute-map.xml are not being mapped as expected. If you tail the log file '''/var/log/shibboleth/shibd.log''' and then try to login using the Shibboleth, you should see a line in the logs that starts:
<samlp:Response ...
If you copy the whole of that line into a text file in /tmp/ and save it. Then you can run xmllint on it to format the output. E.g.
xmllint --format /tmp/saml-response.xml
If attributes are being mapped, in the formatted output you should be able to see section that starts with an '''AttributeStatment''' XML tag. E.g.
<AttributeStatement>
<Attribute Name="http://schemas.microsoft.com/identity/claims/tenantid">
<AttributeValue>01234567-89ab-cdef-0123-456789abcdef</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/objectidentifier">
<AttributeValue>fedcba98-7654-3210-fedc-ba9876543210</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/identity/claims/identityprovider">
<AttributeValue>https://sts.windows.net/89abcdef-0123-4567-89ab-cdef01234567/</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.microsoft.com/claims/authnmethodsreferences">
<AttributeValue>http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password</AttributeValue>
<AttributeValue>http://schemas.microsoft.com/claims/multipleauthn</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:0.9.2342.19200300.100.1.3">
<AttributeValue>j.bloggs@example.org</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.4">
<AttributeValue>Bloggs</AttributeValue>
</Attribute>
<Attribute Name="urn:oid:2.5.4.42">
<AttributeValue>Joe</AttributeValue>
</Attribute>
</AttributeStatement>
If you cannot find users attributes you are expecting to see based on what you have configurured in your Shibboleth SP's attribute-map.xml, then you will need to get the maintainer of Shibboleth IdP to make sure these attributes are released or otherwise release attributes that store the sane user metadata. At this point you can re-run this debugging to see what user attributes you are now getting and update your Shibboleth SP's attribute-map.xml as appropriate.

'''When you have finished debugging. It is sensible to comment out the debug lines in '''/etc/shibboleth/shibd.logger''' again and restart the Shibboleth SP.'''

Shibboleth Debug Logging

2025-11-17T11:09:11Z

Drn@ecs.soton.ac.uk: Added some basic debug instructions, mainly for user attribute mapping

Shibboleth

2025-11-17T10:45:43Z

Drn@ecs.soton.ac.uk: /* With attribute-map.xml */

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will just be different package names and different commands to manage applications.

Generally, it is a good idea to run EPrints with '''HTTPS''' when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP). Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an '''ssl/securevhost.conf''' under the archive directory structure.

== Installing Shibboleth ==
* First, add the Shibboleth repository to your list of YUM repositories (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use Yum to install all package dependencies:
root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling

* You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
overall configuration is loadable, check console for non-fatal problems

* If there are no other warning or error messages from ''shibd -t'', you can start it properly and check to make sure it is running. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
root> systemctl start shibd.service
root> ps aux | grep shib
shibd 29338 0.4 0.7 419784 15024 ? Ssl 11:16 0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
root 29345 0.0 0.0 112640 940 pts/2 S+ 11:17 0:00 grep --color=auto -i shib
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>

<Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
<MetadataProvider type="XML" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>

</ApplicationDefaults>

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>

* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
root> mkdir /etc/shibboleth/foo

* Copy '''attribute-map.xml''' into this new directory.
cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/

* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-cert.pem.old
root> mv sp-key.pem sp-key.pem.old

* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.
root> cd /etc/shibboleth
root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth

* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' and move the ''.old'' files back in place:
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-key.pem foo/
root> mv sp-cert.pem.old sp-cert.pem
root> mv sp-key.pem.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''shibd'''.
root> ls -l /etc/shibboleth/foo/sp-*
-rw-r--r-- 1 shibd shibd 1192 May 6 19:04 /etc/shibboleth/foo/sp-cert.pem
-rw------- 1 shibd shibd 1708 May 6 19:04 /etc/shibboleth/foo/sp-key.pem

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t
This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== Configuring Apache and EPrints ==
'''N.B. All these actions should be carried out by the ''eprints'' user, except when prepended with ''root>'' which means the command should be run as the ''root'' user.'''
* Add the following configuration to your archive's '''ssl/securevhost.conf''', after the '''Include /opt/eprints3/cfg/apache_ssl/foo.conf''', substituting '''foo''' for your archive's name where appropriate. (This assumes you are running Apache 2.4 or greater). See [[#Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration |Troubleshooting]] for instructions on the configuration to use for Apache 2.2. or lower.

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Location "/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

* Copy the following code into your archive (e.g. /opt/eprints3/archives/foo/) as '''cgi/shibboleth'''.
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );

$session->send_http_header( "content_type" => "text/html" );

print "<html><head/><body><code>\n";

foreach my $key (sort keys(%ENV)) {
print "<p>$key = $ENV{$key}</p>";
}

print "</code></body></html>";
$session->terminate;
exit;

* Now restart Shibboleth and Apache:
root> systemctl restart shibd.service
root> apachectl restart

* In a web browser go the '''/cgi/shibboleth''' page for your repository, (e.g. ''https://foo.eprints.org/cgi/shibboleth''). You should be redirected to an error page for your your Shibboleth IdP (e.g. ''https://shib.foo.example.org/idp/profile/SAML2/Redirect/SSO?...'').

* If instead you are displayed with a list of key values or are forbidden to access the page, you have not configured Apache properly, if so, see [[#Apache_Configuration_Issues|Apache_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]]. If you see an error message like the one below, you have not set up Shibboleth properly, if so, see [[#Shibboleth_Configuration_Issues|Shibboleth_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].
opensaml::saml2md::MetadataException
The system encountered an error at Wed May 6 15:19:27 2015
To report this problem, please contact the site administrator at root@localhost.
Please include the following message in any email:
opensaml::saml2md::MetadataException at (http://foo.eprints.org/cgi/shibboleth)
Unable to locate metadata for identity provider (https://shib.foo.example.org/idp/shibboleth)

* Next, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''cfg/cfg.d/zz_shibboleth.pl'''. This is needed to redirect login and logout to use Shibboleth rather than local login.
$c->{get_login_url} = sub {
my( $session, $target ) = @_;

# preserve CGI params
$session->read_params;
$target = $session->get_url(
host => 1,
path => "auto",
query => 1,
);

my $url = URI->new( $session->config( "https_url" ) . "/shibboleth/login" );
$url->query_form( target => "$target" );
return "$url";
};

$c->{on_logout} = sub {
my( $session ) = @_;
my $query = $session->query;
return unless defined $query;

# remove _shibsession_ cookie
my( $shibname, $shibvalue );
for( $query->cookie() ) {
if( $_ =~ /^_shibsession/ ) {
$shibname = $_;
$shibvalue = $query->cookie( $shibname );
}
}

my $cookie = $query->cookie(
-name => $shibname,
-path => "/",
-value => "",
-host => $session->config("cookie_domain"),
-expires => "-1d",
);
EPrints::Apache::AnApache::header_out(
$session->{request},
"Set-Cookie" => $cookie
);
};

push @{$c->{rewrite_exceptions}}, "/shibboleth/";

* Create a folder at the top level of your archive (e.g. ''/opt/eprints3/archives/foo/'') called '''shibboleth''' and copy the main CSS file for Shibboleth into this folder:
eprints> mkdir /opt/eprints3/archives/foo/shibboleth/
eprints> cp /usr/share/shibboleth/main.css /opt/eprints3/archives/foo/shibboleth/

* Now, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''shibboleth/login'''. This is the most basic login script that should work with the minimal attributes any Shibboleth IdP returns and '''only logging in users with existing accounts'''. Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your requirements, such as creation user accounts on-the-fly.
use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ( $username, $email ) = ( undef, "" );
if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
$email = $ENV{eppn};
}
return unless EPrints::Utils::is_set( $username );
my $user = $session->user_by_username( $username );
if( defined $user && defined $email )
{
$user->set_value( "email", $email );
$user->commit;
}
return $user;
}

* Next, add the following markup to '''cfg/lang/en/static/account_required.xpage''' under your archive (e.g. ''/opt/eprints3/archives/foo/''). Substituting ''staff and students of the University of Foo'' to describe to which particular group of people logged in access is restricted.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
<xpage:title>Login Failed</xpage:title>
<xpage:body>
<p style='text-align: center;'>Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" /></p>
</xpage:body>
</xpage:page>

* Now, reload Apache.
root> apachectl reload

* In a web browser go to the '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login''). Like before with ''/cgi/shibboleth'' you should be taken to your Shibboleth IdP's site albeit displaying an error message.

* The Shibboleth IdP shows an error message because EPrints as a Shibboleth Service Provider is not yet registered with it. To do this you need to send the administrator of the Shibboleth IdP the metadata for your Service Provider. You will have generated this earlier when you ran <code>metagen.sh</code>. Copy off your EPrints server the file that this wrote (e.g. to <tt>/etc/shibboleth/foo/sp_metadata.xml</tt>) and send it to the Shibboleth IdP administrator. They should be able to upload this to register EPrints as a Service Provider application.

* Once registered, use a web browser to go to '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'') again. This time you should be prompted for a username and password on the Shibboleth IdP site. Once you have typed this in and clicked to login, you should be returned to EPrints on the '''/cgi/users/home''' page for your repository. If not, see [[#Login_Issues|Login Issues]] under [[#Troubleshooting|Troubleshooting]] below.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just '''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case. The Shibboleth Service Provider can be [[Shibboleth Debug Logging|run in debug mode]], which may help your figure out what attributes are being mapped..

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ($username, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== Further Information ==
* Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available [[Shibboleth authentication|here]].

* For general information about installing and configuring Shibboleth [http://shibboleth.internet2.edu/ click here].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

Shibboleth

2025-11-17T10:45:19Z

Drn@ecs.soton.ac.uk: /* Shibboleth Configuration Issues */

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will just be different package names and different commands to manage applications.

Generally, it is a good idea to run EPrints with '''HTTPS''' when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP). Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an '''ssl/securevhost.conf''' under the archive directory structure.

== Installing Shibboleth ==
* First, add the Shibboleth repository to your list of YUM repositories (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use Yum to install all package dependencies:
root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling

* You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
overall configuration is loadable, check console for non-fatal problems

* If there are no other warning or error messages from ''shibd -t'', you can start it properly and check to make sure it is running. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
root> systemctl start shibd.service
root> ps aux | grep shib
shibd 29338 0.4 0.7 419784 15024 ? Ssl 11:16 0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
root 29345 0.0 0.0 112640 940 pts/2 S+ 11:17 0:00 grep --color=auto -i shib
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>

<Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
<MetadataProvider type="XML" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>

</ApplicationDefaults>

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>

* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
root> mkdir /etc/shibboleth/foo

* Copy '''attribute-map.xml''' into this new directory.
cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/

* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-cert.pem.old
root> mv sp-key.pem sp-key.pem.old

* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.
root> cd /etc/shibboleth
root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth

* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' and move the ''.old'' files back in place:
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-key.pem foo/
root> mv sp-cert.pem.old sp-cert.pem
root> mv sp-key.pem.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''shibd'''.
root> ls -l /etc/shibboleth/foo/sp-*
-rw-r--r-- 1 shibd shibd 1192 May 6 19:04 /etc/shibboleth/foo/sp-cert.pem
-rw------- 1 shibd shibd 1708 May 6 19:04 /etc/shibboleth/foo/sp-key.pem

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t
This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== Configuring Apache and EPrints ==
'''N.B. All these actions should be carried out by the ''eprints'' user, except when prepended with ''root>'' which means the command should be run as the ''root'' user.'''
* Add the following configuration to your archive's '''ssl/securevhost.conf''', after the '''Include /opt/eprints3/cfg/apache_ssl/foo.conf''', substituting '''foo''' for your archive's name where appropriate. (This assumes you are running Apache 2.4 or greater). See [[#Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration |Troubleshooting]] for instructions on the configuration to use for Apache 2.2. or lower.

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Location "/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

* Copy the following code into your archive (e.g. /opt/eprints3/archives/foo/) as '''cgi/shibboleth'''.
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );

$session->send_http_header( "content_type" => "text/html" );

print "<html><head/><body><code>\n";

foreach my $key (sort keys(%ENV)) {
print "<p>$key = $ENV{$key}</p>";
}

print "</code></body></html>";
$session->terminate;
exit;

* Now restart Shibboleth and Apache:
root> systemctl restart shibd.service
root> apachectl restart

* In a web browser go the '''/cgi/shibboleth''' page for your repository, (e.g. ''https://foo.eprints.org/cgi/shibboleth''). You should be redirected to an error page for your your Shibboleth IdP (e.g. ''https://shib.foo.example.org/idp/profile/SAML2/Redirect/SSO?...'').

* If instead you are displayed with a list of key values or are forbidden to access the page, you have not configured Apache properly, if so, see [[#Apache_Configuration_Issues|Apache_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]]. If you see an error message like the one below, you have not set up Shibboleth properly, if so, see [[#Shibboleth_Configuration_Issues|Shibboleth_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].
opensaml::saml2md::MetadataException
The system encountered an error at Wed May 6 15:19:27 2015
To report this problem, please contact the site administrator at root@localhost.
Please include the following message in any email:
opensaml::saml2md::MetadataException at (http://foo.eprints.org/cgi/shibboleth)
Unable to locate metadata for identity provider (https://shib.foo.example.org/idp/shibboleth)

* Next, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''cfg/cfg.d/zz_shibboleth.pl'''. This is needed to redirect login and logout to use Shibboleth rather than local login.
$c->{get_login_url} = sub {
my( $session, $target ) = @_;

# preserve CGI params
$session->read_params;
$target = $session->get_url(
host => 1,
path => "auto",
query => 1,
);

my $url = URI->new( $session->config( "https_url" ) . "/shibboleth/login" );
$url->query_form( target => "$target" );
return "$url";
};

$c->{on_logout} = sub {
my( $session ) = @_;
my $query = $session->query;
return unless defined $query;

# remove _shibsession_ cookie
my( $shibname, $shibvalue );
for( $query->cookie() ) {
if( $_ =~ /^_shibsession/ ) {
$shibname = $_;
$shibvalue = $query->cookie( $shibname );
}
}

my $cookie = $query->cookie(
-name => $shibname,
-path => "/",
-value => "",
-host => $session->config("cookie_domain"),
-expires => "-1d",
);
EPrints::Apache::AnApache::header_out(
$session->{request},
"Set-Cookie" => $cookie
);
};

push @{$c->{rewrite_exceptions}}, "/shibboleth/";

* Create a folder at the top level of your archive (e.g. ''/opt/eprints3/archives/foo/'') called '''shibboleth''' and copy the main CSS file for Shibboleth into this folder:
eprints> mkdir /opt/eprints3/archives/foo/shibboleth/
eprints> cp /usr/share/shibboleth/main.css /opt/eprints3/archives/foo/shibboleth/

* Now, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''shibboleth/login'''. This is the most basic login script that should work with the minimal attributes any Shibboleth IdP returns and '''only logging in users with existing accounts'''. Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your requirements, such as creation user accounts on-the-fly.
use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ( $username, $email ) = ( undef, "" );
if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
$email = $ENV{eppn};
}
return unless EPrints::Utils::is_set( $username );
my $user = $session->user_by_username( $username );
if( defined $user && defined $email )
{
$user->set_value( "email", $email );
$user->commit;
}
return $user;
}

* Next, add the following markup to '''cfg/lang/en/static/account_required.xpage''' under your archive (e.g. ''/opt/eprints3/archives/foo/''). Substituting ''staff and students of the University of Foo'' to describe to which particular group of people logged in access is restricted.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
<xpage:title>Login Failed</xpage:title>
<xpage:body>
<p style='text-align: center;'>Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" /></p>
</xpage:body>
</xpage:page>

* Now, reload Apache.
root> apachectl reload

* In a web browser go to the '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login''). Like before with ''/cgi/shibboleth'' you should be taken to your Shibboleth IdP's site albeit displaying an error message.

* The Shibboleth IdP shows an error message because EPrints as a Shibboleth Service Provider is not yet registered with it. To do this you need to send the administrator of the Shibboleth IdP the metadata for your Service Provider. You will have generated this earlier when you ran <code>metagen.sh</code>. Copy off your EPrints server the file that this wrote (e.g. to <tt>/etc/shibboleth/foo/sp_metadata.xml</tt>) and send it to the Shibboleth IdP administrator. They should be able to upload this to register EPrints as a Service Provider application.

* Once registered, use a web browser to go to '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'') again. This time you should be prompted for a username and password on the Shibboleth IdP site. Once you have typed this in and clicked to login, you should be returned to EPrints on the '''/cgi/users/home''' page for your repository. If not, see [[#Login_Issues|Login Issues]] under [[#Troubleshooting|Troubleshooting]] below.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just '''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case. The Shibboleth Service Provider can be [[run in debug mode|Shibboleth Debug Logging]], which may help your figure out what attributes are being mapped..

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ($username, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== Further Information ==
* Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available [[Shibboleth authentication|here]].

* For general information about installing and configuring Shibboleth [http://shibboleth.internet2.edu/ click here].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]