About Features Downloads Getting Started Documentation Events Support GitHub

Love VuFind®? Consider becoming a financial supporter. Your support helps build a better VuFind®!

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
administration:security

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
administration:security [2020/07/23 16:47] demiankatzadministration:security [2024/02/20 13:09] (current) – [Security] demiankatz
Line 1: Line 1:
-====== Security ======+====== Security for VuFind® Administrators ====== 
 + 
 +===== Unix Accounts and Permissions ===== 
 + 
 +Since VuFind® has a variety of command-line utilities for maintenance, it is a good idea to dedicate an account in your system to VuFind®-related work and to use that account exclusively for running VuFind® commands and [[administration:automation#using_cron|cron jobs]]. 
 + 
 +==== Creating a System Account for VuFind® ==== 
 + 
 +First, decide on a name for your VuFind user. For the example below, we will use "vufind" as the username. Having made this decision, you can create the account with: 
 + 
 +<code bash> 
 +sudo useradd -r -s /usr/sbin/nologin -U vufind 
 +</code> 
 + 
 +The -r switch designates this as a system account, the -s switch sets the login shell to prevent users from logging into the account, and the -U switch creates a group to match the username. 
 + 
 +==== Changing File Ownership ==== 
 + 
 +Once the account is created, you can change the ownership of your VuFind® files to belong to the new user. However, you need to be careful not to interfere with Apache-related permissions in the cache directory while making sure that the separate cache for command-line utilities is owned by the new user. The easiest way to do this, if you're modifying a working installation of VuFind®, is to follow these steps: 
 + 
 +1.) Look up the current owner of the Apache cache by doing a detailed listing of the cache directory: 
 + 
 +<code bash> 
 +ls -l $VUFIND_LOCAL_DIR/cache 
 +</code> 
 + 
 +The username is most likely ''apache'' (if you are using an RPM-based Linux flavor) or ''www-data'' (for Debian-based Linux flavors). Make note of it. 
 + 
 +2.) Change ownership of the entire VuFind® directory to your new service user, then change the cache back to the appropriate ownership, then adjust the command-line cache. This requires three commands, but you should run them in rapid sequence to avoid disruption to your system: 
 + 
 +<code bash> 
 +sudo chown -R vufind:vufind $VUFIND_HOME 
 +sudo chown -R apache:apache $VUFIND_LOCAL_DIR/cache 
 +sudo chown -R vufind:vufind $VUFIND_LOCAL_DIR/cache/cli 
 +</code> 
 + 
 +:!: Note that this example assumes an Apache user of "apache" but you should replace "apache" with the username you noted in step 1. 
 + 
 +==== Setting Up Cron Jobs ==== 
 + 
 +In most Unix-based systems, every user can potentially be configured to run its own cron jobs. Assuming that you have this configured correctly, you can simply switch to the user you wish to modify, and run the ''crontab -e'' command to edit the user's crontab. For example: 
 + 
 +<code bash> 
 +sudo su vufind -s /usr/bin/bash 
 +crontab -e 
 +</code> 
 + 
 +Note that in this example, we specify which shell to use when switching to the vufind user, since in the example above, we set a "nologin" shell as the default. We need to override that to avoid an error message about the account being unavailable. If you set up the user with a different default shell, you can skip this parameter (but the account may be less secure under certain circumstances).
  
 ===== Using SSL ===== ===== Using SSL =====
  
-If your VuFind system takes sensitive information as input (for example, if you use a shared authentication method and want to protect passwords from being sent in plain text), you may want to consider putting it behind SSL so that communications are encrypted.+If your VuFind® system takes sensitive information as input (for example, if you use a shared authentication method and want to protect passwords from being sent in plain text), you may want to consider putting it behind SSL so that communications are encrypted.
  
 SSL configuration is beyond the scope of this document, but a lot of helpful resources exist on the web.  For example, the [[http://tldp.org/HOWTO/SSL-RedHat-HOWTO.html|Building a Secure RedHat Apache Server HOWTO]] is a good starting point (and relevant beyond just RedHat). SSL configuration is beyond the scope of this document, but a lot of helpful resources exist on the web.  For example, the [[http://tldp.org/HOWTO/SSL-RedHat-HOWTO.html|Building a Secure RedHat Apache Server HOWTO]] is a good starting point (and relevant beyond just RedHat).
  
-Once you have SSL configured, if you want to force VuFind to always run behind SSL, you can add these lines above the other RewriteRules in your Apache configuration in httpd-vufind.conf to force a redirect of non-SSL traffic to SSL URLs:+Once you have SSL configured, if you want to force VuFind® to always run behind SSL, you can add these lines above the other RewriteRules in your Apache configuration in httpd-vufind.conf to force a redirect of non-SSL traffic to SSL URLs:
  
 <code> <code>
Line 15: Line 62:
 </code> </code>
  
-IMPORTANT: If you change VuFind to run under SSL, don't forget to adjust your base URL in [[configuration:files:config.ini]] accordingly.+IMPORTANT: If you change VuFind® to run under SSL, don't forget to adjust your base URL in [[configuration:files:config.ini]] accordingly.
  
 ===== Locking Down Solr ===== ===== Locking Down Solr =====
  
-To ensure that your data is secure, it is advised that you lock down the Solr server to only be accessible from your local webserver. The default port is 8983 in VuFind 7 and newer, 8080 in 6.x and earlier. This port should be locked down to eliminate security threats to your data. +To ensure that your data is secure, it is advised that you configure your firewall to lock down the Solr server to only be accessible from your local webserver. The default port is 8983 in VuFind® 7 and newer, 8080 in 6.x and earlier. This port should be locked down to eliminate security threats to your data. 
  
 +It is also strongly recommended that you use a dedicated user account to run Solr, to limit the Solr application's access to other parts of your system.
 +
 +Instructions for creating a dedicated Solr account and changing the Solr port number can be found below.
 +
 +==== Creating a Dedicated Solr User ====
 +
 +=== 1. Create the user account ===
 +
 +First, decide on a name for your Solr user. If you have already [[#creating_a_system_account_for_vufind|created a system account for VuFind®]] as described above, you might decide that you can use this user to run Solr as well as run VuFind®-specific scripts. In that case, no additional configuration should be necessary.
 +
 +If you want to fully isolate Solr by creating a user named solr, just repeat the useradd command described under [[#creating_a_system_account_for_vufind|creating a system account for VuFind®]], replacing the "vufind" name in the example with "solr" (or whatever else you choose to use). The examples in the following steps assume you chose "solr".
 +
 +=== 2. Change the ownership of the Solr directories ===
 +
 +If you are going to run Solr using the new user account, you need to make sure that the Solr files have appropriate ownership:
 +
 +<code bash>
 +sudo chown -R solr:solr $VUFIND_HOME/solr
 +</code>
 +
 +=== 3. Use the new user account to run Solr ===
 +
 +If you are manually starting Solr, you can switch to the new account to start the system:
 +
 +<code bash>
 +sudo su solr -s /usr/bin/bash
 +cd $VUFIND_HOME
 +./solr.sh start
 +</code>
 +
 +See the note under [[administration:security#setting_up_cron_jobs|setting up cron jobs]] above for an explanation of the -s switch on su.
 +
 +If you are automatically starting Solr, make sure that your configuration includes the appropriate username. See the [[/administration:starting_and_stopping_solr|Starting and Stopping Solr]] page for more details.
  
 ==== Changing the Solr Port Number ==== ==== Changing the Solr Port Number ====
Line 26: Line 106:
 === 1. Reconfigure Solr === === 1. Reconfigure Solr ===
  
-If using VuFind 3.0 or newer, the Solr port number is controlled by the SOLR_PORT environment variable; just set this before [[administration:starting_and_stopping_solr|starting Solr]] (e.g. with "export SOLR_PORT=xxxx") and the server will run on the desired port.+If using VuFind® 3.0 or newer, the Solr port number is controlled by the SOLR_PORT environment variable; just set this before [[administration:starting_and_stopping_solr|starting Solr]] (e.g. with "export SOLR_PORT=xxxx") and the server will run on the desired port.
  
-If using VuFind 2.x or earlier, you can change the port number used by Solr by editing the file solr/jetty/etc/jetty.xml under your VuFind installation and changing the jetty.port SystemProperty.+If using VuFind® 2.x or earlier, you can change the port number used by Solr by editing the file solr/jetty/etc/jetty.xml under your VuFind® installation and changing the jetty.port SystemProperty.
  
-=== 2. Reconfigure VuFind ===+=== 2. Reconfigure VuFind® ===
  
 You will need to adjust a few configuration files to reflect the new port number you have chosen. You will need to adjust a few configuration files to reflect the new port number you have chosen.
Line 36: Line 116:
 == A. SolrMarc Import Configuration == == A. SolrMarc Import Configuration ==
  
-If you use SolrMarc to import MARC records, you must edit the solr.hosturl setting in the import/import.properties file (and also import/import_auth.properties, if you plan on importing authority records). Be sure to edit the versions in your [[configuration:local_settings_directory|local settings directory]] if using VuFind 2.x or newer.+If you use SolrMarc to import MARC records, you must edit the solr.hosturl setting in the import/import.properties file (and also import/import_auth.properties, if you plan on importing authority records). Be sure to edit the versions in your [[configuration:local_settings_directory|local settings directory]] if using VuFind® 2.x or newer.
  
 <code> <code>
Line 42: Line 122:
 </code> </code>
  
-== B. VuFind Configuration ==+== B. VuFind® Configuration ==
  
-To ensure that VuFind can perform Solr searches, edit the [Index] section of the [[configuration:files:config.ini]] file as appropriate:+To ensure that VuFind® can perform Solr searches, edit the [Index] section of the [[configuration:files:config.ini]] file as appropriate:
 <code> <code>
 [Index] [Index]
Line 59: Line 139:
 [[administration:starting_and_stopping_solr#restarting_solr_manually|Restart the Solr process]] so the changes can take effect. [[administration:starting_and_stopping_solr#restarting_solr_manually|Restart the Solr process]] so the changes can take effect.
  
 +==== Allowing Access to the Solr Host ====
 +
 +Starting with Solr 9 (and thus affecting VuFind® releases 9.0 and later), Solr will only allow "localhost" connections by default. If you wish to access Solr from another server or workstation, you will need to choose one of these solutions:
 +
 +=== Option 1: Reconfigure SOLR_JETTY_HOST ===
 +
 +If you want to permanently allow Solr to accept connections using a hostname other than "localhost," you can set the SOLR_JETTY_HOST environment variable to control this behavior. If you set the variable to "0.0.0.0" it will accept connections using any name. If you set the variable to a specific hostname, then ONLY that hostname will be allowed (e.g. if you set SOLR_JETTY_HOST to "myserver.myuniversity.edu" then "localhost" connections will stop working, and all Solr traffic must use the hostname). See [[https://solr.apache.org/guide/solr/latest/deployment-guide/taking-solr-to-production.html#security-considerations|Taking Solr to Production]] for more details.
 +
 +=== Option 2: Use SSH Tunneling ===
 +
 +If you only want to temporarily access Solr from another location, you can do so without loosening security by opening an SSH tunnel to expose the Solr port on another machine, effectively allowing "localhost" access remotely. SSH tunneling is available through the standard Unix ssh command line tool and through graphical clients like PuTTY. It is beyond the scope of this documentation to explain SSH tunneling in detail, but if you use a search engine to look for "SSH tunnel" and your client or operating system of choice, you should be able to find a wealth of tutorials on the subject.
 ===== Locking Down the Admin Panel ===== ===== Locking Down the Admin Panel =====
  
-VuFind includes an administration module (accessible through <nowiki>http://your_vufind_url/Admin/Home</nowiki>).  This is useful, but it should not be exposed to the general public. The access.AdminModule [[configuration:permission_options|permission]] can be used to grant granular control to the module. The entire module can still be disabled using the System/admin_enabled setting if desired.+VuFind® includes an administration module (accessible through <nowiki>http://your_vufind_url/Admin/Home</nowiki>).  This is useful, but it should not be exposed to the general public. The access.AdminModule [[configuration:permission_options|permission]] can be used to grant granular control to the module. The entire module can still be disabled using the System/admin_enabled setting if desired.
  
 ===== Proxies and IP Authentication ===== ===== Proxies and IP Authentication =====
  
-If you rely on IP authentication for setting VuFind permissions, and if your VuFind server is located behind a proxy on the network, you may have difficulty accurately identifying users. There are HTTP headers, including X-Real-IP and X-Forwarded-For, which can be used to identify users on the other side of a proxy, but they can be easily spoofed.+If you rely on IP authentication for setting VuFind® permissions, and if your VuFind® server is located behind a proxy on the network, you may have difficulty accurately identifying users. There are HTTP headers, including X-Real-IP and X-Forwarded-For, which can be used to identify users on the other side of a proxy, but they can be easily spoofed.
  
-Starting with VuFind 7.0.1, the config.ini [Proxysection contains an allow_forwarded_ips setting which can be used to control how VuFind identifies IP addresses based on HTTP headers. The full details on configuration options can be found in the comments in that file.+It may be possible to work around this problem through careful configuration of your proxy (e.gby making it filter out these headers from incoming requests) and use of the [[https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html|mod_remoteip]] Apache plugin. In essence, these HTTP headers must be treated as non-trusted content when they come from a client, just like any other data in a client request.
  
-By defaultall IP-forwarding headers are ignoredbut by turning on allow_forwarded_ips, you can tell VuFind which headers to trust, and how to handle multi-valued headers. You also have the option of extending/overriding the VuFind\Net\UserIpReader class if you need to apply more nuanced, institution-specific logic.+In case this approach is not possiblestarting with VuFind® 7.0.1the config.ini [Proxy] section contains allow_forwarded_ips and forwarded_ip_filter settings which can be used to control how VuFind® identifies IP addresses based on HTTP headers. The full details on configuration options can be found in the comments in that file.
  
-If you plan to use this feature, you should install one of the many available browser plugins for editing HTTP headers, and determine exactly how your proxy behaves when receiving falsified headers. (A quick way to do to this is to var_dump the $_SERVER superglobal in a PHP script that you can access through your proxy). Based on this information, you should be able to adjust the configuration of VuFind and/or your proxy to reduce the risk of spoofing.+By default, all IP-forwarding headers are ignored, but by turning on allow_forwarded_ips, you can tell VuFind® which headers to trust, and how to handle multi-valued headers. The forwarded_ip_filter setting can be used to filter own the addresses of known internal network devices. You also have the option of extending/overriding the VuFind®\Net\UserIpReader class if you need to apply more nuanced, institution-specific logic. 
 + 
 +If you plan to use this feature, you should install one of the many available browser plugins for editing HTTP headers, and determine exactly how your proxy behaves when receiving falsified headers. (A quick way to do to this is to var_dump the $_SERVER superglobal in a PHP script that you can access through your proxy). Based on this information, you should be able to adjust the configuration of VuFind® and/or your proxy to reduce the risk of spoofing.
  
 ===== Securing User Credentials ===== ===== Securing User Credentials =====
  
-VuFind stores some user information in its database.  Starting with VuFind 2.0RC1, you have the option to perform extra hashing/encryption to protect these credentials.  The settings are off by default in [[configuration:files:config.ini]], but they can be enabled through VuFind's auto-configuration pages.  Enabling security is highly recommended.+VuFind® stores some user information in its database.  Starting with VuFind® 2.0RC1, you have the option to perform extra hashing/encryption to protect these credentials.  The settings are off by default in [[configuration:files:config.ini]], but they can be enabled through VuFind®'s auto-configuration pages.  Enabling security is highly recommended
 + 
 +VuFind® also supports configuration settings to enforce length and content restrictions on usernames and passwords. Review the settings in the [Authentication] section of [[configuration:files:config.ini]] for more details. It is recommended that you enforce complex passwords when possible, but depending on your authentication settings this may not be possible (e.g. if your login proxies your ILS, and your ILS does not support password restrictions) or may not be necessary (e.g. if you are using single sign-on, where passwords are managed entirely in a third-party system). 
 + 
 +When using some [[configuration:authentication]] options, you have the ability to pre-populate user ILS credentials in the database. In some scenarios, it is possible to configure ILS drivers to look up users based only on usernames or other "public knowledge" fields. In these cases, you should disable direct user login using the allowUserLogin setting in the [Catalog] section of [[configuration:files:config.ini]] to eliminate the possibility of users attempting to impersonate one another. This setting was introduced in VuFind® 9.0.
  
 ===== Using a Content Security Policy ===== ===== Using a Content Security Policy =====
  
-Starting with VuFind 7.0, you can configure a [[administration:security:content_security_policy|content security policy]] to protect against cross-site scripting and other vulnerabilities. See the [[administration:security:content_security_policy|content security policy]] page for more details.+Starting with VuFind® 7.0, you can configure a [[administration:security:content_security_policy|content security policy]] to protect against cross-site scripting and other vulnerabilities. See the [[administration:security:content_security_policy|content security policy]] page for more details
 + 
 +===== General Best Practices ===== 
 + 
 +==== Stay Up to Date ==== 
 + 
 +VuFind® generally puts out one major and one minor release each year, plus patch releases as necessary. Maintaining your VuFind® instance ensures that you receive the latest security fixes and that your instance remains compatible with the latest versions of all of its dependencies. 
 + 
 +You should also be sure to keep your dependencies up to date through necessary operating system patching and upgrading. Make sure that you are running VuFind® in combination with up-to-date and supported versions of Linux, Apache, PHP, etc. 
 + 
 +==== Don't Leave Autoconfiguration Turned On ==== 
 + 
 +It's necessary to put VuFind® into "autoconfiguration" mode via the "autoConfigure" setting of [[configuration:files:config.ini]] for initial installation and when performing upgrades. You should never turn this setting on at any other time, and you should remember to turn it off whenever you are done with it! 
 + 
 +On a related note, while it is sometimes necessary to give Apache ownership of your configuration files to allow it to write updates to disk during autoconfiguration, this ownership should only be granted during active maintenance of VuFind®, and ownership should be given to a different user at all other times.
 ---- struct data ---- ---- struct data ----
 +properties.Page Owner : 
 ---- ----
  
administration/security.1595522842.txt.gz · Last modified: 2020/07/23 16:47 by demiankatz