# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Upgrading

Please note: as there have been changes both in the coppermine files and the database from previous versions to cpg1.5.x, users of older versions than cpg1.5.0 will have to apply all steps mentioned below: both the files have to be replaced and the update.php script has to be run once.

## Why upgrade?

There are major and minor releases of Coppermine. Major releases have so far been cpg1.0, cpg1.1, cpg1.2.x, cpg1.3.x, cpg1.4.x and cpg1.5.x. The next major release will be cpg1.6.x (which currently is in the dev pipeline - no scheduled release date yet) - you're just reading the docs for cpg1.5.x. Minor releases (the third number in the version numbering scheme) represent updates, also known as "maintenance releases". Major releases contain new features (compared to the previous major release), minor releases do not contain new features, but only bug fixes and slight improvements (like additional language files).

To understand the release policy of the coppermine dev team you have to understand how bugs are being fixed: we maintain a repository where the core code of each major release is being constantly being improved. Major and minor bugs that are reported on the coppermine support board are being fixed in that repository. Once a new package is being bundled, all fixes that have been made in that repository go into the new maintenance release.

There is a good reason for every new maintenance release: they are usually being packaged when a new bug or vulnerability is being discovered that is relevant in terms of security. As suggested above, there are several minor bugfixes that go into each new release as well, not only the one major bug or vulnerability that lead to the maintenance release. Therefore, it will not be enough to just fix the single vulnerability that has been the initial reason for a new package to be released. Instead, always upgrade to the most recent stable release as soon as it has been announced.

### Reasons for package releases

This is a list of minor releases of cpg1.5.x and the reason why they have been released. It is meant to explain why you should upgrade as soon as possible to the most recent stable release if you are running an outdated version.

Details

Package | Reason for release | Release Date
--- | --- | ---

cpg1.5.18

- Security release (stable)
- Announcement thread
- Added plugin hook 'upload_file_name'
- Add default values on 'onlinestats' installation to avoid weird dates right after plugin installation (thread)
- Updated Arabic language file (user contribution)
- Fixed simple upload process when users can just upload to their personal gallery (thread)
- Added upload button after each album name in album manager
- Added anchors on plugin manager
- Fixed infinite loop for delayed cookie issue workaround (thread)
- Disallow dots in cookie name (thread)
- Fixed issue with very big 'Max size for uploaded files' values (thread)
- Fixed album thumbnails for public albums in 'My gallery' view for regular users
- Fixed clickable keywords with spaces (thread)
- Fixed critical error for 'lasthits' meta album (thread)
- Fixed misleading error message when uploading files that exceed the file size limit with the simple upload form (thread)
- Added hidden feature "Create sub-directory named according to the album ID in users' upload directories during HTTP upload"
- Use selected album thumbnail for 'lastup' meta album (thread)
- Create user album in personal gallery when user is created via the user manager (thread)
- Added captcha for ecards feature (thread)
- Fixed a potential path disclosure vulnerability in core plugin configuration files
- Updated date/time formats in English (British) language file (thread)
- Updated header information to reflect new year

2012-01-10

cpg1.5.16

- Security release (stable)
- Announcement thread
- Fixed 'delete all comments' function in album properties
- Fixed issue with registration process if both email verification and admin activation are enabled
- Added plugin hook 'register_form_validate'
- Fixed display of non-image files when 'Go directly from thumbnail to full-sized image' is enabled in config (thread)
- Also send activation confirmation email if the user has been activated via the user manager (thread)

2011-09-01

cpg1.5.14

- Maintenance release (stable)
- Announcement thread
- Fixed username in activation mail (thread)
- Fixed version number displayed on the index page in the doc
- Added Norwegian language file (user contribution)
- Fixed album thumbnail for keyword albums without physical files when link_pic_count is disabled (thread)
- Use the intermediate picture 'use dimension' setting when resizing full-sized pictures during the upload process
- Fixed spelling of 'email' in German language files
- Fixed validation of ImageMagick path in config
- Added missing jump label 'top_display_media' to theme 'eyeball' (thread)
- Fixed PHP notices 'Undefined variable' and 'Use of undefined constant' during install step 2 (thread)
- Fixed some missing icons in help pages (thread)
- Fixed detection of intermediate-sized pictures when renaming files (thread)
- Added Serbian language file (user contribution)
- Fixed embedding of SWF files (thread)
- Fixed safe_mode check when sending emails
- Fixed selection of gallery icon for user categories (thread)
- Fixed display of random album thumbnail in sub-category if album keyword is set (thread)
- Updated Turkish language file (user contribution)
- Fixed user manager issue (thread)
- Fixed several keywords issues (issues with ampersands and spaces, leftover keyword separators) (thread)
- Fixed valid token issue during logout (thread)
- Display exact character encoding in config (thread)
- Fixed permission issue if admin tries to create a personal album (thread)
- Fixed batch-add issue if no file is selected (thread)
- Fixed visibility issue when setting an album password with IE (thread)
- Fixed admin tools format in eyeball theme (thread)
- Fixed thumbnail pages dropdown list on album list (thread)
- Adjusted part of documentation to reflect cpg1.5.x code change (thread)
- Fixed critical error message for meta album 'lastalb' if thumbnail image doesn't exist (thread)
- Fixed first level album thumbnails if thumbnail image doesn't exist
- Moved memberlist button to home menu drop-down for theme 'curve' (thread)
- Added workaround for delayed cookie issue during login (thread)

2011-08-01

cpg1.5.12

- Security release (stable)
- Announcement thread
- Fixed film strip issue (thread)
- Fixed indent for subcategories (thread)
- Fixed function 'utf_replace' (thread)
- Updated Portuguese language file (user contribution)
- Fixed custom thumbnail for files with uppercase extension (thread)
- Fixed memberlist issue when database name contains a dash (thread)
- Fixed colspan for guest comments when captcha is enabled (thread)
- Fixed PHP session name for captcha (thread)
- Fixed playback of Windows Media Player videos (thread)
- Fixed XSS issues (thread)

2011-01-02

cpg1.5.10

- Maintenance release (stable)
- Announcement thread
- Fixed default page when comments are sorted in descending order (thread)
- Fixed issue with plugin usergal_alphatabs when bridged (thread)
- Added charsetmgr.php to the delete files array (thread)
- Fixed admin email address validation (thread)
- Corrected French lang file to fix the non showing dropdown in the user manager (thread)
- Fixed search feature in the keyword manager (thread)
- Added partial Swedish language file (user contribution)
- Added Italian language file (user contribution)
- Added Icelandic language file (user contribution)
- Added language fallback to function cpg_get_default_lang_var (thread)
- Updated Finnish language file (user contribution)
- Updated default value of transparent_overlay in configuration.htm (thread)
- Added code that makes sure mb_strlen actually exists when called (thread)
- Fixed album manager issue when users aren't allowed to create private albums (thread)
- Fixed lower case user name issue with plugin usergal_alphatabs (thread)
- Fixed issue where users can edit public albums (thread)
- HTML validation (thread)
- Added partial Portuguese language file (user contribution)
- Added partial Catalan language file (user contribution)
- Fixed template error if guests are allowed to create public albums
- Allow admin to change email address (thread)
- Fixed issue when regular users try to upload to self-created public albums with simple upload form (thread)
- Fixed missing classid attribute causing videos not to play (thread, thread)
- Updated regex to fix error message for blank 'allowed file types' values (thread)
- Fixed setting email sender address
- Show 'upload needs admin approval' message for flash uploader (thread)
- Fixed exif issue when auto resizing is enabled and watermarking is disabled (thread, thread)
- Optimized picture resizing and watermarking procedure
- Fixed display of unprocessed bbcode markup in ecard display
- Fixed registration process if both email verification and admin activation enabled (thread)
- Fixed error message if uploaded file exceeds dimension limit (thread)
- Fixed session table name in SMF bridge files (thread)
- Fixed deprecated message on pluginmgr.php (thread)
- Fixed critical error on memberlist when bridged (thread)
- Fixed use of mysql_insert_id (thread)
- Fixed template placeholder bug that caused cut off tags
- Updated Swedish language file (previous version was mainly a Danish language file)
- Added partial Swedish documentation
- Fixed last visit display in user manager when bridged with SMF2 (thread, thread)
- Fixed implementation of plugin hook 'ip_information' (thread)
- Use IPTC headline instead of IPTC title as picture title according to docs (thread)
- Added additional submit button on top of 'Edit files' form (thread)
- Added plugin hooks 'after_edit_file', 'upload_html_pre_move' and 'upload_swf_pre_move' (thread)
- If error occurs during batch-add, show error message and don't redirect automatically (thread)
- Fixed default selection of check boxes for batch-add (thread)
- Fixed issue with 'User Gallery Alphabetic Tabbing' plugin when bridged (thread)
- Skip unknown file types during batch-add process (thread)
- Added label for 'remember me' checkbox (thread)
- Removed value 'SERVER_PROTOCOL' from client ID generator (thread)
- Fixed picture resizing via admin tools (thread)
- Removed declaration of function 'cpg_folder_file_delete' from update.php (thread)
- Fixed spelling of ImageMagick (thread)
- Fixed error message when entering invalid email address in profile manager (thread)
- Fixed renaming of already added files during batch-add (thread)
- Fixed picture manager - show user created albums in public categories (thread)
- No longer specify a MySQL engine - use the server default.
- Fixed comment approval when editing comments (thread)
- Add anonymous group if it doesn't exist (thread)
- Fixed ownership of albums created with xp publisher
- Consistent use of plugin hook types 'action' and 'filter' (thread)
- Adjusted/added maxlength parameter for album title/keyword according to database types (thread)
- Display more batch add error messages
- Fixed use of intermediate-sized image (thread)
- Theme 'curve': remove drop-down menu leftover if empty (thread)
- Added plugin hook 'replace_forbidden_conditions' (thread)
- No error message for admin during upload if image dimension exceeds configuration value (thread)
- Always use PHP time when querying the database (thread)
- Added missing/new plugin hooks to visiblehookpoints plugin
- Fixed potential security issue during installation (thread)
- Fixed issue with language manager (thread)

2010-11-30

cpg1.5.8

- Maintenance release (stable)
- Announcement thread
- Fixed setting default language with language manager (thread)
- Changed form token generation - removed trouble maker parameters (thread)
- Fixed language manager issue for language files with underscore (thread)
- Set moderator group to '0' for all albums to avoid problems for people who used that feature before it was dropped (thread)
- Fixed ecard if no intermediate picture is present (thread)
- Added Estonian language file (user contribution)
- Update 'last visit' time if it's a 'remember me' session (thread)
- Added Slovak language file (user contribution)
- While deleting non-images, delete the corresponding custom thumbnail if exists
- While renaming non-images, rename the corresponding custom thumbnail if exists
- While renaming files, check if there will be no conflicts before doing anything
- Added plugin hook 'token_criteria'
- Fixed missing CSS class cpg_summary and icon replacement leading to broken output of help boxes on config screen (thread & thread)
- Fixed possibility for users to edit their files in public galleries if disabled in config (thread)
- Disable the possibility for guests to enter file details by default (thread)
- Fixed error message when regular users try to delete their albums in public categories
- Re-organizing zip archives inside docs folder
- Adding documentation about plugin config options
- Fixed issue when reset file ratings (thread)
- Fixed empty values for 'reason' in 'report to administrator' email (thread)
- Fixed category view when albums with keywords are present (thread)
- Changed type of plugin hooks 'theme_thumbnails_wrapper_start/end' from 'filter' to 'action' and adjusted English documentation accordingly (thread)
- Added search terms to the title of the thumbnails page (thread)
- Added Japanese language file (user contribution)
- Adding boxes to config documentation for defaults, max, min, recomended and record name
- Display Coppermine news always in an iframe (thread)
- Fixed error message for non existing categories (thread)
- Replaced wrong link in update.php (thread)
- Added language table population section to update script to stop cpg1.4.x upgrades seing only Luxemburgish and Mexican as available langauges
- Updated Turkish language file (user contribution)
- Show password prompt if user tries to access file in password protected album directly
- Added Brazilian language file (user contribution)
- Fixed uploading to password protected albums in public categories (thread)
- Changed default values for user galleries category (thread)
- Fixed album visibility issue with user galleries (thread)
- Changed fix for category alpha sorting
- Fixed a critical error with the most viewed meta album
- Updated French language file (improvement and corrections)
- Allow higher port numbers for the site url config setting
- Fixed display of swf files in Firefox (thread)
- Fixed resizing of watermark backup images (thread)
- Fixed category permissions for secondary user groups (thread)
- Fixed issue when editing user albums (thread)
- Fixed issues with usergal_alphatabs plugin (thread & thread)
- Fixed line breaks in contact form emails
- Removed outdated FAQ items
- Updated Hungarian language file (user contribution)
- Fixed pre-population of user name on comments form (thread)
- Fixed timeout issue when fetching remote files (thread)
- Fixed thumb sharpening (thread)
- Place new comments form accordingly to sort order of comments (thread)
- Added Danish language file (user contribution)
- Added default value for 'user_profile6' during user creation (thread)
- Fixed HTML validation issue for german lang files - replaced & by &amp;
- Updated plugin manager documentation (thread)
- Added Hungarian language file (user contribution)
- Fixed pagination for user manager (thread)
- Updated Finnish language file (user contribution)

2010-08-06

cpg1.5.7 | This package was never released. In fact it never existed. | -

cpg1.5.6

- Maintenance release (stable)
- Announcement thread
- Fixed broken link (thread)
- Extended lang_byte_units array for some language files (thread)
- Fixed ip address duplicates in stat_details.php (thread)
- Updated Czech language file (user contribution)
- Fixed typo that caused the display of the 'not supported version' message box (thread)
- Fixed issue when uploading plugins to Windows-driven galleries
- Removed cpg1.3.x theme upgrade guide, as a direct upgrade from cpg1.3.x to cpg1.5.x no longer is supported
- Create different log entries for user registrations and admin user creations in access log file (thread)
- Fixed config value for path to ImageMagick when selecting GD during intallation (thread)
- Fixed query for album moderation group (thread)
- Fixed display of upload approval button (thread)

2010-06-04

cpg1.5.5 | This package was never released. In fact it never existed. | -

cpg1.5.4

- Stable release
- Announcement thread

2010-06-02

cpg1.5.3

- Release candidate
- Announcement thread

2010-03-05

cpg1.5.2

- Beta release. First public release for testing and evaluation. Do not use for production! No support available yet.
- Announcement thread

2009-11-16

cpg1.5.1

- Alpha release for testers and translators. This version is not a public release - it has only been released to a closed group of users for testing and translation purposes.

2009-07-24

cpg1.5.0

- This version was never released as a package - the version number 1.5.0 was just reserved for the initial development stage of the cpg1.5.x series before the feature freeze stage started. There is no package available, nor has there ever been one - only Subversion checkouts have been possible.

Never

As you can see, the coppermine dev team is constantly fixing and improving coppermine. Every non-trivial piece of software contains bugs, so there is no guarantee that the version that currently is the most recent one will be the final, ultimately bug-free version to be released in the cpg1.5.x series. It is absolutely vital that you perform regular updates as soon as new packages are being released.

### Changelog

Details on the changes that went into a release can be found in the changelog that comes with each package. The changelog file can be found in the root directory of the coppermine package. The changelog contains more information on additional languages and the time and date of the fix as well.

The changelog is a plain-text file that can be read using a simple editor - on Windows-driven machines, notepad.exe is fine.

## Steps needed to perform when upgrading Coppermine (from any version)

The instructions here apply for all Coppermine udpates/upgrades, so please read them carefully.

- ### Make a backup (dump) of your database

  Recommended tools for creating a database dump are mySqlDumper or phpMyAdmin - refer to the section Tools recommended by the devs: Database manipulation for details.
  Creating a backup is not mandatory in terms of functionality, but just a precaution in case anything should go wrong. It's advisable to make frequent backups anyway.

- ### Backup your include/config.inc.php file, your anycontent.php file and your "albums" directoy as a safety precaution if anything should go wrong.

  Usually, you just download your entire coppermine folder to your local hard drive or any other safe backup location using your FTP app. A fresh Coppermine package doesn't contain a config file anyway (that file has being created during install on your server), so you can't actually replace an existing config file with an empty one from the package; again, the backup is only a safety precaution.

- ### Download the most recent stable version existing in the download section of the official Coppermine homepage

  Don't assume that you have the most recent version, especially if you have installed Coppermine using a control panel app provided by your webhost. The coppermine dev team doesn't recommend using such auto-installers - please download the original from the official Coppermine homepage.
  If you're not sure what package to use (i.e. if there are several archive types), choose the zip archive, as Windows XP and better out of the box come with support for zip archives.

- ### Unpack the coppermine package you downloaded

  Similar to fresh installs, you need to extract the packed archive into a temporary folder on your local hard drive (preserving the folder structure within the package). Most modern operating systems come with an unarchiver that is capable to extract zip archives. If you don't have one, the Coppermine devs recommend using 7-Zip.

- ### Except for the "albums" directory, upload all of the new files and directories, making sure not to overwrite your anycontent.php file or the albums directory.

  In fact, you could upload the albums folder as well - the one that is contained in the package is empty anyway. The recommendation not to upload this folder is only meant as a pre-caution for some users who have "funny" settings for their FTP apps: some exotic FTP applications delete folders existing on the server and then re-create an empty folder on the server-side. This would of course be a disaster for all existing galleries during the upgrade process, as you would lose all your uploaded files in your gallery. However, the number of FTP apps that is set up in that strange way is small and therefore, it won't hurt for most to upload the albums folder as well. If you're not sure, use one of the FTP clients recommended by the devs.

- ### Run the update script

  To run the PHP-file "`update.php`" (i.e. the update script), just enter the URL into the address bar of your browser. The file "`update.php`" resides in the coppermine directory, so to run it you will need to point your browser to `http://yourdomain.tld/your_coppermine_folder/update.php` (if you have installed Coppermine into the root of your web site, you will have to run `http://yourdomain.tld/update.php` accordingly). This will update your coppermine install by making all necessary changes in the database.

To make this absolutely clear:

there is no such thing as a separate upgrade package - coppermine always comes as a complete package that can be used both for a fresh install as well as an upgrade.

## Additional actions for updating from particular versions

Depending on the version you're updating from, there are additional actions you need to perform:

### Upgrading from version cpg1.0, cpg1.1, cpg1.2.x or cpg1.3.x to cpg1.5.x

Support for a direct upgrade from cpg1.0, cpg1.1, cpg1.2.x or cpg1.3.x to cpg1.5.x has been dropped - if you still have such an ancient version running, you will have to upgrade in a two-step-process (from your version to cpg1.4.x and then on to cpg1.5.x)

### Upgrading from cpg1.4.x to version cpg1.5.x

- #### Plugins

  Plugins made for cpg1.4.x usually can no longer be run on cpg1.5.x, so you'll need to turn them off while you're still running cpg1.4.x (before you start upgrading). Some features that have been a plugin for cpg1.4.x went into the core of cpg1.5.x, so you may not need your plugins any longer. The safest way to make sure that plugins don't interfere is by disabling all plugins using the corresponding config option and then removing the content of the plugin folder using your FTP app. After performing the upgrade, get the plugin versions designed for cpg1.5.x and upload them, then re-enable the new plugins one by one.

- #### Custom theme

  If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide. Please note that some themes that used to come with previous versions of Coppermine have been dropped in cpg1.5.x. Those dropped themes are available as separate downloads though.

- #### Language files

  You can not use language files from older versions of Coppermine as primary language (the language the admin will use) - make sure you only have the language files that come with this package inside of your lang folder (delete or rename all files from older versions within the lang folder).
  If you need to use a language that hasn't been translated for cpg1.5.x, you can try using the language file from cpg1.4.x, however there are certain caveats:
  - cpg1.5.x-phrases that don't exist in your old language file will go untranslated or show in english
  - Coppermine can't be administered using an old language file - the admin needs to use a "true" cpg1.5.x language file
  - You're free to try using old language files, however when running into issues or error messages, switch to US-English and see if the issue goes away then. Using outdated language files goes unsupported
  Ideally, you should just delete all files from cpg1.4.x inside the `lang`-folder (the folder that correlates to `http://yoursite.tld/your_coppermine_folder/lang/`) before performing the update, which will make sure that only language files that have been designed for cpg1.5.x will actually reside inside the language folder.
  After completing the update you should visit the new language manager and enable/disable the languages that you actually need or the ones you do not need. The language manager can be accessed by going to Coppermine's config, expanding the section "Language & Charset settings" and then clicking on the link labelled "Manage languages". Alternatively, you can directly go to `http://yoursite.tld/your_coppermine_folder/langmgr.php` in your browser's address bar.

- #### Password encryption

  In cpg1.3.x, the passwords for the users used to be stored in plain text inside the database. This has been changed in cpg1.4.x - out of the box, cpg1.4.x used to store the passwords encrypted. However, there used to be an option for those who upgraded from cpg1.3.x to cpg1.4.x to skip the step of encrypting the passwords. In cpg1.5.x, the plain-text storage of passwords is no longer an option. If you're running such an old gallery that first was updated from cpg1.3.x to cpg1.4.x and now on to cpg1.5.x, the updater will automatically encrypt all the passwords of your users (including your own admin account). You don't have to mind anything specifically - the updater will do this automatically.

- #### Display FAQ

  The option to display a FAQ page to end users (by ticking the corresponding config option) that existed in cpg1.3.x and cpg1.4.x has been removed from cpg1.5.x, because it was hardly every used and only caused additional workload for translators. If you belong to those few users who actually used the FAQ menu item in Coppermine's navigation menu, you can easily come up with a custom page that uses coppermine's header and footer and display your individual FAQ there.

- #### Outdated files

  Delete the outdated files that came with older versions of coppermine that no longer exist in cpg1.5.x.
  Again, this is just a precaution to make sure that your new gallery doesn't contain flaws from outdated versions that would allow malevolent attackers to exploit weaknesses in older versions. To find out what files need to be removed manually, take a look at the output at the bottom of the update screen (`http://yourdomain.tld/your_coppermine_folder/update.php`) - the updater will attempt to delete the files for you, but in most server setups it won't have the permission to do so, so you will have to manually delete the files using your FTP app. Another way to find out about the files that need to be deleted is the versioncheck page - the files that are scheduled for removal will be displayed there as well - the versioncheck page won't attempt to delete those files though.

- #### Safe mode

  If your webserver is running in safe_mode and you have enabled "SILLY_SAFE_MODE" in include/config.inc.php, you will have to go to coppermine's config after performing above mentioned steps and enable "silly safe mode" there, as the setting in `include/config.inc.php` is no longer being taken into account in cpg1.5.x. The silly_safe_mode setting has been turned into a config setting instead.

- #### URI upload removed

  The URI upload feature has been removed from cpg1.4.x to cpg1.5.x, as it wasn't actually doing what many users thought that it would do: when using URI uploads people expected the file to remain at the URI that they entered into the upload form and not be transfered to the webspace where their Coppermine gallery resided on. Subsequently, they thought that they could safe webspace. This was a misconception and in fact just wishfull thinking: using URI uploads in cpg1.4.x, the file actually was uploaded to the Coppermine webspace no matter what.
  Therefore, the actual feature "URI upload" was removed in cpg1.5.x. However (depending on the operating system of your client) you can (ab)use the regular http upload form to accomplish a similar thing in cpg1.5.x: when entering the URL of a file accepted by Coppermine into the http upload form, the file will get downloaded to your client's temporary folder and then a regular http upload from your client to your server will be performed. This is not actually a feature built into coppermine, but rather a feature of your OS/browser and therefore it goes unsupported. However, there is no action required when performing the upgrade - this paragraph is just meant to inform you that the feature was dropped.

- #### Configure new features

  In comparison to cpg1.4.x, the new version cpg1.5.x comes with a load of new features. Some of them are enabled by default after performing the upgrade, which might not be what you want. Therefore, it's advisable that you (at least cursorily) read up the features list and check the config panel and the groups control panel for the changes there. The way that Coppermine handles languages has been changed as well, that's why you need to visit the language manager at least once after the upgrade and configure language support there.

### Upgrading from older versions of cpg1.5.x to the most recent version of cpg1.5.x

There are no additional steps to follow when upgrading from an older version of cpg1.5.x to the most recent version of that family. Just performing the basic instructions discussed above in Steps needed to perform when upgrading Coppermine (from any version) will be enough.

## The update script

The updater is a script that will update your database and delete leftover files from outdated versions that are no longer used in your version. It can be accessed by clicking on the corresponding link inside the admin menu or by entering the URL into the address bar of your browser.

You can run the updater by entering `http://yoursite.tld/your_coppermine_folder/update.php` into your browser's address bar.

### What it does

The updater performs three things:

- Check the authorization of the visitor who accesses the script
- Run the mysql database queries that reside in the file `sql/update.sql` (replacing the generic table prefix with the one you actually chose during initial install)
- Delete some files that used to reside inside coppermine's core in previous versions. The script only deletes unneeded files, but it doesn't touch your custom files, so there is absolutely no reason to be alarmed.
- Convert your passwords from plain text to encrypted: in older versions of coppermine there used to be an option to allow the passwords of your users to be stored in plain text within the database. In cpg1.5.x, plain text passwords are no longer supported. Therefore (if you don't already use encrypted passwords), the passwords in your database will be encrypted by the update script.

### Purpose

The updater will perform the database update for you after you manually have replaced the sql file it is using. The updater will not detect for you if there is a new version of coppermine available, nor will it download anything from the coppermine website. The level of automation is not that advanced in coppermine (yet).

To find out about new versions of coppermine or maintenance releases, check the news from coppermine-gallery.net.

### Authorization check

In Coppermine versions before cpg1.5.x, the update script used to be publicly accessible, e.g. everybody was able to run it. While this was good for support purposes (supporters were able to run the updater for users looking for help if it was obvious that they had not done so), there was a slight chance that this accessibility for everyone could at some stage be a security risk. That's why the dev team members decided to protect the updater from being run by any visitor who accesses it - starting with cpg1.5x you need to supply admin credentials. This can happen in four different ways:

- If you're already logged in as admin and run the updater from the link in coppermine's admin menu, the updater should run without further prompts for authentification - it uses the "regular" cookie-driven authentification that the entire coppermine script is using
- If you're not logged in as admin or if the coppermine core components no longer work without running the updater first (usually happens when upgrading major coppermine versions), you are prompted for credentials - enter the coppermine admin account details that you set up when installing coppermine in the first place
- If you can not remember your standalone coppermine admin credentials, you can supply your mysql credentials - you needed them when you installed coppermine in the first place. If you have forgotten them, read them up in the file that is used to store the mysql database connection details: download `include/config.inc.php` from your webserver to your client and then edit it with a plain text editor - you should see the mysql credentials in that file. If they have changed, your webhost should be able to help you retrieving them.
- If everything else fails, there is a toggle inside the code of the update script that you can use to skip authentification - to switch that toggle, download the update script (`update.php`) from your webserver to your client, find `// define('SKIP_AUTHENTICATION', true);` and replace with `define('SKIP_AUTHENTICATION', true);`. Safe your changes and upload the edited file to your webserver, overwriting the version that already resides on your server. Remember to restore the file as it was after having successfully performed the update.

### When must the updater be run?

You need to run the updater every time you upgrade/update, i.e. each time the file `sql/update.sql` is being replaced with a new version.

It doesn't hurt to run the updater several times in a row, so if you're in doubt, run it again.

## The version check tool

Since the release of cpg1.3.2 Coppermine comes with an additional version checking tool to help you resolve issues with upgrades and updates easily. To launch the versioncheck, simply add `versioncheck.php` to your browser's address bar after being logged into coppermine as admin (example: `http://yourdomain.tld/your_coppermine_folder/versioncheck.php`). With version 1.5.x, you can run the versioncheck utility from the Admin menu.

The versioncheck tool does not perform an actual update: it does not download newer versions of coppermine for you, nor does it install any fixes - it just is meant to make you aware of newer versions and help you to determine wether you performed an upgrade correctly.

### What it does

The script "versioncheck" is meant for two purposes:

- If you have upgraded from a previous version, you should perform versioncheck to see if your upgrade worked as expected
- Use versioncheck to make sure that your coppermine version is up-to-date

This script goes through the files on your webserver and tries to determine if the local file versions on your webserver are the identical to the ones at the repository of http://coppermine-gallery.net. Files that do not match are displayed and are the files you should update as well.

Compared to previous versions, the versioncheck page has been re-designed for cpg1.5.x both in terms of visuals as well as functionality.

### First run

When run for the first time, you will see the option screen first. For a start, default options should be OK, so just submit the form. The script will then determine the coppermine version you're currently running, an try to look up the XML file on the coppermine repository that corresponds to your version. If successfull, it will compare all files that exist on your server against the most recent files that are recommended to use (trying to obtain that data from the repository). Subsequently, you should see a list of folders and files that are supposed to exist on your server and an explanation if the file versions you have are the most recent. For details how to interpret the output, read on.

### Options

There is a small number of options available on the versioncheck page that should be pretty self-explanatory:

- #### Display output

  Determines wether the full output with formatting is used, or only a reduced plain-text output
  - Full-screen
    Use this by default. It will display as much detail as possible and has a nicer layout
  - Text-only
    If a supporter asks you to post your versioncheck-output, switch to this options, so you can easily copy the output and paste it into your posting on the coppermine support board. Only do so if a supporter explicitely asks for it! Another potential use for the text-only output is resources-consumption: if you suffer from time-outs, try using the plain-text option, as it consumes slightly less resources.

- #### Only show potential errors

  If you have no idea what all the output is supposed to mean or if a supporter asks for it, you might want to tick this option to only display the folders/files that have issues.

- #### Hide images

  When enabling this option, the many graphical resources that come with coppermine (i.e. all the icons and other images) are not being taken into account for display on the versioncheck page - a filter is being applied. Use this option to make the output less cluttered: images usually are not security-sensitive, so if you're only concerned about files that have an impact on security, you can safely hide the images.

- #### Don't check for modified files

  This filter will hide the column "modified" from being displayed and will result in a slightly less cluttered output. The check for modified files will not be performed when the script is being run. Only enable this option if you have performance issues with the script or if all your files are being reported as modified.

- #### Do not connect to the online repository

  If you check this option, the versioncheck script will not attempt to connect to the online repository and use the local XML file instead. Only use this option if connecting to the online repository doesn't work for you (e.g. if you're on an intranet and your server doesn't have internet access). The main drawback of not connecting to the online repository is the fact that you won't know about possible updates and most recent releases, so you better find the cause for your inability to connect to the online repository.
  During the development stage (between releases), the online repository usually is not being updated frequently, so only if you're using SVN checkouts (i.e. if you're a developer), you should tick this option.

The options screen lets you configure the versioncheck, or rather what is being displayed. The options aren't saved anywhere, so you will have to adjust them each time you run versioncheck. The default options should be OK for most users - only change them if you have good reasons to do so.

### Version comparison

There is a lot of information packed into a small space. Here's an example of a possible output and what the output means:

- #### Path

  The folder- and file name

- #### Missing

  If nothing is being displayed in this column, the folder/file exists on your server. If this is not the case (i.e. the folder/file does not exist on your server or is inaccessible), the column "Missing" will be populated with the result of this first, basic check.
  Note: there are some folders/files that are mandatory to have; others are optional. Anyway, if you perform a fresh install or upgrade, you should make sure to upload all folders/files. You can then later delete some of the optional files if you want, although this doesn't save much webspace.
  If a file is missing, all other steps that are next in the loop will not be performed - a missing file can't have a version number or similar. If versioncheck complains about missing files, use your FTP app to review if they are actually missing or inaccessible. If they are missing, re-upload them. If they are inaccessible, you will have to assign the needed permissions.
  Some files that existed in older versions might have gotten removed later. Those that might be a possible security issue will be displayed with the word "removed" in the "missing"-column. If you come across such a file, use your FTP-app to remove the file that versioncheck output complains about. Leaving the file where it is (ignoring the suggestion given by versioncheck) might pose a security risk and therefore is not recommended.

- #### Permissions

  Displays the permissions assigned to the folder/file. For some folders, write permissions are needed, while for others read permissions are enough. If the permission level of a folder is good, the result will be displayed together with a remark (in brackets) like "OK" (may differ in your language). Using a script like versioncheck to actually check permissions on folders works OK, while it may or may not work very well on files. This being said, you should mostly be concerned about folders that don't have sufficient permissions. If files are being reported to have an improper set of permissions assigned, don't be to alarmed if the rest of your gallery is working just fine.
  If permissions on folders need reviewing, read up the permissions section of the docs and do as suggested there.

- #### Version

  The version of the file on your server. If it is identical to the version indicated in the repository, you should see an "OK". If you're running an oudated version on your server you should get a fresh package and perform an upgrade.
  Note: folders don't have version numbers, nor do binary files (like graphics) have one, that's why the column "Version" displays "n/a" for folders and binary files. Only files that contain textual content can have a version number, so don't be alarmed by the many "n/a (OK)"-messages.

- #### Revision

  The revision of the file on your server. If it is identical to the revision indicated in the XML repository, you should see an "OK". If you're running an oudated revision on your server you should get a fresh package and perform an upgrade.
  Revisions are related to the versions - usually, if your version is OK, your revision should be OK as well. Only if you perform checkouts from the subversion repository, the revisions may "act up".
  The same thing that applies to version numbers applies to revisions as well: only textual files can have revision numbers - folders and binary files don't have a revision number.
  Confused? You don't have to: usually, you can safely ignore revisions - if you want to find out about what revisions are being used for, read the details on the subversion page.

- #### Modified

  If a file is accessible and the version and revision numbers match, the versioncheck script attempts to perform a check wether the file has been modified, compared to the original that comes with the coppermine package. This check is being performed by taking into account the MD5-hashes of the original file and your copy.
  When performing a fresh install or upgrade, there should be no modified files. If they are being displayed as modified, there are several possible reasons:
  - You deliberately modified the file (e.g. by applying a custom modification to it). In this case, it's OK to ignore the warning in the "Modified"-column and continue
  - Your file has not been transfered fully to the webserver. If this is the case, try to re-upload the file from your client to the server. If this doesn't help, your package might have gotten corrupt. Re-download a fresh one from the coppermine download section, un-archive it and re-upload the file. Make sure that your FTP app is configured to actually overwrite existing files
  - You have used an improper FTP-mode to transfer the file to your webserver. Using FTP apps, you can transfer files in binary or ASCII-mode. Most up-to-date FTP clients have a feature that will automatically select the proper FTP-mode for each file. If this is not the case, try the manual appoach and explicitely specify the FTP-mode for your file uploads.
  - Your webhost is injecting code into each file. Many free webspace providers (so-called "freehosts") do this to inject advertisments into your files. There's little you can do then except signing up with paid webhosting or ignoring the "Modified"-warning and hoping that things will work anyway.
  The output of the column "modified" can be filtered by enabling the option Don't check for modified files. This will result in a slightly increased performance of the versioncheck script.

- #### Comment

  The comment-column contains a short recommendation about what is supposedly wrong and what you should do to fix this. No comments usually means that everything is OK.

- #### Repository link

  The link to the SVN repository (web SVN) is meant as an additional feature for power-users and developers. Read the subversion repository instructions to find out more. If everything is fine, you don't have to worry about the link anyway.

### Things that could go wrong using versioncheck

As the actions performed by the versioncheck script are complex, there are several things that can go wrong, depending on your webserver setup:

- No connection to the online XML repository
  If your server resides behind a proxy or a web filter that requires authentication or doesn't have internet connection at all (e.g. on a company's intranet), the versioncheck script may not be able to connect to the online XML repository. Use the corresponding option to keep the script from trying. The caveats mentioned in the options section applies.
- I get a white page, or a page without actual content
  The script probably times out, as it consumes huge resources. You'll have to live without versioncheck then on your server setup, unless the server is yours to configure, so you can assign more memory and execution time to the script.
- I get an error message
  Error messages like `Fatal error: Maximum execution time of 60 seconds exceeded in /path/to/webroot/coppermine_folder/include/versioncheck.inc.php on line 276` are an indicator for the script consuming too many resources on your server. Try disabling some output options. If this doesn't help, you simply can not run the versioncheck script on your server.

Versioncheck is being provided as a courtesy to end users. As there are several factors that have an impact on it, it may or may not work on your server setup. If the versioncheck tool does nothing at all, this is probably the case for you - you don't have to be alarmed in this case: just make sure to keep your coppermine install up-to-date, preferably by enabling the config option "Display news from coppermine-gallery.net". Only if individual issues are being reported by the version check tool (i.e. only if some lines contain a remark in the comments column), you should be alarmed and take a closer look.

### Wrong expectations

To some this may sound trivial, for others it might be an important piece of information: naturally, files that you have not replaced during the upgrading process (e.g. `anycontent.php`) will show as outdated in versioncheck's output. This is of course to be expected. It doesn't hurt if you performed the upgrade exactly as suggested, as the files you're supposed to keep during that process don't actually contain code that needs updating. As an example, `anycontent.php` doesn't actually contain code at all (at least the file that comes with coppermine out of the box). It can contain custom code if you decide to use it. For details on the usage of `anycontent.php`, refer to the section "Using anycontent.php".

The versioncheck tool doesn't actually download newer file versions from the internet - it just checks the files you have on your server against a list of most recent files. The versioncheck tool doesn't check nor sanitize your site against hacking.

## Upgrading FAQ

- ### How do I find out about new Coppermine releases?

  There are various tools that allow you to stay up to date and make sure that you don't miss a release:
  - Leave the config setting "Display news from coppermine-gallery.net" enabled: this feature will alert you about news concerning releases and security issues on your coppermine-driven gallery. The news are only visible for you as admin, so your end users won't even notice.
  - Subscribe to the package on the sf.net project pages
  - Subscribe to the announcements board (by clicking on "notify" when being logged in). You will then get an email whenever a new posting is made on the announcement board.

- ### What's the difference between updating and upgrading?

  The words "update" and "upgrade" are often being used as synonyms. There is a slight difference though in the definition of the coppermine developers: upgrading usually means increasing the major version number, e.g. from cpg1.4.x to cpg1.5.x; while updating usually refers to minor version increases, e.g. maintenance releases from cpg1.5.x to cpg1.5.y.
  However, the usage is not that strict, so you might find places both in this document as well as other media (like the official coppermine forum) where the terms are being used the other way 'round. In fact, the words are pretty much synonyms as far as we're concerned.

- ### How do I find out what version of Coppermine I have?

  There are several ways to determine what version of Coppermine you are running:
  - If you can log in to your Coppermine gallery using your admin account, go to the config panel of Coppermine: the exact version will be displayed in the table header
  - Take a look at the output of any coppermine-driven page using your regular browser (usually by right-clicking on a blank section and choosing "Show source-code" or similar from the context menu). Scroll down to the bottom of the output (right before the closing body tag) - you should see a comment line there that will display the exact Coppermine version
  - Use a plain text editor to open a local copy of any PHP core file of Coppermine - in the file header you should see both an exact Coppermine version as well as the subversion revision number. This is the case as well for several other files that come with Coppermine.

## Downgrading from cpg1.5.x to an older version

CPG1.5.x incorporates many new features (compared to older versions), so we encourage all users to upgrade. However, there may be some who want to test cpg1.5.x and decide later that they want to go back to an older version. You have to keep in mind that a full upgrade changes the overall layout of coppermine's database that includes converting the encoding to unicode. This process can't be reverted: once you have done the conversion, the only way back is to restore a complete mySQL database dump (of course you have to create this backup before you upgraded in the first place). Creating mySQL dumps (backups) is recommended anyway, so you should do so now.

To make this absolutely clear: you can only downgrade if you used to have cpg1.4.x before and upgraded this version to cpg1.5.x. If you have made a fresh install of cpg1.5.x, you can not downgrade at all!

To actually perform the downgrade, replace all cpg1.5.x files on your server with the files from the older version (as if you were doing an upgrade, see above). Then restore your database dump that you must have made before upgrading. If you don't have a database dump (backup), you can't go back!