Difference between revisions of "EPrints 3.4.3"

From EPrints Documentation
Jump to: navigation, search
m (General Improvements)
(Update description of changes (to extensive tidying rather that wholesale overhaul of url/path settings))
Line 104: Line 104:
 
* Fixes BibTeX import using uploaded files broken by update to third-party <code>BibTeX::Parser</code> in EPrints 3.4.2.
 
* Fixes BibTeX import using uploaded files broken by update to third-party <code>BibTeX::Parser</code> in EPrints 3.4.2.
  
=== Default Configuration Changes: URLs and Paths ===
+
=== Configuration URLs and Paths ===
EPrints has various configuration settings for URLs and paths that are automatically configured based on the settings in an archive's <code>cfg/cfg.d/10_core.pl</code>. Over time there has been a move from EPrints repositories being HTTP-only to HTTP and HTTPS and further towards HTTPS only (with HTTP redirects)Therefore, EPrints configuration has had to evolve over time to support all these use cases, so those running EPrints can (continue to) run the HTTP/HTTPS setup that works for them. (Although, the recommendation would be to use the most secure configuration available).
+
EPrints has various configuration settings for URLs and paths that are automatically configured based on the settings in an archive's <code>cfg/cfg.d/10_core.pl</code>.  The six most significant are the following:
  
Normally, the easiest solution to this problem would be to avoid using full URLs that include the hostname and use the path (e.g. rather than ''http://example.eprints.org/view/year'', just use ''/view/year''). However, EPrints needing to extensively support exports and embedding means that often having the hostname in the URL link is essential.
 
 
==== Current Configuration Settings ====
 
Prior to EPrints 3.4.3, there have been five main configuration settings for the primary part of the URL:
 
 
; <code>http_url</code>
 
; <code>http_url</code>
 
: The HTTP version of the URL (e.g. ''http://example.eprints.org'').  Since EPrints 3.4.1, this will be set to the same as <code>https_url</code> if <code>$c->{host}</code> is undefined in the archive's <code>cfg/cfg.d/10_core.pl</code>.
 
: The HTTP version of the URL (e.g. ''http://example.eprints.org'').  Since EPrints 3.4.1, this will be set to the same as <code>https_url</code> if <code>$c->{host}</code> is undefined in the archive's <code>cfg/cfg.d/10_core.pl</code>.
 
; <code>https_url</code>  
 
; <code>https_url</code>  
 
: The HTTPS version of the URL (e.g. ''https://example.eprints.org''). If <code>$c->{securehost}</code> is not defined in the archive's <code>cfg/cfg.d/</code> directory (typically in <code>10_core.pl</code> or <code>https.pl</code>) then the URL will be set to HTTP (e.g. ''http://example.eprints.org'')
 
: The HTTPS version of the URL (e.g. ''https://example.eprints.org''). If <code>$c->{securehost}</code> is not defined in the archive's <code>cfg/cfg.d/</code> directory (typically in <code>10_core.pl</code> or <code>https.pl</code>) then the URL will be set to HTTP (e.g. ''http://example.eprints.org'')
 +
; <code>base_url</code>
 +
: This is set to <code>http_url</code> or https_url</code> depending on whether <code>$c->{securehost}</code> is defined.
 
; <code>http_root</code>
 
; <code>http_root</code>
: The HTTP version of the root path.  Typically this will be undefined unless EPrints needs to run under its own path (e.g. ''http://example.eprints.org/eprints'' will need the <code>http_root</code> set to <code>/eprints</code>).
+
: The HTTP version of the root path.  Typically this will an empty string unless EPrints needs to run under its own path (e.g. ''http://example.eprints.org/eprints'' will need the <code>http_root</code> set to <code>/eprints</code>).
 
; <code>https_root</code>
 
; <code>https_root</code>
: The HTTPS version of the root path.  Typically this will be undefined unless EPrints needs to run under its own path (e.g. ''https://example.eprints.org/eprints'' will need the <code>https_root</code> set to <code>/eprints</code>).
+
: The HTTPS version of the root path.  Typically this will be empty string unless EPrints needs to run under its own path (e.g. ''https://example.eprints.org/eprints'' will need the <code>https_root</code> set to <code>/eprints</code>).
 
; <code>rel_path</code>
 
; <code>rel_path</code>
: This is the same as the <code>http_root</code> or <code>https_root</code> dependent on whether the current page is HTTP or HTTPS.  If these are not defined, this will be set to an empty string.
+
: Like <code>base_url</code> this is the same as the http_root or https_root dependent on whether <code>$c->{securehost}</code> is defined.
 +
 
 +
Each of the six configuration settings above have their sister configuration settings for their CGI URLs or paths:
 +
{| class="wikitable"
 +
|-
 +
! Setting
 +
! CGI Setting
 +
! Example
 +
! CGI Example
 +
|-
 +
| http_url
 +
| http://example.eprints.org
 +
| http_cgiurl
 +
| http://example.eprints.org/cgi
 +
|-
 +
| https_url
 +
| https://example.eprints.org
 +
| https_cgiurl
 +
| https://example.eprints.org/cgi
 +
|-
 +
| base_url
 +
| https://example.eprints.org
 +
| perl_url
 +
| https://example.eprints.org/cgi
 +
|-
 +
| http_root
 +
|
 +
| http_cgiroot
 +
| /cgi
 +
|-
 +
|-
 +
| https_root
 +
|
 +
| https_cgiroot
 +
| /cgi
 +
| rel_path
 +
|
 +
| rel_cgipath
 +
| /cgi
 +
|}
 +
 
 +
Over time there has been a move from EPrints repositories being HTTP-only to HTTP and HTTPS and further towards HTTPS only (with HTTP redirects)EPrints configuration has had to evolve over time to support all these use cases, so those running EPrints can (continue to) run the HTTP/HTTPS setup that works for them. (Although, the recommendation would be to use the most secure configuration available).  However, this has led to inconsistent use of the twelve configuration settings for URLs and paths described above.  Therefore, EPrints 3.4.3 has attempted to tidy up much of this.
  
==== New Configuration Settings ====
+
The use of <code>http_url</code>, <code>https_url</code>, <code>http_cgiurl</code> and <code>https_cgiurl</code> is unnecessary, when <code>base_url</code> and <code>perl_url</code> by default will consistently provide the most secure available option(The only case where there may be issue is for URIs representing eprint itemsWhere changing the repository setup should not change permanent URIs. For this the recently introduced <code>uri_url</code> configuration option can be used).  Using <code>base_url</code> and <code>perl_url</code> consistently also ensure that there is not switching between the use of HTTPS and HTTP.  In particular, this helps avoid problems with web browser reporting mixed content warnings (e.g. HTTP images on HTTPS pages) and warnings when forms if they submit to an HTTP URL and the page is HTTPS.  
In EPrints 3.4.3, two additional URL configuration settings have been defined to help assist making EPrints repositories more secure and reduce issues, like web pages reporting mixed content warnings or forms popping up security warnings when they are submitted.
 
; <code>pr_url</code>
 
: This is a protocol-relative URL (e.g. ''//example.eprints.org'').  If the current page is HTTP, the link will take the user to the HTTP pageSimilarly if the current page is HTTPS the link will take the user to the HTTPS pageThis is useful to prevent users switching between HTTP and HTTPS, which they might find concerning. However, this is not suitable for some export formats where the text for the URL can be seen, as the format of the (protocol-relative) URL is likely to be unfamiliar to usersIt may also not be supported by some third-party applications that ingest EPrints exports.
 
; <code>preferred_url</code>
 
: This is the preferred URL, (i.e. the most secure available URL).  In essence this works the same as <code>https_url</code> but avoids any confusion over whether the URL will still be set to HTTPS if HTTPS is not enabled.
 
  
Both of these new URL configuration settings have their sister cgi configuration settings, i.e. <code>pr_cgiurl</code> and <code>preferred_cgiurl</code>.  Like the existing <code>http_cgiurl</code>, <code>https_cgiurl</code>, <code>http_cgipath</code>, <code>https_cgipath</code> and <code>rel_cgipath</code>, they are the same as their non-cgi siblings, albeit with a <code>/cgi</code> suffix (e.g. ''//example.eprints.org'' becomes ''//example.eprints.org/cgi'').  
+
Using a full URL (with a protcol and hostname) is excessive in most cases and therefore <code>rel_path</code> and <code>rel_cgipath</code> should be the preferred option. However, there are a number of situations where this would not be appropriate, as the URL may be used outside the scope of the EPrint repository:
 +
# In export formats for eprint items
 +
# In citations for eprint items
 +
# Links in the web page head to related alternate resources of services independent of the web page (i.e. to export formats, API services but not CSS, JavaScript, favicons, etc.).  
 +
For all these scenarios not using a full URLs might prevent the resource being accessed once the content has been exported, embedded or consumed by a user or third-party application.
  
==== Legacy Configuration Settings ====
+
The use of <code>http_root</code>, <code>https_root</code>, <code>http_cgiroot</code> and <code>https_cgiroot</code> is also unnecessary, when  <code>base_url</code> and <code>perl_url</code> are available.  Except when being used to defined other URL and path configuration settings or (with <code>http_url</code>) generating Apache configuration (using ''bin/generate_apacheconf'').
EPrints still has a number of legacy configuration settings that relate to URLs and paths, some small changes have been made to these to ensure they have the most appropriate setting:
+
 
; <code>urlpath</code>
+
==== Summary of Changes ====
: This is equivalent to <code>http_root</code> and this has not changed for EPrints 3.4.3.
+
* All existing URL and path configuration settings have been retained to ensure existing plugins and bespoke code continue to function.
; <code>base_url</code>
+
* Eliminate use of <code>http_url</code> (except in Apache configuration generation), <code>https_url</code>, <code>http_cgiurl</code> and <code>https_cgiurl</code>.
: This was set to <code>http_url</code> with a trailing <code>/</code> but has been changed to <code>pr_url</code> also with a trailing '/' for EPrints 3.4.3. However, the current default ''cfg.d/20_baseurls.pl'' for both ''lib/'' and ''flavours/pub_lib/'' overrides this with the equivalent HTTPS or HTTP URL depending on whether <code>$c->{securehost}</code> is defined.
+
* Use <code>base_url</code> and <code>perl_url</code> for links related to user-generated content (i.e. eprint summary/abstract pages, document download URLs, document preview images/thumbnails, etc.), links defined in the head of a web page that are not directly related to the generation of the page (i.e. everything but CSS stylesheets, JavaScript and favicons) and links that are rendered as text on a web page. 
; <code>perl_url</code>
+
* Use <code>rel_path<code> and <code>rel_cgipath<code> for all other purposes where it is unnecessary <code>base_url</code> or <code>perl_url</code>.
: Similarly, this was set to <code>http_cgiurl</code> with a trailing <code>/</code> but has been changed to <code>pr_cgiurl</code> also with a trailing'/' for EPrints 3.4.3. However, like <code>base_url</code>, the current default ''cfg.d/20_baseurls.pl'' for both ''lib/'' and ''flavours/pub_lib/'' overrides this with the equivalent HTTPS or HTTP URL depending on whether <code>$c->{securehost}</code> is defined.
+
* Eliminate use of <code>http_cgiroot</code> and <code>https_cgiroot</code> and limit use of <code>http_root</code> and <code>https_root</code> to Apache configuration generation and in defining other configuration settings.
; <code>frontpage</code>
+
* Ensure <code>rel_path</code> is used for links in templates, static pages and other places where previously no URL/path configuration setting was used. To ensure these links work when EPrints is not running on the root path (i.e. <code>rel_path</code> is not an empty string).
: As this URL text often appears rendered within a web page, although this was set to <code>http_url</code> with a trailing '/' it has be changed to <code>preferred_url</code> also with a trailing <code>/</code> for EPrints 3.4.3.
 
; <code>userhome</code>
 
: This has remained unchanged as <code>http_cgiroot</code> trailed by <code>/users/home</code> is not affected by the HTTPS setup for the repository.
 
  
 
[[Category:Eprints3.4]]
 
[[Category:Eprints3.4]]
 
[[Category:Planned Releases]]
 
[[Category:Planned Releases]]

Revision as of 09:31, 11 April 2021

Provisional Release Notes

EPrints 3.4.3 release candidate 1 is now available on GitHub. Full release still planned for end of March 2021.

  • Zero codename: Snickerdoodle Sandstorm
  • Publications flavour codename: Banana Bread Rainbow


New Dependencies

None. Check earlier dependencies for EPrints 3.4.2 and before.


Changes Since 3.4.2

New Functionality

  • Provides function (EPrints::Utils::compare_version) for comparing EPrints software versions so plugins can choose to behave differently.
  • Adds jquery EPrints 3.4 ingredient to allow JQuery resources to be incorporated if required by non-core EPrints functionality. Ingredient added but commented out in flavours/pub_lib/inc.
  • Provides picker for date fields to reduce potential for human error.


Security and Privacy Improvements

  • Makes JSON export respect value set for export_as_xml to avoid exporting unintended fields.
  • Sets contact_email to not export by default for better GDPR compliance.
  • Rate limits failed local login attempts for a particular user. Defaults to 10 failed login attempts in 10 minutes (using $c->{max_login_attempts} and $c->{lockout_minutes} configuration options).
  • Rate limits new account requests. Defaults to 100 requests in a hour long period to avoid causing problems with planned mass sign up events. Configured using $c->{max_account_requests} and $c->{max_account_requests_minutes} options.
  • Limits the maximum length of a password (default 200 characters) to prevent specific Denial-of-Service attacks.
  • Modifies latex invocation to make more secure an ensure it rights to the correct output directory.
  • Removes legacy /cgi/latex2png script to prevent Remote Code Execution (RCE) from CVE-2021-3342.
  • Validates parameters passed to /cgi/cal script to protect against RCE and Cross Site Scripting (XSS) from CVE-2021-26475 and CVE-2021-26476.
  • Validates dataset parameter passed to /cgi/dataset_dictionary to protect against XSS from CVE-2021-26702.
  • Validates parameters passed to /cgi/history_search to protect against the possibility of XSS and MySQL injection vulnerabilities, although none currently exploitable.
  • Validates verb passed to /cgi/toolbox/toolbox to protect against RCE from CVE-2021-26704.
  • Allows EPrints::XML::parse_string to temporarily modify parser configuration to disable expanding of XML entities by the /cgi/ajax/phrase script to protect against CVE-2021-26703.
  • Ensure eprints_lang cookie explicitly sets SameSite attribute to Lax if HTTPS is not enabled or sets secure attribute to 1 if it is.
  • Doubles (to 16) number of characters used for randomly generated password suggestions (e.g. for database user created by epadmin).


General Improvements

  • Resolves all accessibility errors and most alerts (as reported by the WAVE Web Accessibility Evaluation Tool) for backend admin pages as listed in the Accessibility report.
  • Tidies up the use of configuration URLs and Paths
  • Uses HTML class for Longtext_counter counter line and provides CSS to by default make this red and bold if the maxwords limit is exceeded.
  • Allows full path or just subject name to be displayed for values set in subjects field by setting render_path attribute (true by default).
  • Allows time between password reset requests to be configured (to a number of hours) rather than hard-coded to 24 hours.
  • Adds option to set status of EPrints that should be checked by check_xapian script.
  • Adds date_embargo_retained field to Documents to retain the embargo date after the embargo is lifted.
  • Adds deprecation warning to indicate only LibXML library will be supported in future versions of EPrints. (Version for removal yet to be confirmed).
  • Adds basic default citation for files.
  • Adds validation for date fields to prevent invalid dates being set.
  • Allows files to be stored to disk with generic filenames (i.e. <fileid>.bin) rather than the upload filename that can cause retrieval problem by setting the $c->{generic_filenames} configuration setting.
  • Adds code to lib and pub_lib versions of security.pl to deal with request a copy access issue if repository has coversheets plugin enabled.
  • Allows sub-fields to have help texts configured.
  • Generates log message for views that have reached their max_items limit.
  • Allows document fields displayed in an eprint's Details tab to be configured.
  • Adds data-context attributes to aid CSS styling of HTML div elements within search forms.
  • Improves scaling of of Lightbox popups on narrow screens.
  • Allows a pin to set the id or class attribute for a template HTML element to facilitate different CSS styling on different pages.
  • Prompts for organisation name when creating a new archive using epadmin create.
  • Allows classes to be assigned to parts (i.e. top, left, main, after, etc.) of abstract/summary pages to facilitate better CSS styling.
  • Allows search results forms to be configured to automatically reload on ordering change.
  • Allows classes for EPrints' user menu (i.e. by default ep_tm_key_tools) to be configured to better integrate with institutional branding.
  • Adds commented advice on fixing issues with PDF thumbnail generation using ImageMagick.
  • Tidies up citations by removing identical flavours/pub_lib/ citations that appear in lib/.
  • Allows max_files that can be expanded from an uploaded zip file to be configured. (Previously hardcoded to 100 file limit).
  • Allows customisable overriding of type-mapping based on ispublished value for BiBTeX and RIS export. (I.e. not using @unpublished type if ispublished set to unpub).
  • Provides has_role EPC function to allow more granular control of workflows that can be edited by specific group of user that have has this role added to their profile.
  • Allows positioning of hovering document preview to be set to left or right and implements this in summary_page and result eprint citations to improve preview positioning.
  • Improves verbosity of get_input and get_input_hidden to explain better why input is invalid. Assisting epadmin data entry.
  • Makes id_number (i.e. for DOIs, etc.) field default type id rather than text to facilitate search for exact IDs, espeically those containing non-alphanumeric characters (e.g. 10.1016/j.ejor.2018.02.047).

Bug Fixes

  • Prevents access code from changing if request a copy is approved multiple times (and warns if request has already been approved).
  • Fixes formatting of results from user search introduced by accessibility changes in 3.4.2.
  • Updates issue citation to use <div> rather than and tags so it works with accessibility changes introduced in 3.4.2.
  • Deals more gracefully if History DataObj's parent does not exist when checking if it is an EPrints::List.
  • Fixes internal server error when trying to save values to a non-multiple compound field.
  • Fixes issue with XML import setting unset compound subfields to NULL rather than empty string.
  • Fixes errors on import pages caused by Accessibility improvements and fixes other Accessibility issues for import pages.
  • Fixes broken link of default 401 error page.
  • Sets STDOUT and STDERR binmode to utf8 to avoid wide character errors.
  • Fixes user history layout as a result of earlier Accessibility improvements.
  • Fixes missing phrases reported in error logs. Typically fieldhelp phrases for sub-fields of compound fields, which are generally not rendered but still report missing phrase warnings.
  • Sets SameSite property to None for secure login and request copy cookies as Google Chrome is now quite strict about this.
  • Provides handling for XML parsing of revision files to show warning for particular revision in the hostory tab rather than an internal server error for the whole page.
  • Allows use of same pin multiple times within a phrase.
  • Prevents undefined $c->{aliases} from causing epadmin config_core to fail.
  • Ensures saved searches indicate email notifications cannot be sent when the Xapianv2 (in addition to Xapian) plugin has been used for the original search.
  • Adds missing event_queue phrases.
  • Fixes inappropriate mapping of monograph_type in BibTeX import.
  • Fixes erroneous post-login redirection when login required to access eprint summary/abstract pages and long URLs (e.g. /id/eprint/1234) enabled.
  • Ensures readonly attribute works for MetaField::Set in compound-multiple fields.
  • Adds missing reason phrase for RejectWithEmail screen plugin.
  • Prevents HEAD requests (e.g. email link checkers) for password from resets from actioning the reset. (Otherwise, when the user clicks the link it will say the password has already been reset, which may concern the user).
  • Forces full day-month-year to be set for document embargo expiry to avoid any ambiguity.
  • Improves epadmin by removing unusable functionality and reporting if database tables do not get created as expected.
  • Adds symlinks between brief and default citations for various data objects to prevent log warnings.
  • Better handles DOI not being set when parsing it.
  • Provides more useful logging when field has invalid parameters.
  • Fixes missing pin for error message phrase when restarting indexer.
  • Fixes MetaField::Listing from logging an error that no datasetid is defined when on its index page (listing datasets).
  • Updates positions for plugins that appear in key tools menu to ensure deterministic ordering.
  • Fixes bug to allow REST calls for subjects with IDs that contain full stops (.).
  • Better handles finding parent eprint when this has been deleted.
  • Fixes tools/map_config.pl to use correct directory for EPrints 3.4 and allow flavour to be specified as a parameter.
  • Fixes tools/update_phrase/file to ensure EPrints libraries can be used and allows specified base path, current working directory or full path to be used for phrase file parameters.
  • Fixes BibTeX import using uploaded files broken by update to third-party BibTeX::Parser in EPrints 3.4.2.

Configuration URLs and Paths

EPrints has various configuration settings for URLs and paths that are automatically configured based on the settings in an archive's cfg/cfg.d/10_core.pl. The six most significant are the following:

http_url
The HTTP version of the URL (e.g. http://example.eprints.org). Since EPrints 3.4.1, this will be set to the same as https_url if $c->{host} is undefined in the archive's cfg/cfg.d/10_core.pl.
https_url
The HTTPS version of the URL (e.g. https://example.eprints.org). If $c->{securehost} is not defined in the archive's cfg/cfg.d/ directory (typically in 10_core.pl or https.pl) then the URL will be set to HTTP (e.g. http://example.eprints.org)
base_url
This is set to http_url or https_url depending on whether $c->{securehost} is defined.
http_root
The HTTP version of the root path. Typically this will an empty string unless EPrints needs to run under its own path (e.g. http://example.eprints.org/eprints will need the http_root set to /eprints).
https_root
The HTTPS version of the root path. Typically this will be empty string unless EPrints needs to run under its own path (e.g. https://example.eprints.org/eprints will need the https_root set to /eprints).
rel_path
Like base_url this is the same as the http_root or https_root dependent on whether $c->{securehost} is defined.

Each of the six configuration settings above have their sister configuration settings for their CGI URLs or paths:

Setting CGI Setting Example CGI Example
http_url http://example.eprints.org http_cgiurl http://example.eprints.org/cgi
https_url https://example.eprints.org https_cgiurl https://example.eprints.org/cgi
base_url https://example.eprints.org perl_url https://example.eprints.org/cgi
http_root http_cgiroot /cgi
https_root https_cgiroot /cgi rel_path rel_cgipath /cgi

Over time there has been a move from EPrints repositories being HTTP-only to HTTP and HTTPS and further towards HTTPS only (with HTTP redirects). EPrints configuration has had to evolve over time to support all these use cases, so those running EPrints can (continue to) run the HTTP/HTTPS setup that works for them. (Although, the recommendation would be to use the most secure configuration available). However, this has led to inconsistent use of the twelve configuration settings for URLs and paths described above. Therefore, EPrints 3.4.3 has attempted to tidy up much of this.

The use of http_url, https_url, http_cgiurl and https_cgiurl is unnecessary, when base_url and perl_url by default will consistently provide the most secure available option. (The only case where there may be issue is for URIs representing eprint items. Where changing the repository setup should not change permanent URIs. For this the recently introduced uri_url configuration option can be used). Using base_url and perl_url consistently also ensure that there is not switching between the use of HTTPS and HTTP. In particular, this helps avoid problems with web browser reporting mixed content warnings (e.g. HTTP images on HTTPS pages) and warnings when forms if they submit to an HTTP URL and the page is HTTPS.

Using a full URL (with a protcol and hostname) is excessive in most cases and therefore rel_path and rel_cgipath should be the preferred option. However, there are a number of situations where this would not be appropriate, as the URL may be used outside the scope of the EPrint repository:

  1. In export formats for eprint items
  2. In citations for eprint items
  3. Links in the web page head to related alternate resources of services independent of the web page (i.e. to export formats, API services but not CSS, JavaScript, favicons, etc.).

For all these scenarios not using a full URLs might prevent the resource being accessed once the content has been exported, embedded or consumed by a user or third-party application.

The use of http_root, https_root, http_cgiroot and https_cgiroot is also unnecessary, when base_url and perl_url are available. Except when being used to defined other URL and path configuration settings or (with http_url) generating Apache configuration (using bin/generate_apacheconf).

Summary of Changes

  • All existing URL and path configuration settings have been retained to ensure existing plugins and bespoke code continue to function.
  • Eliminate use of http_url (except in Apache configuration generation), https_url, http_cgiurl and https_cgiurl.
  • Use base_url and perl_url for links related to user-generated content (i.e. eprint summary/abstract pages, document download URLs, document preview images/thumbnails, etc.), links defined in the head of a web page that are not directly related to the generation of the page (i.e. everything but CSS stylesheets, JavaScript and favicons) and links that are rendered as text on a web page.
  • Use rel_path and rel_cgipath for all other purposes where it is unnecessary base_url or perl_url.
  • Eliminate use of http_cgiroot and https_cgiroot and limit use of http_root and https_root to Apache configuration generation and in defining other configuration settings.
  • Ensure rel_path is used for links in templates, static pages and other places where previously no URL/path configuration setting was used. To ensure these links work when EPrints is not running on the root path (i.e. rel_path is not an empty string).