EPrints Documentation - User contributions [en-gb]

Config Options by File

2016-08-23T07:45:16Z

Denics@free.fr: /* dynamic_template.pl */

[[Category:Manual]]

== 10_core.pl ==
* aliases
* host
* port
* securehost
* securepath
== 20_baseurls.pl ==
* base_url
* perl_url
* urlpath
== adminemail.pl ==
* adminemail
== branding.pl ==
* site_logo
== database.pl ==
* dbhost
* dbname
* dbpass
* dbuser
== document_fields_automatic.pl ==
* set_document_automatic_fields
== document_fields_default.pl ==
* set_document_defaults
== document_upload.pl ==
* diskspace_error_threshold
* diskspace_warn_threshold
* guess_doc_type
* on_files_modified
* required_formats
== document_validate.pl ==
* validate_document
== dynamic_template.pl ==
*[[API:EPrints/Apache/Template#Dynamic_Pins|Dynamic Pins]]

== email.pl ==
* send_email
== eprint_fields.pl ==
* fields
== eprint_fields_automatic.pl ==
* set_eprint_automatic_fields
== eprint_fields_default.pl ==
* set_eprint_defaults
== eprint_render.pl ==
* eprint_render
== eprint_validate.pl ==
* validate_eprint
== eprint_warnings.pl ==
* eprint_warnings
== field_property_defaults.pl ==
* field_defaults
== field_validate.pl ==
* validate_field
== indexing.pl ==
* extract_words
* index
* indexing
== languages.pl ==
* defaultlanguage
* languages
== log.pl ==
* log
* loghandler
== misc.pl ==
* allow_user_removal_request
* cache_maxlife
* cache_timeout
* cookie_auth
* cookie_domain
* disable_userinfo
* pin_timeout
* skip_buffer
* use_mimetex
== oai.pl ==
* oai
== paths.pl ==
* config_path
* documents_path
* htdocs_path
== registration.pl ==
* allow_reset_password
* allow_web_signup
* default_user_type
* signup_style
* user_registration_fields
== request_copy.pl ==
* email_for_doc_request
== search.pl ==
* editor_limit_fields
* issues_search
* latest_citation
* latest_tool_modes
* match_start_of_name
* search
== security.pl ==
* can_request_view_document
* can_user_view_document
== session.pl ==
* session_close
* session_init
== sword.pl ==
* sword
== urls.pl ==
* frontpage
* rewrite_exceptions
* userhome
== user_fields.pl ==
* fields
== user_fields_automatic.pl ==
* set_user_automatic_fields
== user_fields_default.pl ==
* set_user_defaults
== user_render.pl ==
* user_render
== user_roles.pl ==
* user_roles
== user_validate.pl ==
* validate_user
== views.pl ==
* browse_views
== vlit.pl ==
* vlit

EPrints Package Manager

2016-07-14T16:50:23Z

Denics@free.fr: /* EPM Manager Basics */

[[Category:EPrints Bazaar]]

=The EPrints Package Manager=

This page explains the the core features and aims of the EPrints package manager which will see its debut in EPrints 3.3

==Overview==

The EPrints Package Manager is basically a cross between a linux package repository and a user friendly GUI store (think fruit flavoured mobile application store). This makes it a highly open platform for developing extensions specific to a single product which has the flexability and functionality of certain closed stores.

The EPM system consists of 2 main parts, EPM repositories and the client side EPM manager which handles packages installed both from an EPM repository as well as those sourced locally. The EPM manager is able to source packages from more than one EPM repository as is defined by the EPM manager configuration file stored relative to each repository. The EPM manager is also responsible for handling the installation, location of upgrades and EPM development of a new EPM compliant package.

In this document we look at each of the feature of the EPM manager, these in turn aid in the development of an EPM package.

==What is an EPM package and what it is not!==

* A EPM package consists of a series of files which can be dropped into the ARCHIVE_ID location at any level.
* An EPM package is not able to patch existing files and will exit if an existing file is not managed by the package being installed.
* It is possible to perform other changes to the archive not specified in the EPM by adding a custom configuration screen to the package which can be accessed by users after a successful install, more on this later.

==EPM Manager Basics==
* Both command line (via tools/epm) and GUI access (via the Admin interface)
* Basic commands/capabilities. Just download the epm file and run tools/epm from your eprints home.

** build
** disable
** enable
** install
** link_cfg
** link_lib
** list
** rebuild
** uninstall
** unpack

Example command line
perl tools/epm install package.epm

==The EPM Admin GUI==

The EPM admin GUI reflects the command line access and has 4 main tabs which are displayed depending on if there is content to put on them, e.g. the "Installed Packages" tab will not display until you have an EPM installed. The tabs are (in order of display):

===Available Upgrades===
If a later version of a package is found in an EPM repository to the one you have installed locally, this tab will allow you to install the new version.

===Installed Packages===
From this tab you can view, remove and configure installed packages.

===Available Packages===
This tab shows the packages available from the various EPM repositories you have defined.

===Local Packages===
This tab is the development and advanced administrators tab and allows you to upload a custom package into the EPM manager. Once uploaded these packages are checked for complience to the EPM specification before they can be installed. This also means that this tab is ideal for developmental testing of EPM packages.

==The technical side to the EPM Manager (how it works)==

===Installing & Upgrading===
These are essentially the same as the EPM Manager will check each file it is attempting to installed to see if it meets the following conditions.

====Before install/upgrade====
* Make a backup of any previously installed version of this package.

====During install/upgrade====
* If no file exists at destination install from EPM package, record the installed checksum.
* If a file exists and is managed by a previous version of this package (by checksum) copy the new one over the top and checksum.
* If a file exists and is not managed by a previous version of this package (including if it has been changed since the last install), abort and remove files installed to this point, then put back the old files.

====After successful install/upgrade====
* Attempt to reload the repository, if this fails, abort and rollback as the user may loose the ability to launch the package manager to do this later!
* Store checksums, spec file and related package files (e.g. package icon) locally overwriting any previous.

===Removing===
* Make a backup
* Using the checksums file, attempt to remove all files listed if they match their checksum still.
* If success, remove package cache, else call a forced install with the backup which will cause it to all be put back how it was.

=TODO=
* Get postinst/prerm scripts working via a packages configuration screen and define these classes.
* Add ability to search the EPM repositories to both GUI and command line.
* Add ability to cache package list as a local dataset which can be searched here rather then centrally.
* Limit GUI to displaying most popular 20 packages, rest are searched for, this will maintain speed when EPM system gets popular.
* Add button to local packages tab to allow a custom package to be submitted to the EPrints central EPM repository. In all fairness the button is there but the EPM repository is still under construction.

Files/OAI Harvester 1.02

2012-05-01T13:30:53Z

Denics@free.fr: Redirected page to Files/OAI Harvester for EPrints 3.2+

#REDIRECT [[Files/OAI Harvester for EPrints 3.2+]]

Adding new views

2012-03-23T14:35:40Z

Denics@free.fr: /* Browse by type */

[[Category:Manual]]
[[Category:Browse Views]]

{{development}}

Browse views provide a way for visitors to your site to discover relevant content without a specific item in mind (for example, browsing all the content associated with a particular topic). Visitors arriving directly at the page for a specific item in the repository (for example, via a search engine) also use views you have defined to discover related content.

There are two default views in EPrints - '''By Year''' and '''By Subject'''. This guide describes how to add additional views to your repository.
Instead with this link you can read a [http://wiki.eprints.org/w/Views.pl complete list of all options] avaible for views.

__TOC__

===The basics===

The views for your repository are defined in the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Open this file and find the browse_views configuration setting:

$c->{browse_views} = [
{
id => "year",
fields => "-date;res=year",
...
},
{
id => "subjects",
fields => "subjects",
...
},
];

The views are defined using a special (Perl) syntax: the view definition consists of a pair of curly braces (''note the comma after each closing brace'') enclosing a list of property/value pairs (note ''the comma'' after each line).

The key part of the view definition is the '''fields''' property. This names the metadata field (or fields) that EPrints will use to construct the view. For example, for the '''By Year''' view, EPrints groups the records in the repository according to their '''date''' (note that the '''res=year''' suffix tells EPrints to only consider the year part), and constructs a Web page for each date listing the records. Similarly, the '''Browse by Subjscts''' view, groups the records according to the ''subjects'' they have been assigned to (a record may appear in more than one group!).

Both the '''Browse by Year''' and '''Browse by Subject''' views are constructed using the values of a single field ('''date''' and '''subjects''' respectively).

It is also possible to construct a view using the ''combined'' values of two or more fields (eg. group records by author '''and''' editor), or even using a sequence of two or more fields (eg. group records by journal title '''and then''' by volume number).

===Worked example: browse by organisational structure===

By default, EPrints has a ''divisions'' metadata field which allows authors to associate their deposits with the divisions (units, faculties, schools, departments, institutes, centres..) that were involved in producing their item (for example, the author's department, and the departments of any co-authors). This worked example allows visitors to browse the repository content by division.

Open the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Add the following definition to the browse_views setting:

$c->{browse_views} = [
{
id => "year",
...
},
{
id => "subjects",
...
},
{
id => "divisions",
fields => "divisions",
order => "-date/title",
hideempty => 1,
},
];

Save the file and generate the new view pages (this will also re-generate any existing views defined in the views configuration file):

bin/generate_views ARCHIVEID --verbose

Open the view page in a Web browser:

http://your.repository.url/view/

The view page lists all the available views. You should see your new views on the list:

[[Image:View_page2.png|frame|none|The view page lists available views]]

'''Fixing the undefined phrase warning''' The new view may appear on the views page with an ''undefined phrase'' warning (you may also notice a similar warning message when running generate_views):

["viewname_eprint_divisions" not defined]

Each view you create needs to be assigned a ''human-readable'' name, which EPrints will use on the view Web pages.

Edit the language-specific phrases file for view names:

/opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/views.xml

Add an appropriate phrase which describes the new view, for example:

<epp:phrase id="viewname_eprint_divisions">Division</epp:phrase>

Save the phrases file and regenerate the view pages:

bin/generate_views ARCHIVEID --verbose

===Example view definitions===

====Browse by type (3.3.8)====

Every deposit in EPrints has a type (article, book, thesis...). To allow visitors to browse your repository content by type, add the following definition to the browse_views setting:

{
id=>"doctype",
menus => [
{
fields => [ "type" ],
},],
order=>"-date",
},

====Browse by author====

===Example views (combined fields)===

====Browse by author and editor====

===Example views (multiple fields)===

====Browse by journal title, then by volume====

This example lets visitors browse the journals items in your repository have been published in, and then volumes within each journal.

{
id=>"journal_volume",
fields=>"publication,volume",
order=>"-date/title",
hideempty => 1,
},

[[Image:Browse_by_journal.png|border]]

[[Image:Browse_by_journal_volume.png|border]]

===Linking in your view===

You now need to add a link to your repository pages which takes visitors directly to your new view, or to the views page from where they can access all available views.

[[Image:Browse_by_navbar.png]]

====Generating CVs etc====

===Linking items back to views===
===Views as collections===

===New options in EPrints 3.1===

====subfield no longer supported====

The subfield option is no longer supported in EPrints 3.1.

====new_column_at====

This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 10 ]

This would have one column of values until there were 11, then there would be 2 columns.

[ 10, 10 ]

This would have one column if there were ten or less values, two columns if there were between eleven and twenty (ten + ten) values, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

Add one to the number of integers in the array and you get the maximum number of columns. The value of each integer defines the point at which that column becomes full, and more values cause an 'overflow' into the next column.

====variations====

This controls the various ways in which a browse view can be subheaded. It consists of a list of strings. Each string is the name of a non-compound metadata field (or the keyword DEFAULT, for an unsubheaded list), optionally followed by a semi-colon and a comma separated list of options. E.G:

variations => [
"creators_name;first_letter",
"type",
"DEFAULT"
],

See [[views.pl]] for the list of options.

EPrints Control Format

2012-03-23T14:16:19Z

Denics@free.fr: /* $index (3.2.0+) */

{{formats}}

= EPrints Control =

== Output Tags ==

=== epc:print ===

<epc:print expr='expression' opt='key=value;key2=value2'/>

<cite:citation xmlns="http://www.w3.org/1999/xhtml"
xmlns:cite="http://eprints.org/ep3/citation"
xmlns:epc="http://eprints.org/ep3/control">
<epc:print expr="$item.citation('default')" />
</cite:citation>

Outputs the result of the expression in the 'expr' attribute.

Rendering options may be passed in the opt attribute using a key=value form, with semicolons separating multiple options.

Any [[EPScript]] expression can be used. The most simple is just 'eprintid','title','creators' etc. You can also use values from the configuration files by using '$config{base_url}'.

=== Print in attributes using {} ===

Sometimes you may wish to insert a value into an XML attribute. eg. the "href" part of an anchor. Rather than a complicated system, but correct XML, we decide to go for something a bit more readable. Any {} pair in an XML attribute will be treated as a epc:print.

So you can do something like

<nowiki><a href="http://eprints.badger.edu/cgi/myscript.pl?eprintid={eprintid}">run myscript on this eprint</a></nowiki>

=== epc:phrase ===

simple:
<epc:phrase ref='phraseid' />

with pins:
<epc:phrase ref='phraseid'>
<epc:param name='somepin'>Content</epc:param>
</epc:phrase>

Outputs the content of the phrase refered to by 'ref'. Any necessary parameters may be set using the <epc:param> tag, with the contents inserted into the pin with the name corresponding to the name attribute.

== Conditional Tags ==

=== epc:if ===

<epc:if test='expr'>
...
</epc:if>

Outputs any XHTML content and evaluates any EPrints Control structures within the epc:if block if the expression in the test attribute is true.

=== epc:choose, epc:when, epc:otherwise ===

<epc:choose>
<epc:when test='expr'>
...
</epc:when>
<epc:when test='expr2'>
...
</epc:when>
<epc:otherwise>
...
</epc:otherwise>
</epc:choose>

epc:choose allows for the construction of a complex conditional. Each epc:when block's 'test' attribute is evaluated, and the content of the block is returned if the result is true. If no expressions return true, the optional epc:otherwise block is returned. Note that no subsequent epc:when blocks are evaluated once the first block to return true is reached.

== Loops ==

Multiple values can be iterated over. For example.

<epc:foreach expr="creators_name" iterator="name">
( <epc:print expr="$name" /> )
</epc:foreach>

=== $index (3.2.0+) ===

Within a foreach block you can use $index to find what iteration of the loop is on. The first value is zero.

This can be used with the modulus "%" to add a strip effect, if wanted, eg.

<nowiki><table>
<epc:foreach expr="creators_name" iterator="name">
<epc:if test="$index % 2">
<tr class='odd'><td><epc:print expr="$name" /></td></tr>
</epc:if>
<epc:if test="!($index % 2)">
<tr class='even'><td><epc:print expr="$name" /></td></tr>
</epc:if>
</epc:foreach>
</table></nowiki>

=== limit (3.2.0+) ===

You can set a limit of how many iterations to process using a "limit" attribute on the epc:foreach element. For example,

<epc:foreach expr="creators_name" iterator="name" limit="3">

== epc:debug (3.2.0+) ==

The epc:debug element has identical syntax to epc:print, but the result is sent to the error log -- either the command line, or to the apache error log.

<epc:debug expr='expression' opt='key=value;key2=value2'/>

== epc:set (3.2.0+) ==

This allows a variable to be set for any print or if elements within the epc:set. This is useful if creating the value has a notable cost which you wish to minimise.

$item.documents() requires some database access, and the results are not cached, so using this speeds things up.

<epc:set name='docs' expr='$item.documents()'>

LDAP

2012-03-14T15:42:20Z

Denics@free.fr: /* LDAP Authentication */

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

===Kerberos Authentication on AD with On-Demand Creation of Users using LDAP ===

Tested on 3.3.8

Here's another example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>:

* allowing LDAP accounts to login, using the following example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# Kerberos authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required
use Authen::Krb5::Simple;
use Authen::SASL;

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "OU=people,DC=example,DC=org";
my $proxy_user ="ad_read";
my $dn = "CN=$proxy_user,$base";

# Kerberos tunables
my $krb_host = "example.org";

my $krb = Authen::Krb5::Simple->new(realm => $krb_host);
unless ( $krb )
{
print STDERR "Kerberos error: $@\n";
return 0;
}

my $ldap = Net::LDAP->new ( $ldap_host );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

my $sasl = Authen::SASL->new(
mechanism => 'GSSAPI',
callback => { user => 'ad_read' }
) or die "$@";

my $mesg = $ldap->bind(sasl => $sasl);

if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
filter => "(&(sAMAccountName=$username))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail', 'department', 'title'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}

# Check password
if( !$krb->authenticate( $username, $password ) )
{
print STDERR "$username authentication failed: ", $krb->errstr(), "\n";
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$name->{honourific} = $entr->get_value( "title");
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->set_value( "dept", $entr->get_value("department") );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

===Possible enhancements===

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP

2012-03-14T15:40:57Z

Denics@free.fr: /* Kerberos Authentication on AD with On-Demand Creation of Users using LDAP */

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

===Kerberos Authentication on AD with On-Demand Creation of Users using LDAP ===

Tested on 3.3.8

Here's another example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>:

* allowing LDAP accounts to login, using the following example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# Kerberos authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required
use Authen::Krb5::Simple;
use Authen::SASL;

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "OU=people,DC=example,DC=org";
my $proxy_user ="ad_read";
my $dn = "CN=$proxy_user,$base";

# Kerberos tunables
my $krb_host = "example.org";

my $krb = Authen::Krb5::Simple->new(realm => $krb_host);
unless ( $krb )
{
print STDERR "Kerberos error: $@\n";
return 0;
}

my $ldap = Net::LDAP->new ( $ldap_host );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

my $sasl = Authen::SASL->new(
mechanism => 'GSSAPI',
callback => { user => 'ad_read' }
) or die "$@";

my $mesg = $ldap->bind(sasl => $sasl);

if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
filter => "(&(sAMAccountName=$username))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail', 'department', 'title'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}

# Check password
if( !$krb->authenticate( $username, $password ) )
{
print STDERR "$username authentication failed: ", $krb->errstr(), "\n";
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$name->{honourific} = $entr->get_value( "title");
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->set_value( "dept", $entr->get_value("department") );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Possible enhancements====

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP

2012-03-14T15:40:15Z

Denics@free.fr: /* Kerberos Authentication on AD with On-Demand Creation of Users using LDAP */

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

===Kerberos Authentication on AD with On-Demand Creation of Users using LDAP ===

Tested on 3.3.8

Here's another example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>:

* allowing LDAP accounts to login, using the following example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# Kerberos authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required
use Authen::Krb5::Simple;
use Authen::SASL;

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "OU=people,DC=example,DC=org";
my $proxy_user ="ad_read";
my $dn = "CN=$proxy_user,$base";

# Kerberos tunables
my $krb_host = "example.org";

my $krb = Authen::Krb5::Simple->new(realm => $krb_host);
unless ( $krb )
{
print STDERR "Kerberos error: $@\n";
return 0;
}

my $ldap = Net::LDAP->new ( $ldap_host );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

my $sasl = Authen::SASL->new(
mechanism => 'GSSAPI',
callback => { user => 'ad_read' }
) or die "$@";

my $mesg = $ldap->bind(sasl => $sasl);

if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
filter => "(&(sAMAccountName=$username))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail', 'department', 'title'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}

# Check password
if( !$krb->authenticate( $username, $password ) )
{
print STDERR "$username authentication failed: ", $krb->errstr(), "\n";
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$name->{honourific} = $entr->get_value( "title");
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->set_value( "dept", $entr->get_value("department") );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Possible enhancements====

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP

2012-03-14T15:39:15Z

Denics@free.fr: /* Kerberos Authentication on AD with On-Demand Creation of Users using LDAP */

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

===Kerberos Authentication on AD with On-Demand Creation of Users using LDAP ===

Tested on 3.3.8

Here's another example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>:

* allowing LDAP accounts to login, using the following example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# Kerberos authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required
use Authen::Krb5::Simple;
use Authen::SASL;

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "OU=people,DC=example,DC=org";
my $proxy_user ="ad_read";
my $dn = "CN=$proxy_user,$base";

# Kerberos tunables
my $krb_host = "example.org";

my $krb = Authen::Krb5::Simple->new(realm => $krb_host);
unless ( $krb )
{
print STDERR "Kerberos error: $@\n";
return 0;
}

my $ldap = Net::LDAP->new ( $ldap_host );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

my $sasl = Authen::SASL->new(
mechanism => 'GSSAPI',
callback => { user => 'ad_read' }
) or die "$@";

my $mesg = $ldap->bind(sasl => $sasl);

if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
filter => "(&(sAMAccountName=$username))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail', 'department', 'title'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}

# Check password
if( !$krb->authenticate( $username, $password ) )
{
print STDERR "$username authentication failed: ", $krb->errstr(), "\n";
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$name->{honourific} = $entr->get_value( "title");
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->set_value( "dept", $entr->get_value("department") );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Possible enhancements====

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

LDAP

2012-03-14T15:38:31Z

Denics@free.fr: /* LDAP Authentication */

[[Category:Authentication]]

==LDAP Authentication==

===LDAP and User Roles===

It is recommended that certain user rights are removed when using LDAP for login. The user should not be allowed to change their password or their email address. It is also suggested that the user not be allowed to edit their profile, however I have found certain fields that I would like the user to edit. To set the rights edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_roles.pl

######################################################################
#
# User Roles
#
# Here you can configure which different types of user are
# parts of the system they are allowed to use.
#
######################################################################
$c->{user_roles}->{user} = [qw/
general
edit-own-record
saved-searches
deposit
/],
$c->{user_roles}->{editor} = [qw/
general
edit-own-record
saved-searches
deposit
editor
view-status
staff-view
/],
$c->{user_roles}->{admin} = [qw/
general
edit-own-record
saved-searches
set-password
deposit
change-email
editor
view-status
staff-view
admin
/],
#$c->{user_roles}->{minuser} = [qw/
# saved-searches
# set-password
# change-email
# change-user
# no_edit_own_record
# lock-username-to-email
#/];

After editing restart Apache.

===LDAP Authentication with Bulk Import of Users===

This recipe enables authenticating passwords against an LDAP directory for all users (including administrators). The users will need to already exist in EPrints, most likely created by a bulk import from your LDAP server.

The recommendation for EPrints is not to allow users to alter email and passwords, as these changes are not at present written back to the LDAP database.

====LDAP Configuration====

All changes for LDAP authentication can be made in a single file, the file contains useful notes on configuration. Here is an example from my site, I have configured a standard Samba Domain using LDAP for authentication, if you have similar then this config may work for you :

See [[user_login.pl]] for general information on check_user_password.

Edit the file :

vi /opt/eprints3/archives/yourarchivename/cfg/cfg.d/user_login.pl

# This function allows you to override the default username/password
# authentication. For example, you could apply different authentication rules to
# different types of user.
#
# Example: LDAP Authentication (Quick Start)
#
# Tip: use the test script to determine your LDAP parameters first!
# Tip: remove the set-password priviledge from users and editors in
# user_roles.pl. Also consider removing edit-own-record and
# change-email.
#
use Net::LDAP; # IO::Socket::SSL also required
use Net::LDAP::Util;

$c->{check_user_password} = sub {
my( $repo, $username, $password ) = @_;

my $user = $repo->user_by_username( $username );
return unless $user;

$username = $user->value( "username" );

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $repo->database->valid_login( $username, $password );
}

# LDAP authentication for "user" and "editor" types
#
# LDAP hostname (and port if not the default)
my $ldap_host = "ldap.yourdomain.ac.uk";
#my $ldap_host = "ldap.host.name:1234";
#my $ldap_host = "ldaps://ldap.host.name"; # if server supports LDAPS

# Distinguished name for this user
# The distinguished name is a unique name for an LDAP entry.
# e.g. "cn=John Smith, ou=staff, dc=eprints, dc=org"
# You will need to derive this from the username or user metadata
my $ldap_dn = sprintf("uid=%s,ou=People,dc=example,dc=org",
Net::LDAP::Util::escape_dn_value($username)
);

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
$repo->log( "LDAP error: $@" );
return;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls( sslversion => "sslv3" );
if( $ssl->code() )
{
$repo->log( "LDAP SSL error: " . $ssl->error() );
return;
}
# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return;
}

return $username;
}
# Advanced LDAP Configuration
#
# 1. It is also possible to define additional user types, each with a different
# authentication mechanism. For example, you could keep the default user,
# editor and admin types and add ldapuser, ldapeditor and ldapadmin types with
# LDAP authentication - this would suit an arrangement where internal staff are
# authenticated against the LDAP server but user accounts can still be granted
# to external users.
#
# 2. Sometimes the distinguished name of the user is not computable from the
# username. You may need to use values from the user metadata (e.g. name_given,
# name_family):
#
# my $name = $user->get_value( "name" );
# my $ldap_dn = $name->{family} . ", " . $name->{given} .", ou=yourorg, dc=yourdomain";
#
# or perform an LDAP lookup to determine it (more complicated):
#
# my $base = "ou=yourorg, dc=yourdomain";
# my $result = $ldap->search (
# base => "$base",
# scope => "sub",
# filter => "cn=$username",
# attrs => ['DN'],
# sizelimit=>1
# );
#
# my $entr = $result->pop_entry;
# unless( defined $entr )
# {
# return 0;
# }
# my $ldap_dn = $entr->dn
#
# Alternatively, you could store the distinguished name as part of the user
# metadata when the user account is imported print STDERR "LDAP SSL error: " . $ssl->error() . "\n";

After editing restart Apache.

====LDAP Import====

You can use the [http://files.eprints.org/27/1/update_users update_users script] and apply the following patch to make it work with eprints3:

<pre>
--- update_users.orig 2007-04-23 16:22:26.000000000 +0200
+++ update_users 2007-04-24 21:16:40.000000000 +0200
@@ -1,6 +1,6 @@
-#!/usr/bin/perl -w -I/opt/eprints2/perl_lib
+#!/usr/bin/perl -w -I/opt/eprints3/perl_lib

-use EPrints::User;
+use EPrints::DataObj::User;
use EPrints::Session;
use Net::LDAP;
use strict;
@@ -16,6 +16,7 @@

# Start connection
my $ldap = Net::LDAP->new( "ldap.host.name", version => 3 );
+$ldap->start_tls();
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
@@ -74,7 +75,7 @@
# New account
if( $forreal )
{
- $user = EPrints::User::create_user( $session, "ldapuser" );
+ $user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
print "CREATING: $username\n";
}
@@ -118,7 +119,7 @@
print "FAMILY = " . $entr->get_value( "sn" ) . "\n";
print "GIVEN = " . $entr->get_value( "givenName" ) . "\n";
print "EMAIL = " . $entr->get_value( "mail" ) . "\n";
- print "DN = " . $entr->get_value( "distinguishedName" ) . "\n";
+ print "DN = " . $entr->dn . "\n";

}

</pre>

===LDAP Authentication with On-Demand Creation of Users===

Here's an example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>

* allowing LDAP accounts to login, using the "Advanced LDAP Configuration" example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

Most of the code is from the default <tt>user_login.pl</tt> and from the [http://files.eprints.org/27/1/update_users update_users] script (which does not seem to exist anymore, but code & text below seem to have been written by [[User:Sp]] not later than May 7th 2007).

Be sure to only use this over [[HTTPS]]!

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# LDAP authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "dc=example,dc=org";
my $dn = "cn=someProxyAccount,ou=accounts,$base";

my $ldap = Net::LDAP->new ( $ldap_host, version => 3 );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

# Start secure connection (not needed if using LDAPS)
my $ssl = $ldap->start_tls();
if( $ssl->code() )
{
print STDERR "LDAP SSL error: " . $ssl->error() . "\n";
return 0;
}

# Get password for the search-bind-account
my $repository = $session->get_repository;
my $id = $repository->get_id;
my $ldappass = `cat /opt/eprints3/archives/$id/cfg/ldap.passwd`;
chomp($ldappass);

my $mesg = $ldap->bind( $dn, password=>$ldappass );
if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
scope => "sub",
filter => "(&(uid=$username)(objectclass=inetOrgPerson))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail'],
sizelimit=>1
);
my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}
my $ldap_dn = $entr->dn;

# Check password
my $mesg = $ldap->bind( $ldap_dn, password => $password );
if( $mesg->code() )
{
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Things to note====

* This script uses a dedicated proxy account which must exist in your LDAP tree and has appropriate permissions (ACL settings) to search for users and read their <tt>uid,givenname,sn,mail</tt> attributes.
* It gets this proxy accounts' password from a file inside the repository configuration. this file needs to have read permissions for the user your webserver runs as (e.g. <tt>www-data</tt> on Debian). Use file system permissions to protect this (e.g. <tt>chmod 400 ldap.passwd</tt>).
* It changes the flow of <tt>user_login.pl</tt> a little to only check for local ''admin'' accounts (no users or editors; we have them all in our LDAP tree) and only when no user is found for ldap authentication. This allows you to have your admins in LDAP (if you want) but still use the local admin for "promoting" other users to admins, among other things (which could also be done with a simple SQL <code>update</code> directly in the RDBMS). If you don't need the local admin, remove those lines and just <tt>return 0</tt> since no user was found in LDAP.
* you could change the default role for generated user accounts from <tt>user</tt>, if you really wanted.

===Kerberos Authentication on AD with On-Demand Creation of Users using LDAP ===

Tested on 3.3.8

Here's another example of a customized <tt>/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/user_login.pl</tt>:

* allowing LDAP accounts to login, using the following example
* allowing the local eprints admin account to login w/ database authentication
* creating eprints accounts for all successfully authenticated LDAP users ''on the fly''

$c->{check_user_password} = sub {
my( $session, $username, $password ) = @_;

# Kerberos authentication for "user", "editor" and "admin" types (roles)

use Net::LDAP; # IO::Socket::SSL also required
use Authen::Krb5::Simple;
use Authen::SASL;

# LDAP tunables
my $ldap_host = "ldap.example.org";
my $base = "OU=people,DC=example,DC=org";
my $proxy_user ="ad_read";
my $dn = "CN=$proxy_user,$base";

# Kerberos tunables
my $krb_host = "example.org";

my $krb = Authen::Krb5::Simple->new(realm => $krb_host);
unless ( $krb )
{
print STDERR "Kerberos error: $@\n";
return 0;
}

my $ldap = Net::LDAP->new ( $ldap_host );
unless( $ldap )
{
print STDERR "LDAP error: $@\n";
return 0;
}

my $sasl = Authen::SASL->new(
mechanism => 'GSSAPI',
callback => { user => 'ad_read' }
) or die "$@";

my $mesg = $ldap->bind(sasl => $sasl);

if( $mesg->code() )
{
print STDERR "LDAP Bind error: " . $mesg->error() . "\n";
return 0;
}

# Distinguished name (and attribues needed later on) for this user
my $result = $ldap->search (
base => "$base",
filter => "(&(sAMAccountName=$username))",
attrs => ['1.1', 'uid', 'sn', 'givenname', 'mail', 'department', 'title'],
sizelimit=>1
);

my $entr = $result->pop_entry;
unless( defined $entr )
{
# Allow local EPrints authentication for admins (accounts not found in LDAP)
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
return 0 unless $user;

my $user_type = $user->get_type;
if( $user_type eq "admin" )
{
# internal authentication for "admin" type
return $session->get_database->valid_login( $username, $password );
}
return 0;
}

# Check password
if( !$krb->authenticate( $username, $password ) )
{
print STDERR "$username authentication failed: ", $krb->errstr(), "\n";
return 0;
}

# Does account already exist?
my $user = EPrints::DataObj::User::user_with_username( $session, $username );
if( !defined $user )
{
# New account
$user = EPrints::DataObj::User::create( $session, "user" );
$user->set_value( "username", $username );
}

# Set metadata
my $name = {};
$name->{family} = $entr->get_value( "sn" );
$name->{given} = $entr->get_value( "givenName" );
$name->{honourific} = $entr->get_value( "title");
$user->set_value( "name", $name );
$user->set_value( "username", $username );
$user->set_value( "email", $entr->get_value( "mail" ) );
$user->set_value( "dept", $entr->get_value("department") );
$user->commit();

$ldap->unbind if $ldap;

return 1;
}

====Possible enhancements====

Currently this script does not remove local eprints accounts from the database: when accounts get deleted from the LDAP database the corresponding local EPrints accounts sit around forever. But since login isn't possible anymore this is not a risk or of high priority.

Depending on your situation it may be enough to run some kind of cleanup script, e.g. once a year, that get's a list of all local EPrints accounts, loops over them and <code>$user->remove</code>s all those, which cannot be found in LDAP anymore (except for those where <code>$user_type eq 'admin'</code>, so you don't risk losing your local admins).

IRStats

2012-03-07T17:30:03Z

Denics@free.fr:

[[Category:IRStats]]
IRStats is a flexible statistics package which allows easy processing of accesses to fulltext documents of eprints. It can be downloaded from the [http://files.eprints.org/722/ Eprints File repository]. For more detailed information, please see the [[IRStats Technical Documentation]], though it is now somewhat out of date.

== The front end ==

===The Query Form===

The main interface to IRStats is found at the following URL (given a repository base URL of myrepository.ac.uk):

<pre>
myrepository.ac.uk/cgi/irstats.cgi
</pre>

You will be presented with a form allowing you to select the parameters with which to generate a report.

===Advanced Report Generation (get_view2 params)===

The following will help if you wish to create queries by setting the CGI parameters by hand.

There are three fundamental parameters that IRStats uses. There are:
* A Date Range (actually 6 parameters for day, month and year for both start and end dates)
* A Set of EPrints
* A View

However, in order to add functionality, the get_view2 page will convert a larger number of parameters into these three. The following table shows all parameters and values, with square brackets denoting variables.

{| border="1"
! Parameter
! Possible Values
! Notes
|-
| IRS_datechoice || period, range || Controls whether the 6 date range parameters or the single period parameter is used.
|-
| period || -[X]m, Q[Z][YYYY] || Used when IRS_datechoice=period. Where m and Q are literal characters, X is a positive integer, Z is an integer in the range 1 to 4 and YYYY is a four digit year. Examples: <dl><dt>-4m<dd>Go back exactly four months from today's date<dt>Q32004<dd>Quarter 3, 2004</dl>
|-
| start_day, start_month, start_year, end_day, end_month, end_year || integers (1-31, 1-12, four digit respectively) || Used when IRS_datechoice=range. Note that if a day value is higher than the highest day in the chosen month, it will be treated as the highest day -- e.g. start_day=31&start_month=02 is seen as valid and equivalent to February 28th. Note that start_day=99 is also valid!
|-
| IRS_epchoice || All, EPrint, [set_id] || Controls whether stats will be generated on all eprints, a single eprints, or a set of eprints. The 'All' option is the only one that does not require extra parameters. Note that 'set_id' is the id of a valid set as defined in the IRStats configuration.
|-
| eprint || [eprintid] || Used when IRS_epchoice=EPrint. Any valid eprint ID (integer).
|-
| [set_id]s || [set_id]_[set_member_code] || Used when IRS_epchoice=[set_id]. Best described through example: <dl><dt>IRS_epchoice=divisions&divisionss=divisions_art<dd>Will generate a report on the art department, given a standard EPrints repository and IRStats config, where the subject id 'art' exists in the divisions tree in EPrints.
|-
| view || [view classname] || The classname of the IRStats::View perl module.
|}

===The Dashboard Form===

A dashboard is a collection of reports on a single item or set of items (e.g. all items by John Smith). To access the form to generate a report, go to the url:

<pre>
myrepository.ac.uk/cgi/irstats.cgi?page=db
</pre>

== The configuration file ==

Documentation to follow.

IRStats

2012-03-07T17:29:49Z

Denics@free.fr:

[[Category:IRStats]]
IRStats is a flexible statistics package which allows easy processing of accesses to fulltext documents of eprints. It can be downloaded from the [http://files.eprints.org/722/ | Eprints File repository]. For more detailed information, please see the [[IRStats Technical Documentation]], though it is now somewhat out of date.

== The front end ==

===The Query Form===

The main interface to IRStats is found at the following URL (given a repository base URL of myrepository.ac.uk):

<pre>
myrepository.ac.uk/cgi/irstats.cgi
</pre>

You will be presented with a form allowing you to select the parameters with which to generate a report.

===Advanced Report Generation (get_view2 params)===

The following will help if you wish to create queries by setting the CGI parameters by hand.

There are three fundamental parameters that IRStats uses. There are:
* A Date Range (actually 6 parameters for day, month and year for both start and end dates)
* A Set of EPrints
* A View

However, in order to add functionality, the get_view2 page will convert a larger number of parameters into these three. The following table shows all parameters and values, with square brackets denoting variables.

{| border="1"
! Parameter
! Possible Values
! Notes
|-
| IRS_datechoice || period, range || Controls whether the 6 date range parameters or the single period parameter is used.
|-
| period || -[X]m, Q[Z][YYYY] || Used when IRS_datechoice=period. Where m and Q are literal characters, X is a positive integer, Z is an integer in the range 1 to 4 and YYYY is a four digit year. Examples: <dl><dt>-4m<dd>Go back exactly four months from today's date<dt>Q32004<dd>Quarter 3, 2004</dl>
|-
| start_day, start_month, start_year, end_day, end_month, end_year || integers (1-31, 1-12, four digit respectively) || Used when IRS_datechoice=range. Note that if a day value is higher than the highest day in the chosen month, it will be treated as the highest day -- e.g. start_day=31&start_month=02 is seen as valid and equivalent to February 28th. Note that start_day=99 is also valid!
|-
| IRS_epchoice || All, EPrint, [set_id] || Controls whether stats will be generated on all eprints, a single eprints, or a set of eprints. The 'All' option is the only one that does not require extra parameters. Note that 'set_id' is the id of a valid set as defined in the IRStats configuration.
|-
| eprint || [eprintid] || Used when IRS_epchoice=EPrint. Any valid eprint ID (integer).
|-
| [set_id]s || [set_id]_[set_member_code] || Used when IRS_epchoice=[set_id]. Best described through example: <dl><dt>IRS_epchoice=divisions&divisionss=divisions_art<dd>Will generate a report on the art department, given a standard EPrints repository and IRStats config, where the subject id 'art' exists in the divisions tree in EPrints.
|-
| view || [view classname] || The classname of the IRStats::View perl module.
|}

===The Dashboard Form===

A dashboard is a collection of reports on a single item or set of items (e.g. all items by John Smith). To access the form to generate a report, go to the url:

<pre>
myrepository.ac.uk/cgi/irstats.cgi?page=db
</pre>

== The configuration file ==

Documentation to follow.

IRStats

2012-03-07T17:29:04Z

Denics@free.fr:

[[Category:IRStats]]
IRStats is a flexible statistics package which allows easy processing of accesses to fulltext documents of eprints. It can be downloaded from the [[ http://files.eprints.org/722/ | Eprints File repository]]. For more detailed information, please see the [[IRStats Technical Documentation]], though it is now somewhat out of date.

== The front end ==

===The Query Form===

The main interface to IRStats is found at the following URL (given a repository base URL of myrepository.ac.uk):

<pre>
myrepository.ac.uk/cgi/irstats.cgi
</pre>

You will be presented with a form allowing you to select the parameters with which to generate a report.

===Advanced Report Generation (get_view2 params)===

The following will help if you wish to create queries by setting the CGI parameters by hand.

There are three fundamental parameters that IRStats uses. There are:
* A Date Range (actually 6 parameters for day, month and year for both start and end dates)
* A Set of EPrints
* A View

However, in order to add functionality, the get_view2 page will convert a larger number of parameters into these three. The following table shows all parameters and values, with square brackets denoting variables.

{| border="1"
! Parameter
! Possible Values
! Notes
|-
| IRS_datechoice || period, range || Controls whether the 6 date range parameters or the single period parameter is used.
|-
| period || -[X]m, Q[Z][YYYY] || Used when IRS_datechoice=period. Where m and Q are literal characters, X is a positive integer, Z is an integer in the range 1 to 4 and YYYY is a four digit year. Examples: <dl><dt>-4m<dd>Go back exactly four months from today's date<dt>Q32004<dd>Quarter 3, 2004</dl>
|-
| start_day, start_month, start_year, end_day, end_month, end_year || integers (1-31, 1-12, four digit respectively) || Used when IRS_datechoice=range. Note that if a day value is higher than the highest day in the chosen month, it will be treated as the highest day -- e.g. start_day=31&start_month=02 is seen as valid and equivalent to February 28th. Note that start_day=99 is also valid!
|-
| IRS_epchoice || All, EPrint, [set_id] || Controls whether stats will be generated on all eprints, a single eprints, or a set of eprints. The 'All' option is the only one that does not require extra parameters. Note that 'set_id' is the id of a valid set as defined in the IRStats configuration.
|-
| eprint || [eprintid] || Used when IRS_epchoice=EPrint. Any valid eprint ID (integer).
|-
| [set_id]s || [set_id]_[set_member_code] || Used when IRS_epchoice=[set_id]. Best described through example: <dl><dt>IRS_epchoice=divisions&divisionss=divisions_art<dd>Will generate a report on the art department, given a standard EPrints repository and IRStats config, where the subject id 'art' exists in the divisions tree in EPrints.
|-
| view || [view classname] || The classname of the IRStats::View perl module.
|}

===The Dashboard Form===

A dashboard is a collection of reports on a single item or set of items (e.g. all items by John Smith). To access the form to generate a report, go to the url:

<pre>
myrepository.ac.uk/cgi/irstats.cgi?page=db
</pre>

== The configuration file ==

Documentation to follow.

IRStats

2012-03-07T17:28:46Z

Denics@free.fr:

[[Category:IRStats]]
IRStats is a flexible statistics package which allows easy processing of accesses to fulltext documents of eprints. It can be downloaded from the [[Eprints File repository | http://files.eprints.org/722/]]. For more detailed information, please see the [[IRStats Technical Documentation]], though it is now somewhat out of date.

== The front end ==

===The Query Form===

The main interface to IRStats is found at the following URL (given a repository base URL of myrepository.ac.uk):

<pre>
myrepository.ac.uk/cgi/irstats.cgi
</pre>

You will be presented with a form allowing you to select the parameters with which to generate a report.

===Advanced Report Generation (get_view2 params)===

The following will help if you wish to create queries by setting the CGI parameters by hand.

There are three fundamental parameters that IRStats uses. There are:
* A Date Range (actually 6 parameters for day, month and year for both start and end dates)
* A Set of EPrints
* A View

However, in order to add functionality, the get_view2 page will convert a larger number of parameters into these three. The following table shows all parameters and values, with square brackets denoting variables.

{| border="1"
! Parameter
! Possible Values
! Notes
|-
| IRS_datechoice || period, range || Controls whether the 6 date range parameters or the single period parameter is used.
|-
| period || -[X]m, Q[Z][YYYY] || Used when IRS_datechoice=period. Where m and Q are literal characters, X is a positive integer, Z is an integer in the range 1 to 4 and YYYY is a four digit year. Examples: <dl><dt>-4m<dd>Go back exactly four months from today's date<dt>Q32004<dd>Quarter 3, 2004</dl>
|-
| start_day, start_month, start_year, end_day, end_month, end_year || integers (1-31, 1-12, four digit respectively) || Used when IRS_datechoice=range. Note that if a day value is higher than the highest day in the chosen month, it will be treated as the highest day -- e.g. start_day=31&start_month=02 is seen as valid and equivalent to February 28th. Note that start_day=99 is also valid!
|-
| IRS_epchoice || All, EPrint, [set_id] || Controls whether stats will be generated on all eprints, a single eprints, or a set of eprints. The 'All' option is the only one that does not require extra parameters. Note that 'set_id' is the id of a valid set as defined in the IRStats configuration.
|-
| eprint || [eprintid] || Used when IRS_epchoice=EPrint. Any valid eprint ID (integer).
|-
| [set_id]s || [set_id]_[set_member_code] || Used when IRS_epchoice=[set_id]. Best described through example: <dl><dt>IRS_epchoice=divisions&divisionss=divisions_art<dd>Will generate a report on the art department, given a standard EPrints repository and IRStats config, where the subject id 'art' exists in the divisions tree in EPrints.
|-
| view || [view classname] || The classname of the IRStats::View perl module.
|}

===The Dashboard Form===

A dashboard is a collection of reports on a single item or set of items (e.g. all items by John Smith). To access the form to generate a report, go to the url:

<pre>
myrepository.ac.uk/cgi/irstats.cgi?page=db
</pre>

== The configuration file ==

Documentation to follow.

IRStats

2012-03-07T17:28:17Z

Denics@free.fr:

[[Category:IRStats]]
IRStats is a flexible statistics package which allows easy processing of accesses to fulltext documents of eprints. It can be downloaded from eprints file repository [[http://files.eprints.org/722/]]. For more detailed information, please see the [[IRStats Technical Documentation]], though it is now somewhat out of date.

== The front end ==

===The Query Form===

The main interface to IRStats is found at the following URL (given a repository base URL of myrepository.ac.uk):

<pre>
myrepository.ac.uk/cgi/irstats.cgi
</pre>

You will be presented with a form allowing you to select the parameters with which to generate a report.

===Advanced Report Generation (get_view2 params)===

The following will help if you wish to create queries by setting the CGI parameters by hand.

There are three fundamental parameters that IRStats uses. There are:
* A Date Range (actually 6 parameters for day, month and year for both start and end dates)
* A Set of EPrints
* A View

However, in order to add functionality, the get_view2 page will convert a larger number of parameters into these three. The following table shows all parameters and values, with square brackets denoting variables.

{| border="1"
! Parameter
! Possible Values
! Notes
|-
| IRS_datechoice || period, range || Controls whether the 6 date range parameters or the single period parameter is used.
|-
| period || -[X]m, Q[Z][YYYY] || Used when IRS_datechoice=period. Where m and Q are literal characters, X is a positive integer, Z is an integer in the range 1 to 4 and YYYY is a four digit year. Examples: <dl><dt>-4m<dd>Go back exactly four months from today's date<dt>Q32004<dd>Quarter 3, 2004</dl>
|-
| start_day, start_month, start_year, end_day, end_month, end_year || integers (1-31, 1-12, four digit respectively) || Used when IRS_datechoice=range. Note that if a day value is higher than the highest day in the chosen month, it will be treated as the highest day -- e.g. start_day=31&start_month=02 is seen as valid and equivalent to February 28th. Note that start_day=99 is also valid!
|-
| IRS_epchoice || All, EPrint, [set_id] || Controls whether stats will be generated on all eprints, a single eprints, or a set of eprints. The 'All' option is the only one that does not require extra parameters. Note that 'set_id' is the id of a valid set as defined in the IRStats configuration.
|-
| eprint || [eprintid] || Used when IRS_epchoice=EPrint. Any valid eprint ID (integer).
|-
| [set_id]s || [set_id]_[set_member_code] || Used when IRS_epchoice=[set_id]. Best described through example: <dl><dt>IRS_epchoice=divisions&divisionss=divisions_art<dd>Will generate a report on the art department, given a standard EPrints repository and IRStats config, where the subject id 'art' exists in the divisions tree in EPrints.
|-
| view || [view classname] || The classname of the IRStats::View perl module.
|}

===The Dashboard Form===

A dashboard is a collection of reports on a single item or set of items (e.g. all items by John Smith). To access the form to generate a report, go to the url:

<pre>
myrepository.ac.uk/cgi/irstats.cgi?page=db
</pre>

== The configuration file ==

Documentation to follow.

How to add a subdirectory that runs PHP scripts

2012-03-07T15:17:02Z

Denics@free.fr:

[[Category:Howto]]
In this example, we are adding a 'blog' directory, perhaps to host wordpress.

===Edit (or create) [eprint install dir]/archives/[archive]/cfg/cfg.d/[[20_baseurls.pl]]===

Amend this line to include the directory you want to make an exception for.

Here we are adding the directory /blog/ to the array.
$c->{[[rewrite_exceptions]]} = [ '/cgi/', '/archive/', ''''/blog/''''];

Save and close.

===Edit: [eprint install dir]/archives/[archive]/cfg/[[apachevhost.conf]]===

And add the following.

Alias /blog/ /path/to/blog/
<Location "/blog">
AddHandler php5-script php
DirectoryIndex index.php
</Location>
<Directory /path/to/blog>
Order allow,deny
Allow from all
</Directory>

===Restart Apache===

/etc/init.d/apache2 force-reload

User:Denics@free.fr

2011-12-22T17:09:36Z

Denics@free.fr: Created page with 'Ciao!'

Ciao!

How to

2011-12-10T11:53:02Z

Denics@free.fr: /* Using an external search engine */

[[Category:Howto]]
==HOW TO: Set up a Complex Custom View==
Simple instructions are in the ArchiveConfig.pm section.

Example situation: On my main website www.foobars.ac.uk I have a page per research project, of which we have hundreds. Each project has a short unique id code, eg. "manticore". I have a field in my eprints archive (eprints.foobars.ac.uk) which is configured:

<code>
{ name=>"projectcodes", type=>"text", multiple=>1 }
</code>
I add the following browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title" }
</code>
This will generate a page http://eprints.foobars.ac.uk/views/by_project/manticore.html with a list of all papers in that project, we can link to that URL!

===Making the Field link to the Browse Page===
If you want a subject to link the subject browse page of that value, add the '''browse_link''' property to the field (and regenerate the abstracts if you want).

If you remove the browse view you should remove the browse_link or it will be a broken link.

Values rendered inside citations which are used to link to the main record will not link into the browse view for obvious reasons.

===Including a view in another page===
If you change that to:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1 }
</code>
This will generate a view which is NOT listed on the /view/ page and it will not skip making the .html file and make a .include file per value. This will only contain the "count" of items and the XHTML of their citations. This can be used as part of a page on the http://www.foobaars.ac.uk/ site; either by using php and capturing it on-the-fly using <tt>readfile</tt> or scripting it with perl or NFS exporting the filesystem onto the main server (or just doing it all on one computer) and using server side includes to place it in a page.

===Customising the way each item is cited===
I want to list the project papers in a strict format in a table with 4 columns: title, author(s), year and an icon which links to the document abstract page...

I add some ''more'' options to the browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1,
nocount=>1, citation=>"project_table" }
</code>
Now I add a new citation to the citations config file:

<code>
<ep:citation type="project_table"><tr><td>&title;</td><td>&authors;</td>
<td>&year;</td><td><ep:linkhere><img
src="http://www.foobars.ac.uk/images/paperlink.png" alt="view" width="32"
height="64" border="0" /></ep:linkhere></td></tr></ep:citation>
</code>
That should generate for the manticore project, in the ".include" file (I've cut the contents of the "img" tag for readability:

<code>
<tr><td>Making Stuff</td><td>Guy, A.</td><td>2001</td><td><a
href="http://eprints.foobar.ac.uk/archive/00000923/"><img ... /></a>
</td></tr>
<tr><td>Eating Food</td><td>Herring, Walter and Chips, Bob</td><td>
2000</td><td><a href="http://eprints.foobar.ac.uk/archive/00000445/">
<img ... /></a></td></tr>
</code>
===A "CV" page - a list of all of Alices records===
This is where the authors and editors field having an ID comes in handy.

Say we use local username to identify people in the "Person ID" fields, we can now set up a view:

<code>
{ id=>"by_person", allow_null=>0, fields=>"authors.id/editors.id",
order=>"-year/title", noindex=>1, include=>1 }
</code>
This will generate both .html pages and .include pages. An member of your organisation can get a list of their records either by linking to <tt>/views/by_person/alice.html</tt> (where alice is their username) or by snarfing the URL <tt>/views/by_person/alice.include</tt> into his own homepage.

==HOW TO: Fields==
===Add a new Field
This convers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but invloves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

; Add the Field to ArchiveMetafieldConfig.pm : Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)

<code>
{ name => "local", type => "set", input_rows => 1,
options => [ "yes", "no", "partial" ] }
</code>
input_rows being set to one will make it appear as a pull-down menu.
; Add the Field to metadata-types.xml : If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in metadata-types.xml (this can be changed on a live system without any serious consequencies).

<code>
<field name="local" required="yes" />
</code>
; Add the Field Information to the Archive Phrase File(s) : Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language).

<code>
<ep:phrase ref="eprint_fieldname_local">Produced Locally</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_local">Please indicate if this item was
produces in the foo organisation, or not.
<ep:phrase ref="eprint_fieldopt_local_yes">produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_no">not produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_partial">only partially produced
locally</ep:phrase>
</code>

====Other things you may wish to change after adding a new field====
; Add it to the citations file : This is optional, only do this if you want it to appear in the citated forms.
In our example case we only want this to appear when citing technical reports, so we change that entry to:

<code>
<ep:citation type="eprint_techreport"><ep:linkhere>&authors; <ep:ifset name="year">(&year;)
</ep:ifset>&title;. Technical Report<ep:ifset name="reportno">
&reportno;</ep:ifset><ep:ifset name="department">, &department;
</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>.
&local;.</ep:linkhere></ep:citation>
</code>
All we've done is add <tt>&local;.</tt> to the end. It's not inside <tt> <ep:ifset name="local"> </tt> as it is a required field and will (should) always be set.
; Add it to the the Abstract (or View-User) page. : This is also optional. If you want it to appear on the web page for this item then edit ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.
In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...
Single language example:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
# don't need to "my $p" as it's done earlier.
$p = $session->make_element( "p" );
$p->appendChild( $session->make_text( "This item was " ) );
$p->appendChild( $eprint->render_value( "local" ) );
$p->appendChild( $session->make_text( "." ) );

# Append our new paragraph to the page.
$page->appendChild( $p );
}
</code>
Multiple-language example:
If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<code>
<ep:phrase ref="page:itemnotlocal">This item was <pin ref="status" />.</ep:phrase>
</code>
And to the ArchiveRenderConfig.pm file:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
my $localmsg = $session->html_phrase(
"page:itemnotlocal",
status=>$eprint->render_value( "local" ) );
$page->appendChild( $localmsg );
}
</code>
You may prefer to use this method even if you are only using a single language.
; Add extra Validation Routines : If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm
; Add it to the OAI metadata (eprints only) : If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.
; Add a browse view (eprints only) : If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.

===HOW TO: Remove a Field===
The quick answer is to say "the opposite of adding one".

; Remove the Field to metadata-types.xml : Removing it from here will mean that nobody can enter values for that field. Which is possibly enough, and means you can put it back later.
; Remove the Field to ArchiveMetafieldConfig.pm : This will remove it from the database ( and require a rebuild as with adding a field ).
; Remove it from the phrase file(s) : This is optional, unused phrases are just ignored.
; Remove it from the citations file : If it's used there.
; Remove it from the the Abstract (or View-User) page. : If it's used there.
; Remove extra Validation Routines : In the unlikely event you added some validation which looks at this field.
; Remove it from the OAI metadata (eprints only) : If it's being used. Fields used to generate the default dublincore are: title, authors, subjects, abstract, year and month. It also uses "type" which is a system field so you can't remove it!
; Remove it from browse views (eprints only) : If it's used there.

==HOW TO: EPrint types==
===Add a new eprint type===
Add the eprint type to '''metadata-types.xml'''. Some fields should probably be "required".

Add the name of the type to the phrase file.

Add a citation for this type to the citations file.

===Remove an eprint type===
Remove it from metadata-types.xml

You can remove it from the phrase file & citations but it won't hurt to leave it there.

==HOW TO: Add a new document type==
Add it to '''metadata-types.xml'''. This does not need any fields.

Add the name of the document type to the phrase file.

Add a citation for this document to the citations file.

If you want this to be one of the must-have-one-of document types then add it's id to the list in ArchiveConfig.pm

If you want to do something "clever" on the abstract page then edit the ArchiveRenderConfig.pm file. If you don't then it will use the citiation you created to render it in the list, as with PDF, HTML etc.

==HOW TO: Add a Discussion Forum for Each EPrint==
The UK Open University (open.ac.uk) have set up a service which allows you to create a discussion for every EPrint in your archive.

The really easy way to do this is to use their discussion server. If you want to run your own d3e server the software is available from http://d3e.sourceforge.net/

===Using d3eprints.open.ac.uk===
Just add the following code to the ArchiveRenderConfig.pm file just before the <tt>if( $has_multiple_versions )</tt> bit.

Please note that this code is not internationalised.

<code>
#####################################
# Begin D3Eprints links

my $ol = $session->make_element( "ol" );
my $li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/disc.php?url=".$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"View public discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/private/disc.php?url=".
$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"Create private discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$table->appendChild( _render_row(
$session,
$session->make_text( "D3Eprints discussion" ),
$ol ) );

# End of D3Eprints links
#####################################
</code>
==HOW TO: Website Integration==
===Make the latest additions to your archive appear on your main website===
The contents of the "latest" page - /perl/latest - can be included via a cron tab using wget and a server side include or using something like PHP's command to do:

<code>
readfile( "http://eprints.foo.org/perl/latest?mainonly=yes" );
</code>
The "mainonly=yes" flag is a hack which supresses the template of any eprints page in the /perl/ area so that it can be included, but it is most useful for "latest".

WARNING: If you have a script which imports 1000 records in one night then latest isn't currently bright enough to truncate the list so your homepage could get kinda messy.

===RSS into HTML===
If you want to turn any search into a dynamically generated list of references with a link back to the EPrints page, then use this. This solution uses PHP. So, you will need PHP enabled on the server.

'''Dependency:''' This code depends on [http://magpierss.sourceforge.net/ MagpieRSS].

'''Original Context:''' It was developed for use in a [http://www.terminalfour.com/ Terminal4 'SiteManager'] template, but can be used with almost no modification.

The code implements local caching of the generated HTML in a text file which is never more than an hour old, unless there is a problem with the server whereupon the last good cached version is used.

<code>
require_once('D:/website/[path to]/magpierss/rss_fetch.inc');
//set some variables here:
$anchor = '<t4 type="meta" meta="html_anchor" />';
# All items in Terminal4's cms have an anchor - we like break it apart to get the Unique id, to name the cache file.
$TTL = 3600;
# Time to live - one hour only.
$feed = '<t4 type="content" name="RSS_Feed_URL" output="normal" modifiers="" />';
$uniqueID = explode("\"", $anchor);
$filename = "./" . str_replace('.', '-', $uniqueID[1]) . ".txt";
#filename of cache - generated from unique id in T4 content management system.
$max_items = <t4 type="content" name="MaxNumberToShow" output="normal" modifiers="" />;
# $max_items = 30; // this is set in EPrints as well, will not exceed Eprints' own internal limit.
$with_summaries = '<t4 type="content" name="ShowSummary" output="normal" modifiers="" />'; # could be 'yes' or 'no'
$age = 0;
if(file_exists($filename)){
$age = time() - filemtime($filename);
}else{
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
$age = $TTL;
}

function getFromCache($f){
$fh = fopen($f, "r");
$size = filesize($f);
$data = fread($fh, $size);
print $data;
fclose($fh);
}

if($age >= $TTL){
if($rss = fetch_rss($feed)){
$items = array_slice($rss->items, 0);
$find = array("/^\.?/");
$replace = array(" ");
$news_feed = "<ul class=\"rss_list\">\n";
foreach ($items as $item ){
if($count < $max_items){
$news_feed .= "\t<li class=\"rss_item\">\n";
$news_feed .= "\t\t<a href=\"" . $item['link'] . "\" target=\"_blank\">";
$news_feed .= $item['title'] . "</a>\n\t\t \n";
if($with_summaries == 'yes'){
$news_feed .= "\t\t\n\t\t\t";
$news_feed .= str_replace(($item['title'] . "."), "", htmlentities($item['summary'])) . " \n\t\t\n";
}
$news_feed .= "\t\t \n\t</li>\n";
$count += 1;
}
}
$news_feed .= "</ul>\n\n";
echo $news_feed;
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
}else{
getFromCache($filename);
}
}else{
getFromCache($filename);
}
# David Kane, Waterford Institute of Technology
</code>

==HOW TO: Add full text searching==
EPrints does not support this natively but there are several options.

===htdig, or similar software===
There is plenty of software which will provide a full text search of a website. To add non-eprints cgi scripts to your site create a directory in the cgi dir:

<code>
mkdir /opt/eprints2/cgi/local
</code>
and place your scripts in there, they will have URLs under <tt>http://yoursite.com/perl/</tt>

===Using an external search engine===
This is very easy, but will only index public documents. Any search engine will work, but Google is a good choice. Google provide a site-search service which allows you to register with them and then have a form which searches your site using google and adds your logo and colourscheme to the results.

A really easy solution is to just make a form which links to our "google_site" script which just adds "site:yoursite.com" to the google request to limit the search results. The HTML for this would be something like:

<form action="/perl/google_site">
Use Google to search this site:
<input name="q" value="" />
<input type="submit" name="go" value="Search" />
</form>

For other search engines; see their documentation for how to make a form to search only your site.

==HOW TO: Make the referencetext field link to the items referenced==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Make the password controlled parts of the site use HTTPS==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Customise the way the the search results are formatted==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Reset your EPrints admin password [3.3]==

To directly reset your password, log into phpMyAdmin and execute the following mySQL statement:

UPDATE user SET password = encrypt('newpassword') WHERE userid = 1;
This will effectively reset the EPrint admin password for user 1. Note that you can use this to reset the password of any user, although this is typically unnecessary as you should be able to simply log in as admin user (user 1), under which you have the ability to reset any user's password.

How to

2011-12-10T11:26:26Z

Denics@free.fr: /* Using an external search engine */

[[Category:Howto]]
==HOW TO: Set up a Complex Custom View==
Simple instructions are in the ArchiveConfig.pm section.

Example situation: On my main website www.foobars.ac.uk I have a page per research project, of which we have hundreds. Each project has a short unique id code, eg. "manticore". I have a field in my eprints archive (eprints.foobars.ac.uk) which is configured:

<code>
{ name=>"projectcodes", type=>"text", multiple=>1 }
</code>
I add the following browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title" }
</code>
This will generate a page http://eprints.foobars.ac.uk/views/by_project/manticore.html with a list of all papers in that project, we can link to that URL!

===Making the Field link to the Browse Page===
If you want a subject to link the subject browse page of that value, add the '''browse_link''' property to the field (and regenerate the abstracts if you want).

If you remove the browse view you should remove the browse_link or it will be a broken link.

Values rendered inside citations which are used to link to the main record will not link into the browse view for obvious reasons.

===Including a view in another page===
If you change that to:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1 }
</code>
This will generate a view which is NOT listed on the /view/ page and it will not skip making the .html file and make a .include file per value. This will only contain the "count" of items and the XHTML of their citations. This can be used as part of a page on the http://www.foobaars.ac.uk/ site; either by using php and capturing it on-the-fly using <tt>readfile</tt> or scripting it with perl or NFS exporting the filesystem onto the main server (or just doing it all on one computer) and using server side includes to place it in a page.

===Customising the way each item is cited===
I want to list the project papers in a strict format in a table with 4 columns: title, author(s), year and an icon which links to the document abstract page...

I add some ''more'' options to the browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1,
nocount=>1, citation=>"project_table" }
</code>
Now I add a new citation to the citations config file:

<code>
<ep:citation type="project_table"><tr><td>&title;</td><td>&authors;</td>
<td>&year;</td><td><ep:linkhere><img
src="http://www.foobars.ac.uk/images/paperlink.png" alt="view" width="32"
height="64" border="0" /></ep:linkhere></td></tr></ep:citation>
</code>
That should generate for the manticore project, in the ".include" file (I've cut the contents of the "img" tag for readability:

<code>
<tr><td>Making Stuff</td><td>Guy, A.</td><td>2001</td><td><a
href="http://eprints.foobar.ac.uk/archive/00000923/"><img ... /></a>
</td></tr>
<tr><td>Eating Food</td><td>Herring, Walter and Chips, Bob</td><td>
2000</td><td><a href="http://eprints.foobar.ac.uk/archive/00000445/">
<img ... /></a></td></tr>
</code>
===A "CV" page - a list of all of Alices records===
This is where the authors and editors field having an ID comes in handy.

Say we use local username to identify people in the "Person ID" fields, we can now set up a view:

<code>
{ id=>"by_person", allow_null=>0, fields=>"authors.id/editors.id",
order=>"-year/title", noindex=>1, include=>1 }
</code>
This will generate both .html pages and .include pages. An member of your organisation can get a list of their records either by linking to <tt>/views/by_person/alice.html</tt> (where alice is their username) or by snarfing the URL <tt>/views/by_person/alice.include</tt> into his own homepage.

==HOW TO: Fields==
===Add a new Field
This convers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but invloves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

; Add the Field to ArchiveMetafieldConfig.pm : Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)

<code>
{ name => "local", type => "set", input_rows => 1,
options => [ "yes", "no", "partial" ] }
</code>
input_rows being set to one will make it appear as a pull-down menu.
; Add the Field to metadata-types.xml : If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in metadata-types.xml (this can be changed on a live system without any serious consequencies).

<code>
<field name="local" required="yes" />
</code>
; Add the Field Information to the Archive Phrase File(s) : Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language).

<code>
<ep:phrase ref="eprint_fieldname_local">Produced Locally</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_local">Please indicate if this item was
produces in the foo organisation, or not.
<ep:phrase ref="eprint_fieldopt_local_yes">produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_no">not produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_partial">only partially produced
locally</ep:phrase>
</code>

====Other things you may wish to change after adding a new field====
; Add it to the citations file : This is optional, only do this if you want it to appear in the citated forms.
In our example case we only want this to appear when citing technical reports, so we change that entry to:

<code>
<ep:citation type="eprint_techreport"><ep:linkhere>&authors; <ep:ifset name="year">(&year;)
</ep:ifset>&title;. Technical Report<ep:ifset name="reportno">
&reportno;</ep:ifset><ep:ifset name="department">, &department;
</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>.
&local;.</ep:linkhere></ep:citation>
</code>
All we've done is add <tt>&local;.</tt> to the end. It's not inside <tt> <ep:ifset name="local"> </tt> as it is a required field and will (should) always be set.
; Add it to the the Abstract (or View-User) page. : This is also optional. If you want it to appear on the web page for this item then edit ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.
In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...
Single language example:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
# don't need to "my $p" as it's done earlier.
$p = $session->make_element( "p" );
$p->appendChild( $session->make_text( "This item was " ) );
$p->appendChild( $eprint->render_value( "local" ) );
$p->appendChild( $session->make_text( "." ) );

# Append our new paragraph to the page.
$page->appendChild( $p );
}
</code>
Multiple-language example:
If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<code>
<ep:phrase ref="page:itemnotlocal">This item was <pin ref="status" />.</ep:phrase>
</code>
And to the ArchiveRenderConfig.pm file:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
my $localmsg = $session->html_phrase(
"page:itemnotlocal",
status=>$eprint->render_value( "local" ) );
$page->appendChild( $localmsg );
}
</code>
You may prefer to use this method even if you are only using a single language.
; Add extra Validation Routines : If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm
; Add it to the OAI metadata (eprints only) : If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.
; Add a browse view (eprints only) : If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.

===HOW TO: Remove a Field===
The quick answer is to say "the opposite of adding one".

; Remove the Field to metadata-types.xml : Removing it from here will mean that nobody can enter values for that field. Which is possibly enough, and means you can put it back later.
; Remove the Field to ArchiveMetafieldConfig.pm : This will remove it from the database ( and require a rebuild as with adding a field ).
; Remove it from the phrase file(s) : This is optional, unused phrases are just ignored.
; Remove it from the citations file : If it's used there.
; Remove it from the the Abstract (or View-User) page. : If it's used there.
; Remove extra Validation Routines : In the unlikely event you added some validation which looks at this field.
; Remove it from the OAI metadata (eprints only) : If it's being used. Fields used to generate the default dublincore are: title, authors, subjects, abstract, year and month. It also uses "type" which is a system field so you can't remove it!
; Remove it from browse views (eprints only) : If it's used there.

==HOW TO: EPrint types==
===Add a new eprint type===
Add the eprint type to '''metadata-types.xml'''. Some fields should probably be "required".

Add the name of the type to the phrase file.

Add a citation for this type to the citations file.

===Remove an eprint type===
Remove it from metadata-types.xml

You can remove it from the phrase file & citations but it won't hurt to leave it there.

==HOW TO: Add a new document type==
Add it to '''metadata-types.xml'''. This does not need any fields.

Add the name of the document type to the phrase file.

Add a citation for this document to the citations file.

If you want this to be one of the must-have-one-of document types then add it's id to the list in ArchiveConfig.pm

If you want to do something "clever" on the abstract page then edit the ArchiveRenderConfig.pm file. If you don't then it will use the citiation you created to render it in the list, as with PDF, HTML etc.

==HOW TO: Add a Discussion Forum for Each EPrint==
The UK Open University (open.ac.uk) have set up a service which allows you to create a discussion for every EPrint in your archive.

The really easy way to do this is to use their discussion server. If you want to run your own d3e server the software is available from http://d3e.sourceforge.net/

===Using d3eprints.open.ac.uk===
Just add the following code to the ArchiveRenderConfig.pm file just before the <tt>if( $has_multiple_versions )</tt> bit.

Please note that this code is not internationalised.

<code>
#####################################
# Begin D3Eprints links

my $ol = $session->make_element( "ol" );
my $li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/disc.php?url=".$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"View public discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/private/disc.php?url=".
$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"Create private discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$table->appendChild( _render_row(
$session,
$session->make_text( "D3Eprints discussion" ),
$ol ) );

# End of D3Eprints links
#####################################
</code>
==HOW TO: Website Integration==
===Make the latest additions to your archive appear on your main website===
The contents of the "latest" page - /perl/latest - can be included via a cron tab using wget and a server side include or using something like PHP's command to do:

<code>
readfile( "http://eprints.foo.org/perl/latest?mainonly=yes" );
</code>
The "mainonly=yes" flag is a hack which supresses the template of any eprints page in the /perl/ area so that it can be included, but it is most useful for "latest".

WARNING: If you have a script which imports 1000 records in one night then latest isn't currently bright enough to truncate the list so your homepage could get kinda messy.

===RSS into HTML===
If you want to turn any search into a dynamically generated list of references with a link back to the EPrints page, then use this. This solution uses PHP. So, you will need PHP enabled on the server.

'''Dependency:''' This code depends on [http://magpierss.sourceforge.net/ MagpieRSS].

'''Original Context:''' It was developed for use in a [http://www.terminalfour.com/ Terminal4 'SiteManager'] template, but can be used with almost no modification.

The code implements local caching of the generated HTML in a text file which is never more than an hour old, unless there is a problem with the server whereupon the last good cached version is used.

<code>
require_once('D:/website/[path to]/magpierss/rss_fetch.inc');
//set some variables here:
$anchor = '<t4 type="meta" meta="html_anchor" />';
# All items in Terminal4's cms have an anchor - we like break it apart to get the Unique id, to name the cache file.
$TTL = 3600;
# Time to live - one hour only.
$feed = '<t4 type="content" name="RSS_Feed_URL" output="normal" modifiers="" />';
$uniqueID = explode("\"", $anchor);
$filename = "./" . str_replace('.', '-', $uniqueID[1]) . ".txt";
#filename of cache - generated from unique id in T4 content management system.
$max_items = <t4 type="content" name="MaxNumberToShow" output="normal" modifiers="" />;
# $max_items = 30; // this is set in EPrints as well, will not exceed Eprints' own internal limit.
$with_summaries = '<t4 type="content" name="ShowSummary" output="normal" modifiers="" />'; # could be 'yes' or 'no'
$age = 0;
if(file_exists($filename)){
$age = time() - filemtime($filename);
}else{
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
$age = $TTL;
}

function getFromCache($f){
$fh = fopen($f, "r");
$size = filesize($f);
$data = fread($fh, $size);
print $data;
fclose($fh);
}

if($age >= $TTL){
if($rss = fetch_rss($feed)){
$items = array_slice($rss->items, 0);
$find = array("/^\.?/");
$replace = array(" ");
$news_feed = "<ul class=\"rss_list\">\n";
foreach ($items as $item ){
if($count < $max_items){
$news_feed .= "\t<li class=\"rss_item\">\n";
$news_feed .= "\t\t<a href=\"" . $item['link'] . "\" target=\"_blank\">";
$news_feed .= $item['title'] . "</a>\n\t\t \n";
if($with_summaries == 'yes'){
$news_feed .= "\t\t\n\t\t\t";
$news_feed .= str_replace(($item['title'] . "."), "", htmlentities($item['summary'])) . " \n\t\t\n";
}
$news_feed .= "\t\t \n\t</li>\n";
$count += 1;
}
}
$news_feed .= "</ul>\n\n";
echo $news_feed;
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
}else{
getFromCache($filename);
}
}else{
getFromCache($filename);
}
# David Kane, Waterford Institute of Technology
</code>

==HOW TO: Add full text searching==
EPrints does not support this natively but there are several options.

===htdig, or similar software===
There is plenty of software which will provide a full text search of a website. To add non-eprints cgi scripts to your site create a directory in the cgi dir:

<code>
mkdir /opt/eprints2/cgi/local
</code>
and place your scripts in there, they will have URLs under <tt>http://yoursite.com/perl/</tt>

===Using an external search engine===
This is very easy, but will only index public documents. Any search engine will work, but Google is a good choice. Google provide a site-search service which allows you to register with them and then have a form which searches your site using google and adds your logo and colourscheme to the results.

A really easy solution is to just make a form which links to our "google_site" script which just adds "site:yoursite.com" to the google request to limit the search results. The HTML for this would be something like:

<code>
<form action="/perl/google_site">
Use Google to search this site:
<input name="q" value="" />
<input type="submit" name="go" value="Search" />
</form>
</code>

For other search engines; see their documentation for how to make a form to search only your site.

==HOW TO: Make the referencetext field link to the items referenced==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Make the password controlled parts of the site use HTTPS==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Customise the way the the search results are formatted==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Reset your EPrints admin password [3.3]==

To directly reset your password, log into phpMyAdmin and execute the following mySQL statement:

UPDATE user SET password = encrypt('newpassword') WHERE userid = 1;
This will effectively reset the EPrint admin password for user 1. Note that you can use this to reset the password of any user, although this is typically unnecessary as you should be able to simply log in as admin user (user 1), under which you have the ability to reset any user's password.

How to

2011-12-10T11:25:52Z

Denics@free.fr: /* Using an external search engine */

[[Category:Howto]]
==HOW TO: Set up a Complex Custom View==
Simple instructions are in the ArchiveConfig.pm section.

Example situation: On my main website www.foobars.ac.uk I have a page per research project, of which we have hundreds. Each project has a short unique id code, eg. "manticore". I have a field in my eprints archive (eprints.foobars.ac.uk) which is configured:

<code>
{ name=>"projectcodes", type=>"text", multiple=>1 }
</code>
I add the following browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title" }
</code>
This will generate a page http://eprints.foobars.ac.uk/views/by_project/manticore.html with a list of all papers in that project, we can link to that URL!

===Making the Field link to the Browse Page===
If you want a subject to link the subject browse page of that value, add the '''browse_link''' property to the field (and regenerate the abstracts if you want).

If you remove the browse view you should remove the browse_link or it will be a broken link.

Values rendered inside citations which are used to link to the main record will not link into the browse view for obvious reasons.

===Including a view in another page===
If you change that to:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1 }
</code>
This will generate a view which is NOT listed on the /view/ page and it will not skip making the .html file and make a .include file per value. This will only contain the "count" of items and the XHTML of their citations. This can be used as part of a page on the http://www.foobaars.ac.uk/ site; either by using php and capturing it on-the-fly using <tt>readfile</tt> or scripting it with perl or NFS exporting the filesystem onto the main server (or just doing it all on one computer) and using server side includes to place it in a page.

===Customising the way each item is cited===
I want to list the project papers in a strict format in a table with 4 columns: title, author(s), year and an icon which links to the document abstract page...

I add some ''more'' options to the browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1,
nocount=>1, citation=>"project_table" }
</code>
Now I add a new citation to the citations config file:

<code>
<ep:citation type="project_table"><tr><td>&title;</td><td>&authors;</td>
<td>&year;</td><td><ep:linkhere><img
src="http://www.foobars.ac.uk/images/paperlink.png" alt="view" width="32"
height="64" border="0" /></ep:linkhere></td></tr></ep:citation>
</code>
That should generate for the manticore project, in the ".include" file (I've cut the contents of the "img" tag for readability:

<code>
<tr><td>Making Stuff</td><td>Guy, A.</td><td>2001</td><td><a
href="http://eprints.foobar.ac.uk/archive/00000923/"><img ... /></a>
</td></tr>
<tr><td>Eating Food</td><td>Herring, Walter and Chips, Bob</td><td>
2000</td><td><a href="http://eprints.foobar.ac.uk/archive/00000445/">
<img ... /></a></td></tr>
</code>
===A "CV" page - a list of all of Alices records===
This is where the authors and editors field having an ID comes in handy.

Say we use local username to identify people in the "Person ID" fields, we can now set up a view:

<code>
{ id=>"by_person", allow_null=>0, fields=>"authors.id/editors.id",
order=>"-year/title", noindex=>1, include=>1 }
</code>
This will generate both .html pages and .include pages. An member of your organisation can get a list of their records either by linking to <tt>/views/by_person/alice.html</tt> (where alice is their username) or by snarfing the URL <tt>/views/by_person/alice.include</tt> into his own homepage.

==HOW TO: Fields==
===Add a new Field
This convers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but invloves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

; Add the Field to ArchiveMetafieldConfig.pm : Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)

<code>
{ name => "local", type => "set", input_rows => 1,
options => [ "yes", "no", "partial" ] }
</code>
input_rows being set to one will make it appear as a pull-down menu.
; Add the Field to metadata-types.xml : If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in metadata-types.xml (this can be changed on a live system without any serious consequencies).

<code>
<field name="local" required="yes" />
</code>
; Add the Field Information to the Archive Phrase File(s) : Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language).

<code>
<ep:phrase ref="eprint_fieldname_local">Produced Locally</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_local">Please indicate if this item was
produces in the foo organisation, or not.
<ep:phrase ref="eprint_fieldopt_local_yes">produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_no">not produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_partial">only partially produced
locally</ep:phrase>
</code>

====Other things you may wish to change after adding a new field====
; Add it to the citations file : This is optional, only do this if you want it to appear in the citated forms.
In our example case we only want this to appear when citing technical reports, so we change that entry to:

<code>
<ep:citation type="eprint_techreport"><ep:linkhere>&authors; <ep:ifset name="year">(&year;)
</ep:ifset>&title;. Technical Report<ep:ifset name="reportno">
&reportno;</ep:ifset><ep:ifset name="department">, &department;
</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>.
&local;.</ep:linkhere></ep:citation>
</code>
All we've done is add <tt>&local;.</tt> to the end. It's not inside <tt> <ep:ifset name="local"> </tt> as it is a required field and will (should) always be set.
; Add it to the the Abstract (or View-User) page. : This is also optional. If you want it to appear on the web page for this item then edit ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.
In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...
Single language example:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
# don't need to "my $p" as it's done earlier.
$p = $session->make_element( "p" );
$p->appendChild( $session->make_text( "This item was " ) );
$p->appendChild( $eprint->render_value( "local" ) );
$p->appendChild( $session->make_text( "." ) );

# Append our new paragraph to the page.
$page->appendChild( $p );
}
</code>
Multiple-language example:
If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<code>
<ep:phrase ref="page:itemnotlocal">This item was <pin ref="status" />.</ep:phrase>
</code>
And to the ArchiveRenderConfig.pm file:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
my $localmsg = $session->html_phrase(
"page:itemnotlocal",
status=>$eprint->render_value( "local" ) );
$page->appendChild( $localmsg );
}
</code>
You may prefer to use this method even if you are only using a single language.
; Add extra Validation Routines : If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm
; Add it to the OAI metadata (eprints only) : If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.
; Add a browse view (eprints only) : If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.

===HOW TO: Remove a Field===
The quick answer is to say "the opposite of adding one".

; Remove the Field to metadata-types.xml : Removing it from here will mean that nobody can enter values for that field. Which is possibly enough, and means you can put it back later.
; Remove the Field to ArchiveMetafieldConfig.pm : This will remove it from the database ( and require a rebuild as with adding a field ).
; Remove it from the phrase file(s) : This is optional, unused phrases are just ignored.
; Remove it from the citations file : If it's used there.
; Remove it from the the Abstract (or View-User) page. : If it's used there.
; Remove extra Validation Routines : In the unlikely event you added some validation which looks at this field.
; Remove it from the OAI metadata (eprints only) : If it's being used. Fields used to generate the default dublincore are: title, authors, subjects, abstract, year and month. It also uses "type" which is a system field so you can't remove it!
; Remove it from browse views (eprints only) : If it's used there.

==HOW TO: EPrint types==
===Add a new eprint type===
Add the eprint type to '''metadata-types.xml'''. Some fields should probably be "required".

Add the name of the type to the phrase file.

Add a citation for this type to the citations file.

===Remove an eprint type===
Remove it from metadata-types.xml

You can remove it from the phrase file & citations but it won't hurt to leave it there.

==HOW TO: Add a new document type==
Add it to '''metadata-types.xml'''. This does not need any fields.

Add the name of the document type to the phrase file.

Add a citation for this document to the citations file.

If you want this to be one of the must-have-one-of document types then add it's id to the list in ArchiveConfig.pm

If you want to do something "clever" on the abstract page then edit the ArchiveRenderConfig.pm file. If you don't then it will use the citiation you created to render it in the list, as with PDF, HTML etc.

==HOW TO: Add a Discussion Forum for Each EPrint==
The UK Open University (open.ac.uk) have set up a service which allows you to create a discussion for every EPrint in your archive.

The really easy way to do this is to use their discussion server. If you want to run your own d3e server the software is available from http://d3e.sourceforge.net/

===Using d3eprints.open.ac.uk===
Just add the following code to the ArchiveRenderConfig.pm file just before the <tt>if( $has_multiple_versions )</tt> bit.

Please note that this code is not internationalised.

<code>
#####################################
# Begin D3Eprints links

my $ol = $session->make_element( "ol" );
my $li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/disc.php?url=".$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"View public discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/private/disc.php?url=".
$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"Create private discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$table->appendChild( _render_row(
$session,
$session->make_text( "D3Eprints discussion" ),
$ol ) );

# End of D3Eprints links
#####################################
</code>
==HOW TO: Website Integration==
===Make the latest additions to your archive appear on your main website===
The contents of the "latest" page - /perl/latest - can be included via a cron tab using wget and a server side include or using something like PHP's command to do:

<code>
readfile( "http://eprints.foo.org/perl/latest?mainonly=yes" );
</code>
The "mainonly=yes" flag is a hack which supresses the template of any eprints page in the /perl/ area so that it can be included, but it is most useful for "latest".

WARNING: If you have a script which imports 1000 records in one night then latest isn't currently bright enough to truncate the list so your homepage could get kinda messy.

===RSS into HTML===
If you want to turn any search into a dynamically generated list of references with a link back to the EPrints page, then use this. This solution uses PHP. So, you will need PHP enabled on the server.

'''Dependency:''' This code depends on [http://magpierss.sourceforge.net/ MagpieRSS].

'''Original Context:''' It was developed for use in a [http://www.terminalfour.com/ Terminal4 'SiteManager'] template, but can be used with almost no modification.

The code implements local caching of the generated HTML in a text file which is never more than an hour old, unless there is a problem with the server whereupon the last good cached version is used.

<code>
require_once('D:/website/[path to]/magpierss/rss_fetch.inc');
//set some variables here:
$anchor = '<t4 type="meta" meta="html_anchor" />';
# All items in Terminal4's cms have an anchor - we like break it apart to get the Unique id, to name the cache file.
$TTL = 3600;
# Time to live - one hour only.
$feed = '<t4 type="content" name="RSS_Feed_URL" output="normal" modifiers="" />';
$uniqueID = explode("\"", $anchor);
$filename = "./" . str_replace('.', '-', $uniqueID[1]) . ".txt";
#filename of cache - generated from unique id in T4 content management system.
$max_items = <t4 type="content" name="MaxNumberToShow" output="normal" modifiers="" />;
# $max_items = 30; // this is set in EPrints as well, will not exceed Eprints' own internal limit.
$with_summaries = '<t4 type="content" name="ShowSummary" output="normal" modifiers="" />'; # could be 'yes' or 'no'
$age = 0;
if(file_exists($filename)){
$age = time() - filemtime($filename);
}else{
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
$age = $TTL;
}

function getFromCache($f){
$fh = fopen($f, "r");
$size = filesize($f);
$data = fread($fh, $size);
print $data;
fclose($fh);
}

if($age >= $TTL){
if($rss = fetch_rss($feed)){
$items = array_slice($rss->items, 0);
$find = array("/^\.?/");
$replace = array(" ");
$news_feed = "<ul class=\"rss_list\">\n";
foreach ($items as $item ){
if($count < $max_items){
$news_feed .= "\t<li class=\"rss_item\">\n";
$news_feed .= "\t\t<a href=\"" . $item['link'] . "\" target=\"_blank\">";
$news_feed .= $item['title'] . "</a>\n\t\t \n";
if($with_summaries == 'yes'){
$news_feed .= "\t\t\n\t\t\t";
$news_feed .= str_replace(($item['title'] . "."), "", htmlentities($item['summary'])) . " \n\t\t\n";
}
$news_feed .= "\t\t \n\t</li>\n";
$count += 1;
}
}
$news_feed .= "</ul>\n\n";
echo $news_feed;
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
}else{
getFromCache($filename);
}
}else{
getFromCache($filename);
}
# David Kane, Waterford Institute of Technology
</code>

==HOW TO: Add full text searching==
EPrints does not support this natively but there are several options.

===htdig, or similar software===
There is plenty of software which will provide a full text search of a website. To add non-eprints cgi scripts to your site create a directory in the cgi dir:

<code>
mkdir /opt/eprints2/cgi/local
</code>
and place your scripts in there, they will have URLs under <tt>http://yoursite.com/perl/</tt>

===Using an external search engine===
This is very easy, but will only index public documents. Any search engine will work, but Google is a good choice. Google provide a site-search service which allows you to register with them and then have a form which searches your site using google and adds your logo and colourscheme to the results.

A really easy solution is to just make a form which links to our "google_site" script which just adds "site:yoursite.com" to the google request to limit the search results. The HTML for this would be something like:

<code>
<form action="/perl/google_site">
Use Google to search this site:
<input name="q" value="" />
<input type="submit" name="go" value="Search" />
</form>
</code>

For other search engines; see their documentation for how to make a form to search only your site.

==HOW TO: Make the referencetext field link to the items referenced==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Make the password controlled parts of the site use HTTPS==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Customise the way the the search results are formatted==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Reset your EPrints admin password [3.3]==

To directly reset your password, log into phpMyAdmin and execute the following mySQL statement:

UPDATE user SET password = encrypt('newpassword') WHERE userid = 1;
This will effectively reset the EPrint admin password for user 1. Note that you can use this to reset the password of any user, although this is typically unnecessary as you should be able to simply log in as admin user (user 1), under which you have the ability to reset any user's password.

How to

2011-12-10T11:25:08Z

Denics@free.fr:

[[Category:Howto]]
==HOW TO: Set up a Complex Custom View==
Simple instructions are in the ArchiveConfig.pm section.

Example situation: On my main website www.foobars.ac.uk I have a page per research project, of which we have hundreds. Each project has a short unique id code, eg. "manticore". I have a field in my eprints archive (eprints.foobars.ac.uk) which is configured:

<code>
{ name=>"projectcodes", type=>"text", multiple=>1 }
</code>
I add the following browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title" }
</code>
This will generate a page http://eprints.foobars.ac.uk/views/by_project/manticore.html with a list of all papers in that project, we can link to that URL!

===Making the Field link to the Browse Page===
If you want a subject to link the subject browse page of that value, add the '''browse_link''' property to the field (and regenerate the abstracts if you want).

If you remove the browse view you should remove the browse_link or it will be a broken link.

Values rendered inside citations which are used to link to the main record will not link into the browse view for obvious reasons.

===Including a view in another page===
If you change that to:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1 }
</code>
This will generate a view which is NOT listed on the /view/ page and it will not skip making the .html file and make a .include file per value. This will only contain the "count" of items and the XHTML of their citations. This can be used as part of a page on the http://www.foobaars.ac.uk/ site; either by using php and capturing it on-the-fly using <tt>readfile</tt> or scripting it with perl or NFS exporting the filesystem onto the main server (or just doing it all on one computer) and using server side includes to place it in a page.

===Customising the way each item is cited===
I want to list the project papers in a strict format in a table with 4 columns: title, author(s), year and an icon which links to the document abstract page...

I add some ''more'' options to the browse view:

<code>
{ id=>"by_project", allow_null=>0, fields=>"projectcodes",
order=>"-year/title", noindex=>1, nolink=>1, nohtml=>1, include=>1,
nocount=>1, citation=>"project_table" }
</code>
Now I add a new citation to the citations config file:

<code>
<ep:citation type="project_table"><tr><td>&title;</td><td>&authors;</td>
<td>&year;</td><td><ep:linkhere><img
src="http://www.foobars.ac.uk/images/paperlink.png" alt="view" width="32"
height="64" border="0" /></ep:linkhere></td></tr></ep:citation>
</code>
That should generate for the manticore project, in the ".include" file (I've cut the contents of the "img" tag for readability:

<code>
<tr><td>Making Stuff</td><td>Guy, A.</td><td>2001</td><td><a
href="http://eprints.foobar.ac.uk/archive/00000923/"><img ... /></a>
</td></tr>
<tr><td>Eating Food</td><td>Herring, Walter and Chips, Bob</td><td>
2000</td><td><a href="http://eprints.foobar.ac.uk/archive/00000445/">
<img ... /></a></td></tr>
</code>
===A "CV" page - a list of all of Alices records===
This is where the authors and editors field having an ID comes in handy.

Say we use local username to identify people in the "Person ID" fields, we can now set up a view:

<code>
{ id=>"by_person", allow_null=>0, fields=>"authors.id/editors.id",
order=>"-year/title", noindex=>1, include=>1 }
</code>
This will generate both .html pages and .include pages. An member of your organisation can get a list of their records either by linking to <tt>/views/by_person/alice.html</tt> (where alice is their username) or by snarfing the URL <tt>/views/by_person/alice.include</tt> into his own homepage.

==HOW TO: Fields==
===Add a new Field
This convers adding a new field to a new system, not a live system. It is possible to add a new field to a live system but invloves SQL hacking.

In this example we add a new "set" field called "local" which will have 3 options "yes","no" and "partial" - this will indicate if the item in question was produced in our organisation or not.

; Add the Field to ArchiveMetafieldConfig.pm : Add the field to the appropriate part of ArchiveMetafieldConfig.pm (the "eprint" section in our example)

<code>
{ name => "local", type => "set", input_rows => 1,
options => [ "yes", "no", "partial" ] }
</code>
input_rows being set to one will make it appear as a pull-down menu.
; Add the Field to metadata-types.xml : If you want the user to be able to edit this field for any or all types of eprint/user then you need to add it to each appropriate type in metadata-types.xml (this can be changed on a live system without any serious consequencies).

<code>
<field name="local" required="yes" />
</code>
; Add the Field Information to the Archive Phrase File(s) : Normally we just need to add fieldname and fieldhelp, but this is an option field so we need to add names for each option. If we run the archive in more than one language then we add this to each phrase file (but in the appropriate language).

<code>
<ep:phrase ref="eprint_fieldname_local">Produced Locally</ep:phrase>
<ep:phrase ref="eprint_fieldhelp_local">Please indicate if this item was
produces in the foo organisation, or not.
<ep:phrase ref="eprint_fieldopt_local_yes">produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_no">not produced locally</ep:phrase>
<ep:phrase ref="eprint_fieldopt_local_partial">only partially produced
locally</ep:phrase>
</code>

====Other things you may wish to change after adding a new field====
; Add it to the citations file : This is optional, only do this if you want it to appear in the citated forms.
In our example case we only want this to appear when citing technical reports, so we change that entry to:

<code>
<ep:citation type="eprint_techreport"><ep:linkhere>&authors; <ep:ifset name="year">(&year;)
</ep:ifset>&title;. Technical Report<ep:ifset name="reportno">
&reportno;</ep:ifset><ep:ifset name="department">, &department;
</ep:ifset><ep:ifset name="institution">, &institution;</ep:ifset>.
&local;.</ep:linkhere></ep:citation>
</code>
All we've done is add <tt>&local;.</tt> to the end. It's not inside <tt> <ep:ifset name="local"> </tt> as it is a required field and will (should) always be set.
; Add it to the the Abstract (or View-User) page. : This is also optional. If you want it to appear on the web page for this item then edit ArchiveRenderConfig.pm and select the appropriate function, either eprint_render or user_render.
In our example we only want to mention items if an item was not produced locally. We'll add it below the documents and above the abstract...
Single language example:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
# don't need to "my $p" as it's done earlier.
$p = $session->make_element( "p" );
$p->appendChild( $session->make_text( "This item was " ) );
$p->appendChild( $eprint->render_value( "local" ) );
$p->appendChild( $session->make_text( "." ) );

# Append our new paragraph to the page.
$page->appendChild( $p );
}
</code>
Multiple-language example:
If you want to make it handle more than language then we'll need to use the archive phrase file - we would add something like this to each languages file:

<code>
<ep:phrase ref="page:itemnotlocal">This item was <pin ref="status" />.</ep:phrase>
</code>
And to the ArchiveRenderConfig.pm file:

<code>
if( $eprint->get_value( "local" ) ne "yes" )
{
my $localmsg = $session->html_phrase(
"page:itemnotlocal",
status=>$eprint->render_value( "local" ) );
$page->appendChild( $localmsg );
}
</code>
You may prefer to use this method even if you are only using a single language.
; Add extra Validation Routines : If you need to validate this field in a special way, add code into ArchiveValidateConfig.pm
; Add it to the OAI metadata (eprints only) : If this field can be rendered into Dublin Core (or other metadata formats you are using) then add it to the appropriate place in the ArchiveOAIConfig.pm file.
; Add a browse view (eprints only) : If you want to be able to browse this values items. See elsewhere in the docs for how to do this.

If you add a field you will need to run erase_archive and create_tables before you will see a change. EPrints will fail to run if you change the fields and do rebuild the tables.

===HOW TO: Remove a Field===
The quick answer is to say "the opposite of adding one".

; Remove the Field to metadata-types.xml : Removing it from here will mean that nobody can enter values for that field. Which is possibly enough, and means you can put it back later.
; Remove the Field to ArchiveMetafieldConfig.pm : This will remove it from the database ( and require a rebuild as with adding a field ).
; Remove it from the phrase file(s) : This is optional, unused phrases are just ignored.
; Remove it from the citations file : If it's used there.
; Remove it from the the Abstract (or View-User) page. : If it's used there.
; Remove extra Validation Routines : In the unlikely event you added some validation which looks at this field.
; Remove it from the OAI metadata (eprints only) : If it's being used. Fields used to generate the default dublincore are: title, authors, subjects, abstract, year and month. It also uses "type" which is a system field so you can't remove it!
; Remove it from browse views (eprints only) : If it's used there.

==HOW TO: EPrint types==
===Add a new eprint type===
Add the eprint type to '''metadata-types.xml'''. Some fields should probably be "required".

Add the name of the type to the phrase file.

Add a citation for this type to the citations file.

===Remove an eprint type===
Remove it from metadata-types.xml

You can remove it from the phrase file & citations but it won't hurt to leave it there.

==HOW TO: Add a new document type==
Add it to '''metadata-types.xml'''. This does not need any fields.

Add the name of the document type to the phrase file.

Add a citation for this document to the citations file.

If you want this to be one of the must-have-one-of document types then add it's id to the list in ArchiveConfig.pm

If you want to do something "clever" on the abstract page then edit the ArchiveRenderConfig.pm file. If you don't then it will use the citiation you created to render it in the list, as with PDF, HTML etc.

==HOW TO: Add a Discussion Forum for Each EPrint==
The UK Open University (open.ac.uk) have set up a service which allows you to create a discussion for every EPrint in your archive.

The really easy way to do this is to use their discussion server. If you want to run your own d3e server the software is available from http://d3e.sourceforge.net/

===Using d3eprints.open.ac.uk===
Just add the following code to the ArchiveRenderConfig.pm file just before the <tt>if( $has_multiple_versions )</tt> bit.

Please note that this code is not internationalised.

<code>
#####################################
# Begin D3Eprints links

my $ol = $session->make_element( "ol" );
my $li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/disc.php?url=".$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"View public discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$li = $session->make_element( "li" );
$a = $session->render_link(
EPrints::Utils::url_escape(
"http://d3eprints.open.ac.uk/private/disc.php?url=".
$eprint->get_url ),
"_top" );
$a->appendChild( $session->make_text(
"Create private discussion of this document" ) );
$li->appendChild( $a );
$ol->appendChild( $li );

$table->appendChild( _render_row(
$session,
$session->make_text( "D3Eprints discussion" ),
$ol ) );

# End of D3Eprints links
#####################################
</code>
==HOW TO: Website Integration==
===Make the latest additions to your archive appear on your main website===
The contents of the "latest" page - /perl/latest - can be included via a cron tab using wget and a server side include or using something like PHP's command to do:

<code>
readfile( "http://eprints.foo.org/perl/latest?mainonly=yes" );
</code>
The "mainonly=yes" flag is a hack which supresses the template of any eprints page in the /perl/ area so that it can be included, but it is most useful for "latest".

WARNING: If you have a script which imports 1000 records in one night then latest isn't currently bright enough to truncate the list so your homepage could get kinda messy.

===RSS into HTML===
If you want to turn any search into a dynamically generated list of references with a link back to the EPrints page, then use this. This solution uses PHP. So, you will need PHP enabled on the server.

'''Dependency:''' This code depends on [http://magpierss.sourceforge.net/ MagpieRSS].

'''Original Context:''' It was developed for use in a [http://www.terminalfour.com/ Terminal4 'SiteManager'] template, but can be used with almost no modification.

The code implements local caching of the generated HTML in a text file which is never more than an hour old, unless there is a problem with the server whereupon the last good cached version is used.

<code>
require_once('D:/website/[path to]/magpierss/rss_fetch.inc');
//set some variables here:
$anchor = '<t4 type="meta" meta="html_anchor" />';
# All items in Terminal4's cms have an anchor - we like break it apart to get the Unique id, to name the cache file.
$TTL = 3600;
# Time to live - one hour only.
$feed = '<t4 type="content" name="RSS_Feed_URL" output="normal" modifiers="" />';
$uniqueID = explode("\"", $anchor);
$filename = "./" . str_replace('.', '-', $uniqueID[1]) . ".txt";
#filename of cache - generated from unique id in T4 content management system.
$max_items = <t4 type="content" name="MaxNumberToShow" output="normal" modifiers="" />;
# $max_items = 30; // this is set in EPrints as well, will not exceed Eprints' own internal limit.
$with_summaries = '<t4 type="content" name="ShowSummary" output="normal" modifiers="" />'; # could be 'yes' or 'no'
$age = 0;
if(file_exists($filename)){
$age = time() - filemtime($filename);
}else{
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
$age = $TTL;
}

function getFromCache($f){
$fh = fopen($f, "r");
$size = filesize($f);
$data = fread($fh, $size);
print $data;
fclose($fh);
}

if($age >= $TTL){
if($rss = fetch_rss($feed)){
$items = array_slice($rss->items, 0);
$find = array("/^\.?/");
$replace = array(" ");
$news_feed = "<ul class=\"rss_list\">\n";
foreach ($items as $item ){
if($count < $max_items){
$news_feed .= "\t<li class=\"rss_item\">\n";
$news_feed .= "\t\t<a href=\"" . $item['link'] . "\" target=\"_blank\">";
$news_feed .= $item['title'] . "</a>\n\t\t \n";
if($with_summaries == 'yes'){
$news_feed .= "\t\t\n\t\t\t";
$news_feed .= str_replace(($item['title'] . "."), "", htmlentities($item['summary'])) . " \n\t\t\n";
}
$news_feed .= "\t\t \n\t</li>\n";
$count += 1;
}
}
$news_feed .= "</ul>\n\n";
echo $news_feed;
$fh = fopen($filename, "w");
fwrite($fh, $news_feed);
fclose($fh);
}else{
getFromCache($filename);
}
}else{
getFromCache($filename);
}
# David Kane, Waterford Institute of Technology
</code>

==HOW TO: Add full text searching==
EPrints does not support this natively but there are several options.

===htdig, or similar software===
There is plenty of software which will provide a full text search of a website. To add non-eprints cgi scripts to your site create a directory in the cgi dir:

<code>
mkdir /opt/eprints2/cgi/local
</code>
and place your scripts in there, they will have URLs under <tt>http://yoursite.com/perl/</tt>

===Using an external search engine===
This is very easy, but will only index public documents. Any search engine will work, but Google is a good choice. Google provide a site-search service which allows you to register with them and then have a form which searches your site using google and adds your logo and colourscheme to the results.

A really easy solution is to just make a form which links to our "google_site" script which just adds "site:yoursite.com" to the google request to limit the search results. The HTML for this would be something like:

<code>
<form action="/perl/google_site">
Use Google to search this site:
<input name="q" value="" />
<input type="submit" name="go" value="Search" />
</form>
</code>
For other search engines; see their documentation for how to make a form to search only your site.

==HOW TO: Make the referencetext field link to the items referenced==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Make the password controlled parts of the site use HTTPS==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Customise the way the the search results are formatted==
This should have been in the 2.2 docs but I didn't have time. Check the latest version of the documentation at software.eprints.org, if it's not there then bug me at support@eprints.org

==HOW TO: Reset your EPrints admin password [3.3]==

To directly reset your password, log into phpMyAdmin and execute the following mySQL statement:

UPDATE user SET password = encrypt('newpassword') WHERE userid = 1;
This will effectively reset the EPrint admin password for user 1. Note that you can use this to reset the password of any user, although this is typically unnecessary as you should be able to simply log in as admin user (user 1), under which you have the ability to reset any user's password.

Files/OAI Harvester for EPrints 3.2+

2011-07-06T09:38:21Z

Denics@free.fr: /* OAI Harvester for EPrints 3.2+ */

Keeps your repository in-sync with another repository via OAI-PMH.

Note that these modules contain only the abstract classes, you will need to write your own module which translate whatever XML format you're harvesting to EPrints data structure. An example is provided under <code>cfg/plugins/EPrints/Plugin/Import/OAIPMH/Stub.pm.stub</code>.

=== Install ===
* As ''root'' user:
<code>
cpan HTTP::OAI
</code>
* As ''eprints'' user:
<code>
cp -rf bin/ cfg/ ./archives/ARCHIVEID/
</code>

check the perl declaration in file ''./archives/ARCHIVEID/bin/oai/harvest'' and change it accordingly

<code>
./bin/epadmin update_database_structure ARCHIVEID
</code>
* As ''root'' user:

Restart Web Server.

=== Usage ===
* Create a module which transforms XML as explained in the intro of this file. Say you created a DC importer called OAIPMH::OAI_DC.
* Edit the configuration file ''cfg/cfg.d/oai_harvester.pl'' and create a new configuration for the service you want to harvest (an example is provided in that file) eg:
$c->{oai_harvester}->{service_name} = {
url => 'http://oaiserver.com/oai',
set => 'that_set'
default_values => sub {
my( $session, $epdata, $header ) = @_;
$epdata->{userid} = 1234; # user '1234' will own all imported publications
$epdata->{eprint_status} = 'archive'; # imported publications will go straight to the live archive
# etc...
},
};
* Run (or setup in cron) bin/oai/harvest periodically:
<code>
bin/oai/harvest ARCHIVEID --plugin=OAIPMH::OAI_DC --conf=service_name
</code>

That's it!

Files/OAI Harvester for EPrints 3.2+

2011-07-06T09:38:03Z

Denics@free.fr: Created page with '== OAI Harvester for EPrints 3.2+ == Keeps your repository in-sync with another repository via OAI-PMH. Note that these modules contain only the abstract classes, you will need …'

== OAI Harvester for EPrints 3.2+ ==
Keeps your repository in-sync with another repository via OAI-PMH.

Note that these modules contain only the abstract classes, you will need to write your own module which translate whatever XML format you're harvesting to EPrints data structure. An example is provided under <code>cfg/plugins/EPrints/Plugin/Import/OAIPMH/Stub.pm.stub</code>.

=== Install ===
* As ''root'' user:
<code>
cpan HTTP::OAI
</code>
* As ''eprints'' user:
<code>
cp -rf bin/ cfg/ ./archives/ARCHIVEID/
</code>

check the perl declaration in file ''./archives/ARCHIVEID/bin/oai/harvest'' and change it accordingly

<code>
./bin/epadmin update_database_structure ARCHIVEID
</code>
* As ''root'' user:

Restart Web Server.

=== Usage ===
* Create a module which transforms XML as explained in the intro of this file. Say you created a DC importer called OAIPMH::OAI_DC.
* Edit the configuration file ''cfg/cfg.d/oai_harvester.pl'' and create a new configuration for the service you want to harvest (an example is provided in that file) eg:
$c->{oai_harvester}->{service_name} = {
url => 'http://oaiserver.com/oai',
set => 'that_set'
default_values => sub {
my( $session, $epdata, $header ) = @_;
$epdata->{userid} = 1234; # user '1234' will own all imported publications
$epdata->{eprint_status} = 'archive'; # imported publications will go straight to the live archive
# etc...
},
};
* Run (or setup in cron) bin/oai/harvest periodically:
<code>
bin/oai/harvest ARCHIVEID --plugin=OAIPMH::OAI_DC --conf=service_name
</code>

That's it!