From 8a15f4893893e3c24054a5704749e3b823b31550 Mon Sep 17 00:00:00 2001 From: Robert Soulliere Date: Mon, 13 Sep 2010 14:52:18 -0400 Subject: [PATCH] Clean up files for samntic coding. Add index entries. --- 1.6/admin/AdminMisc.xml | 185 ++++++++++++----------- 1.6/admin/admin-intro.xml | 17 ++- 1.6/admin/requirements-configuration.xml | 161 ++++++++++---------- 3 files changed, 195 insertions(+), 168 deletions(-) diff --git a/1.6/admin/AdminMisc.xml b/1.6/admin/AdminMisc.xml index 3de62217ea..8811cf2835 100644 --- a/1.6/admin/AdminMisc.xml +++ b/1.6/admin/AdminMisc.xml @@ -5,95 +5,100 @@ Server Operations and Maintenance - This chapter deals with basic server operations such as starting and stopping Evergreen as well wall security, backing up and troubleshooting Evergreen. + This chapter deals with basic server operations such as starting and stopping Evergreen as well wall + security, backing up and troubleshooting Evergreen.
Starting, Stopping and Restarting - Occasionally, you may need to restart Evergreen. It is imperative that you understand the basic - commands to stop and start the Evergreen server. You can start and stop Evergreen from the command line of - the server using the osrf_ctl.sh script located in the + Occasionally, you may need to restart Evergreen. It is imperative that you understand the basic + commands to stop and start the Evergreen server. You can start and stop Evergreen from the command line of + the server using the osrf_ctl.sh script located in the openils/bin directory. - The osrf_ctl.sh script must be run as the opensrf user. - To view help on osrf_ctl.sh and get all of its options, - run: - osrf_ctl.sh -h + The osrf_ctl.sh command must be run as the opensrf user. + To view help on osrf_ctl.sh and get all of its options, run: + osrf_ctl.sh -h To start Evergreen, run: - osrf_ctl.sh -l -a start_all - The -l flag is used to indicate that Evergreen is configured to use localhost as - the host. If you have configured opensrf.xml to use your real hostname, do not use the -l flag. The -a + osrf_ctl.sh -l -a start_all + The flag is used to indicate that Evergreen is configured to use localhost as + the host. If you have configured opensrf.xml to use your real hostname, do not use the flag. The option is required and indicates the action of the command. In this case - start_all. + . - If you receive the error message bash: osrf_ctl.sh: - command not found, then your environment variable PATH does not include the - /openils/bin directory. - You can set it using the following command: - export PATH=$PATH:/openils/bin - If you receive the error message Can't locate OpenSRF/System.pm in @INC … BEGIN - failed–compilation aborted, then your environment variable PERL5LIB does not + If you receive the error message: osrf_ctl.sh: command not found, then your environment variable + PATHenvironment variablePATH does not include the + /openils/bin directory. You can set it using the following command: + export PATH=$PATH:/openils/bin + If you receive the error message Can't locate OpenSRF/System.pm in @INC … BEGIN + failed–compilation aborted, then your environment variable PERL5LIBenvironment + variablePERL5LIB does not include the /openils/lib/perl5 directory. You can set it using the following command: - export PERL5LIB=$PERL5LIB:/openils/lib/perl5 + export PERL5LIB=$PERL5LIB:/openils/lib/perl5 It is also possible to start a specific service. For example: - osrf_ctl.sh -l -a start_router - will only start the router service. + osrf_ctl.sh -l -a start_router + will only start the router service. If you decide to start each service individually, you need to start them in a specific order for Evergreen to start correctly. Run the commands in this exact order: - osrf_ctl.sh -l -a start_router - osrf_ctl.sh -l -a start_perl - osrf_ctl.sh -l -a start_c + osrf_ctl.sh -l -a start_router + osrf_ctl.sh -l -a start_perl + osrf_ctl.sh -l -a start_c - After starting or restarting Evergreen, it is also necessary to restart the Apache web server for the - OPAC to work correctly. - To stop Evergreen, run: - osrf_ctl.sh -l -a stop_all + After starting or restarting Evergreen, it is also necessary to restart the Apache web server + web serverApache for the OPAC to work correctly. + To stop Evergreen, run: + osrf_ctl.sh -l -a stop_all As with starting, you can choose to stop one service - To restart Evergreen, run: - osrf_ctl.sh -l -a restart_all + To restart Evergreen, run: + osrf_ctl.sh -l -a restart_all
Backing Up Backing up your system files and data is a critical task for server and database administrators. Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and - a a complete catastrophe. + a complete catastrophe. - Backing up the Evergreen Database - Most of the critical data for an Evergreen system – patrons, bibliographic records, holdings, - transactions, bills – is stored in the PostgreSQL database. You can therefore use normal PostgreSQL - backup procedures to backup this data. For example, the simplest method of backing up the Evergreen - database is to use the pg_dump command to create a live backup of the database without having to - interrupt any Evergreen services as follows: - # pg_dump -U [username] -h [hostname] -f [output-file] [database-name] - pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen + Backing up the <application>Evergreen</application> Databasedatabases + Most of the critical data for an Evergreen system – patrons, bibliographic records, holdings, + transactions, bills – is stored in the PostgreSQLdatabases + PostgreSQL database. You can therefore use normal + PostgreSQL backup procedures to backup this data. For example, the simplest method of backing up the Evergreen + database is to use the pg_dump command to create a live backup of the database without having to + interrupt any Evergreen services: + # pg_dump -U [username] -h [hostname] -f [output-file] [database-name] + pg_dump -U evergreen -h localhost -f evergreen_db.backup evergreen To restore the backed up database into a new database, create a new database using the - template0 database template and the UTF8 encoding, and run the psql command, specifying the new + template0 database template and the UTF8 encoding, and run the psql command, specifying the new database as your target: - createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen - psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen + createdb -T template0 -E UTF8 -U evergreen -h localhost new_evergreen + psql -U evergreen -h localhost -f evergreen_db.backup new_evergreen This method of backup is only suitable for small Evergreen instances. Larger sites - should consider implementing continuous archiving (also known as “log shipping”) to provide - more granular backups with lower system overhead. More information on backing up PostgreSQL - databases can be found in the official PostgreSQL documentation. + should consider implementing continuous archiving (also known as log shipping) to provide + more granular backups with lower system overhead. More information on backing up PostgreSQL + databases can be found in the official PostgreSQL documentation. Backing up Evergreen Files When you deploy Evergreen, you will probably customize many aspects of your system including - the system configuration files, Apache configuration files, OPAC and Staff Client. In order to + the system configuration files, Apache configuration files, OPAC and Staff Client. In order to protect your investment of time, you should carefully consider the best approach to backing up files. There are a number of ways of tackling this problem. You could create a script that regularly creates a time-stamped tarball of all of these files and copies it to a remote server - but that - would build up over time to hundreds of files. You could use rsync to ensure that the files of + would build up over time to hundreds of files. You could use rsync + rsync to ensure that the files of interest are regularly updated on a remote server - but then you would lose track of the changes to the files, should you make a change that introduces a problem down the road. - Perhaps one of the best options is to use a version control system like Bazaar, git, - Subversion, or CVS to regularly push updates of the files you care about to a repository on a + Perhaps one of the best options is to use a version control system like + BazaarVersion Control SystemSubversion, + gitVersion Control Systemgit + or SubversionVersion Control System + Subversion to regularly push updates of the files you care about to a repository on a remote server. This gives you the advantage of quickly being able to run through the history of the changes you made, with a commenting system that reminds you why each change was made, combined with remote storage of the pertinent files in case of disaster on site. In addition, your team can create @@ -104,39 +109,39 @@ Full System Backup A full system backup archives every file on the file system. Some basic methods require you - to shut down most system processes; other methods can use mirrored RAID setups or SAN storage to - take “snapshot” backups of your full system while the system continues to run. The subject of how + to shut down most system processes; other methods can use mirrored RAIDRAID setups or + SANSAN storage to + take snapshot backups of your full system while the system continues to run. The subject of how to implement full system backups is beyond the scope of this documentation.
Security As with an ILS and resource accessible from the world wide web careful consideration needs to be - given to the security of your Evergreen servers and database. While it is impossible to cover all aspects - of security, it is important to take several precautions when setting up production Evergreen site. + given to the security of your Evergreen servers and database. While it is impossible to cover all aspects + of security, it is important to take several precautions when setting up production Evergreen site. - Change the Evergreen Admin password and keep it secure. The - default Admin password is known by anyone who has installed Evergreen. It is not a secret + Change the Evergreen admin password and keep it secure. The + default admin password is known by anyone who has installed Evergreen. It is not a secret and needs to be changed by the Administrator. It should also only be shared by those who - need the highest level access to Evergreen. + need the highest level of access to your system. Create strong passwords using a combination of numerical and alphabetical characters - for all of the Administrative passwords used by Evergreen including the Evergreen - postgresql user, opensrf Linux account, and Admin evergreen users, and of course, any - superusers on your server. + for all of the Administrative passwords including the postgres and + opensrf users - Open ports in the firewall with Caution - It is necessary to open some ports to the - server such as port 80 for http and 443 for ssl, and it can be helpful to open ports for - remote access to the database or staff client. It is also critical for an administrator to - understand the concepts of network security and take precautions to not allow the server to - be vulnerable to the outside world. + Open ports in the firewallfirewall with caution - It is necessary to open some ports to the + server such as port 80 for http HTTP and 443 + for sslSSL , and it can be helpful to open ports for + remote access to the database or staff client. It is also critical for administrators to + understand the concepts of network security and take precautions to minimize vulnerabilities. - Use permissions and permission groups wisely - it is important to understand the + Use permissions permissions and permission groups wisely - it is important to understand the purpose of the permissions and to only give users the level of access that they require. @@ -144,29 +149,33 @@
Managing Log Files - Evergreen comes with a sophisticated logging system, but it is important to manage the OpenSRF and Evergreen logs. This section will provide a couple of log management techniques - and tools. + Evergreen comes with a sophisticated logging system, but it is important to manage the OpenSRF + and Evergreen logs. This section will provide a couple of log management techniques and tools. - Using the Log Rotate Utility to Manage Log Size - Fortunately, this is not a new problem for Unix administrators, and there are a number of ways of keeping your logs under control. On Debian and Ubuntu, for example, - the logrotate utility controls when old log files are compressed and a new log file is started. logrotate runs once a day and checks all log files that it knows about to see if a + Using the Log Rotate<indexterm><primary>logrotate</primary></indexterm> Utility to Manage Log Size + Fortunately, this is not a new problem for Unix administrators, and there are a number of ways of keeping your logs under control. + On Debian and Ubuntu, for example, + the logrotate utility controls when old log files are compressed and a new log file is started. + logrotate runs once a day and checks all log files that it knows about to see if a threshold of time or size has been reached and rotates the log files if a threshold condition has been met. - To teach logrotate to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, create a new file /etc/logrotate.d/evergreen with the - following contents: - compress - /openils/var/log/*.log { - # keep the last 4 archived log files along with the current log file - # log log.1.gz log.2.gz log.3.gz log.4.gz - # and delete the oldest log file (what would have been log.5.gz) - rotate 5 - # if the log file is > 50MB in size, rotate it immediately - size 50M - # for those logs that don't grow fast, rotate them weekly anyway - weekly - } + To teach logrotate to rotate Evergreen logs on a weekly basis, or if they are > 50MB in size, + create a new file /etc/logrotate.d/evergreen with the following contents: + + compress + /openils/var/log/*.log { + # keep the last 4 archived log files along with the current log file + # log log.1.gz log.2.gz log.3.gz log.4.gz + # and delete the oldest log file (what would have been log.5.gz) + rotate 5 + # if the log file is > 50MB in size, rotate it immediately + size 50M + # for those logs that don't grow fast, rotate them weekly anyway + weekly + } + - Changing Logging Level for Evergreen + Changing Logging Level for <application>Evergreen</application> Change the Log Levels in your config files. Changing the level of logging will help narrow down errors. @@ -174,16 +183,16 @@ will produce vastly larger log files and thus reduce server performance. Change logging levels by editing the configuration file - /openils/conf/opensrf_core.xml + /openils/conf/opensrf_core.xmlconfiguration filesopensrf_core.xml you will want to search for lines containing <loglevel>. the default setting for loglevel is 3 which will log errors, warnings and information. The next level is 4 which is for debugging and provides additional information helpful for the debugging process. Thus, lines with: - <loglevel>3</loglevel> + <loglevel>3</loglevel> Should be changed to: - <loglevel>4</loglevel> + <loglevel>4</loglevel> to allow debugging level logging Other logging levels include 0 for no logging, 1 for logging errors and 2 for logging warnings diff --git a/1.6/admin/admin-intro.xml b/1.6/admin/admin-intro.xml index 7316f99a5a..813ed6c2e0 100644 --- a/1.6/admin/admin-intro.xml +++ b/1.6/admin/admin-intro.xml @@ -1,6 +1,15 @@ - This part of the documentation is intended for Evergreen administrators and requires root access to your Evergreen server(s) and administrator access to the Evergreen staff client. It deals with maintaining servers, installation, upgrading, and configuring both system wide and local library settings. - Some sections require understanding of linux system administration while others require an understanding of your system hierarchy of locations and users. Many procedures explained in the following - chapters are accomplished with linux commands run from the terminal without a Graphical User Interface (GUI). - In order to accomplish some of the tasks, prerequisite knowledge or experience will be required and you may need to consult system administration documentation for your specific linux distribution if you have limited linux system experience. A vast ammount of free resources can be found on the on the web for various experinece levels. You might also consider consulting PostgreSQL and Apache documentation for a greater understanding of the software stack on which Evergreen is built. + This part of the documentation is intended for Evergreen administrators and requires root access to your Evergreen server(s) and administrator access to + the Evergreen + staff client. It deals with maintaining servers, installation, upgrading, and configuring both system wide and local library settings. + Some sections require understanding of Linux system administration while others require an understanding of your system hierarchy of locations + and users. Many procedures explained in the following + chapters are accomplished with Linux commandsLinuxcommands run from the + terminal without a Graphical User Interface (GUI). + In order to accomplish some of the tasks, prerequisite knowledge or experience will be required and you may need to consult system administration documentation for your + specific Linux distribution if you have limited Linux system experience. A vast ammount of free + resources can be found on the on the web for various experinece levels. You might also consider consulting + PostgreSQLdatabasesPostgreSQL and + ApacheApache documentation for a greater understanding + of the software stack on which Evergreen is built. diff --git a/1.6/admin/requirements-configuration.xml b/1.6/admin/requirements-configuration.xml index f069b80cae..efaa113b4d 100644 --- a/1.6/admin/requirements-configuration.xml +++ b/1.6/admin/requirements-configuration.xml @@ -1,86 +1,95 @@ - + System Requirements and Hardware Configurations - - - Evergreen is extremely scalable and can serve the need of a large range of libraries. The specific requirements and configuration of your system should be determined based on your - specific needs of your organization or consortium. - + + Evergreen is extremely scalable and can serve the need of a large range of libraries. The specific requirements and configuration of your + system should be determined based on your specific needs of your organization or consortium.
- - Server Minimum Requirements - - The following are the base requirements setting Evergreen up on a test server: - - An available desktop, server or virtual image - 1GB RAM, or more if your server also runs a graphical desktop - Linux Operating System - - Debian and Ubuntu are the most widely used Linux distributions for installing Evergreen and most development takes place on Debian based systems. If you are new - to Linux, it is strongly recommended that you install Evergreen on the latest stable server edition of Debian (http://www.debian.org/) - or Ubuntu 10.04 Server(http://www.ubuntu.com/) since the installation instructions have been tested on these distributions. Debian and Ubuntu are free distributions of Linux. -
-
+ + Server Minimum Requirements + + The following are the base requirements setting Evergreen up on a test server: + + An available desktop, server or virtual imagevirtual image + 1GB RAM, or more if your server also runs a graphical desktop + Linux Operating SystemLinux + + + DebianLinuxDebian and + UbuntuLinuxUbuntu are the most widely used + Linux distributions for installing Evergreen and most development takes place on Debian based systems. If you are new + to Linux, it is strongly recommended that you install Evergreen on the latest stable server edition of Debian + (http://www.debian.org/) + or Ubuntu 10.04 Server(http://www.ubuntu.com/) since the installation instructions have been + tested on these distributions. Debian and Ubuntu are free distributions of + Linux. + +
+
+ + Server Hardware Configurations and Clusteringhardwareclustering + + The hardware requirements for running a functional Evergreen server are minimal. It is also possible to scale up your evergreen configuration to be + spread your Evergreen resources and services over several or even many servers in a clustered approach for the purpose + of system redundancy, load balancing and downtime reduction. This allows very large + consortia to share one Evergreen system with hundreds of libraries with millions of records and millions of users, making the scalability of + Evergreen almost infinite. + Here are some example scenarios for networked server configurations: + + A small library library with 1 location, under 25,000 items and a few thousand users could easily run Evergreen on a single server + (1 machine). + A college or university with 1 million items and 20,000 users could run an Evergreen system using several servers balancing the + load on their + system by spreading services over multiple servers. It should host their PostgreSQLdatabases + PostgreSQL + database on a separate server. They could also cluster the Evergreen services + strategically to minimize or eliminate any necessary downtown when upgrading Evergreen or other server software. Moreover, system redundancy will reduce the chance of + unplanned catastrophic downtime caused by system failure since Evergreen will be running over several machines. + A large library consortium with several public library systems and/or academic libraries with millions of users and items could run an + Evergreen + system over many servers with clusters for Evergreen services as well as a cluster for the Postgresql Database. + + The key to Evergreen scalability is in the OpenSRF configuration files + /openils/conf/opensrf.xmlconfiguration filesopensrf.xml and + /openils/conf/opensrf_core.xmlconfiguration filesopensrf_core.xml. + By configuring these files, an administrator could cluster evergreen services over multiple hosts, change the host running a specific service + or change the host of the PostgreSQL database. + + The default configuration of Evergreen in the installation instructions assumes a single localhost + server setup. For more complex + multi-server clustered configurations, some server administration and database administration experience or knowledge will be required. +
+
+ + Staff Client Requirements + + + Staff terminals connect to the central database using the Evergreen staff client, available for download from + The Evergreen download page. The staff client must be installed on each staff workstation and requires at + minimum: + + Windows (XP, Vista, or 7), Mac OS X, + or Linux operating system + a reliable high speed Internet connection + 512Mb of RAM + + - Server Hardware Configurations and Clustering + Barcode Scanners -<<<<<<< HEAD - The hardware requirements for running a functional Evergreen server are minimal. It is also possible to scale up your evergreen configuration to be spread your Evergreen resources and services over several or even many servers in a clustered approach for the purpose -======= - The hardware requirements for running a functional Evergreen server are minimal. It is also possible - to scale up your evergreen configuration to be spread your Evergreen resources and services over several or even many servers in a clustered approach for the purpose ->>>>>>> d7545acfb3e35c75cd8d52bf8ca16ca95df72832 - of system redundancy, load balancing and downtime reduction. This allows very large - consortia to share one Evergreen system with hundreds of libraries with millions of records and millions of users, making the scalability of Evergreen almost infinite. - Here are some example scenarios for networked server configurations: - - A small library library with 1 location, under 25,000 items and a few thousand users could easily run Evergreen on a single server - (1 machine). - A college or university with 1 million items and 20,000 users could run an Evergreen system using several servers balancing the load on their - system by spreading services over multiple servers. It should host their PostgreSQL database on a separate server. They could also cluster the Evergreen services - strategically to minimize or eliminate any necessary downtown when upgrading Evergreen or other server software. Moreover, system redundancy will reduce the chance of - unplanned catastrophic downtime caused by system failure since Evergreen will be running over several machines. - A large library consortium with several public library systems and/or academic libraries with millions of users and items could run an Evergreen - system over many servers with clusters for Evergreen services as well as a cluster for the Postgresql Database. - - The key to Evergreen scalability is in the OpenSRF configuration files /openils/conf/opensrf.xml and - /openils/conf/opensrf_core.xml. - By configuring these files, an administrator could cluster evergreen services over multiple hosts, change the host running a specific service - or change the host of the PostgreSQL database. - - The default configuration of Evergreen in the installation instructions assumes a single localhost server setup. For more complex - multi-server clustered configurations, some server administration and database administration experience or knowledge will be required. -
- -
+ Evergreen will work with virtually any barcode scannerbarcode scanner – + if it worked with your legacy system it should work on Evergreen. + + - Staff Client Requirements + Printers - - Staff terminals connect to the central database using the Evergreen staff client, available for download from - The Evergreen download page. The staff client must be installed on each staff workstation and requires at - minimum: - - Windows (XP, Vista, or 7), Mac OS X, or Linux operating system - a reliable high speed Internet connection - 512Mb of RAM - - - - Barcode Scanners - - Evergreen will work with virtually any barcode scanner – if it worked with your legacy system it should work on Evergreen. - - - - Printers - - Evergreen can use any printer configured for your terminal to print receipts, check-out slips, holds - lists, etc. The single exception is spine label printing, which is still under development. Evergreen - currently formats spine labels for output to a label roll printer. If you do not have a roll printer - manual formatting may be required. For more on configuring receipt printers, see Printer Settings. - -
+ Evergreen can use any printer configuredprinters for your terminal to print receipts, check-out slips, holds + lists, etc. The single exception is spine label printing, which is still under development. Evergreen + currently formats spine labels for output to a label roll printer. If you do not have a roll printer + manual formatting may be required. For more on configuring receipt printers, see Printer Settings. + +
-- 2.43.2