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

# Groups

Each visitor of your gallery is a member of at least one group. In Coppermine, you don't assign individual permissions per user, but per group membership. There is a number of built-in groups that can't be deleted, and an infinite number of custom groups that can be defined by the admin.

## The group control panel

This is where you define what members of a user group can and can't do. In Coppermine, you don't assign privileges to individual users, but to groups. Users can be in various groups, so you can determine granular levels of permissions.

### Group names

Out of the box there are four groups in Coppermine. You can rename them just as well as you can rename custom groups, but it's recommended to leave them they way they are by default. This will make upgrades easier and help you administer and maintain your gallery. End users usually don't see the name of the group they are in, so you don't have to provide other group names.

However, if you choose to rename a group, just change the name and submit the group control panel form by clicking on "Apply modifications".

### Group types

There are two types of groups in Coppermine: those that come with it out of the box (default groups) and custom user groups. The ones that come with Coppermine by default ("Administrators", "Registered", "Guests") can not be deleted.
Users can be member of several groups - privileges inherited from the group accumulate. This means that the least restrictive permission/setting is being taken into account.

User "Linus" is member of the "registered" group as primary group and additionally member of the custom user groups "Cartoonists" and "Photographers". Members of the group "registered" are allowed to send ecards, but are not allowed to rate nor to post comments. They are not allowed to have a personal gallery neither. Members of the "Cartoonists" group are allowed to comment, send ecards and rate. Members of the group "Photographers" are not allowed to comment, to send ecards nor to rate, but they are allowed to have personal galleries. Subsequently, the user "Linus" would have the privilege to send ecards (inherited from membership in the group "registered"); he would be allowed to post comments and rate files (inherited from membership in the group "Cartoonists"). Additionally, "Linus" would have the privilege to have a personal gallery (inherited from membership int the group "Photographers"). The fact that members of the group "Photographers" are not allowed to rate, send ecards or post comments would not be taken into account, since membership inside the other two groups that grant those privileges would override the more restrictive settings for the group "Photographers".

#### Administrators

By default (after initial installation), there is only one user who resides in the Administrators group: the admin account you set up during initial install. You can later add other users to the administrators group (using the user control panel), but you have to keep in mind that all other members of this group have exactly the same privileges the original admin has: they could ruin your entire gallery in a couple of mouse clicks. It's strongly recommended to only assign others admin privileges that you fully trust.

#### Registered

By default, there is no user inside the "Registered" group. This will change as soon as you allow registration and members come in. All new users who get created (either by completing the login form or when they are created by an admin) reside in the "Registered" group (as primary group) no matter what.

#### Anonymous/Guests

Use the anonymous group to define what non-registered users can and can't do. Quota and "Personal gallery" are meaningless for anonymous users. You can not (and mustn't try) to assign existing users to the "anonymous" group - being a registered user automatically keeps them from being a member of the "Anonymous" group.

#### Custom groups

You can create groups as you see fit. Make sure to come up with a naming scheme that makes sense in the first place. It's advisable to start with a minimum set of custom groups and only add them later if you must.

Users can be members of several groups.

### Quota

#### Scope

Specify the maximum web space usage that the images (or other files if you allow them) uploaded by a user who is member of that particular group you assign the quota for is allowed to consume. The quota is set in kilobytes (KB) and only applies for the files uploaded into a personal gallery of a user. Uploads of that user that go into public albums are not being taken into account and don't add to the quota of that user.

The quota applies to each member of the group. Set the quota to a value that actually makes sense - setting it to several terabytes does not make sense and may lead to funny side-effects.

#### Zero means unlimited

Keep in mind that setting a quota to zero actually means "unlimited quota". If you want to disallow uploading, set the corresponding option that allows group members to have a personal gallery and upload to it in the column personal gallery by setting "Allowed" to "no" instead of setting the quota value to zero.

#### Calculation

If a user is member in different groups, the quotas from the groups don't get added. Instead, the least restrictive quota applies.

User "Linus" is member of the "registered" group as primary group and additionally member of the custom user groups "Cartoonists" and "Photographers". Members of the group "registered" are not allowed to have personal galleries at all, but members of the group "Cartoonists" are allowed to have a personal gallery and their quota is set to 20480 KB (i.e. roughly 20 MB) and members of the group "Photographers" are allowed a personal gallery with a quota of 40960 KB (i.e. roughly 40 MB). Subsequently, Linus will be able to upload files to his personal gallery up to a total of 40 MB, as the quota he inherits from group membership in the "Photographers" group is the least restrictive one.

### Group permissions (Rating/Ecards/Comments)

Permissions control what the user is allowed to do in the gallery (Rating/Sending Ecards/Posting Comments).

Bear in mind that if a user is a member of a group where "Rating", "Comments" or "Public albums upload" is set "YES", s/he will have the right to perform these operations only in albums where they are allowed. ( ie. uploading files will only be possible in albums where "Visitors can upload files" has been set to YES using the album properties screen of particular albums.)

### Public albums upload

Think of the setting "Public albums upload" as a general switch that determines if members of a particular group are allowed to upload to public albums (i.e. albums that the admin created) at all. Setting this to "Yes" will not immediately grant users access to upload to all public albums, but only to the albums that you explicitely specified upload permissions using the album properties dialog of a particular public album you want to allow user uploads to.

### Personal gallery

If "Personal gallery" is set to Allowed, the members of the group will be able to have their own gallery in the "User galleries" category where they will be able to create their own albums.

If "Approval" is set to NO, files uploaded by members of the group in albums created in their own gallery won't need to be approved by the admin. If "Approval" is set to YES, the users in the particular group will be able to upload, however the uploaded files will only be shown after the admin (you) has approved them.

### Access Level

For each group, you can set the group's access level to:

- None
  Users cannot view any images at all, except for the one thumbnail shown for an album or category. This option is only recommended for the guest/anonymous group if you want to force people to log in to view thumbnails and the rest. For other groups, this option usually doesn't make sense since your logged-in users will wonder why they logged in if they cannot see anything; the option is provided here in case some administrators find it useful. If you are going to set a group's access to 'none', make sure the guest/anonymous group is also set to 'none'. Otherwise, logged-in users will find that logging out gives them more access!
- Thumbnail only
  Users can view the thumbnails only. If they click on them, they will be shown a little dialog box that they are not allowed to view larger images.
- Thumbnail and intermediate image
  Users can see everything but the full-sized image pop-ups (if you have any)
- Thumbnail, intermediate and full-size image
  Users can access all sizes of images.

The setting here for the guest/anonymous group is the same as the setting "Allow unlogged users access" on the Gallery Configuration page under "User Settings". If you update the option here, it will update the configuration setting and vice versa.

### Assigned albums

The link "Assigned album(s)" will let you display what albums are assigned exclusively to members of a particular group. To make this absolutely clear: this feature does not allow you to actually assign albums to groups, it just displays those assignements. To actually assign albums to particular groups, use the album properties dialog of individual albums.

### Creating custom groups

To create a custom user group, click on the "Create new group" button located at the bottom of the "Groups" control panel. A new table row will appear at the bottom of the table with a blank name. It has not been saved yet - you will have to at least assign a unique name for it. Change any of the other properties of your new group and finally click the "Apply modifications" button.
It is recommended to only use web-safe alpha-numeric characters for group names (plus underscore and minus).

When being bridged you can't create new groups in Coppermine's groups control panel, as Coppermine then no longer controls the groups. Therefore, you have to create new custom groups inside the app you have bridged with.

### Deleting custom groups

You can not delete the four pre-defined groups ("Administrators", "Registered", "Guests"). All other (custom) groups can be deleted by going to Coppermine's groups control panel, checking the tickbox in front of the group you want to delete and finally clicking on the "Delete selected groups" button at the bottom of the screen. Deleting groups can not be undone. Deleting a group does not delete the members within that particular group.
When bridged, a similar thing that applies for the creation of groups applies to deleting them as well: Coppermine doesn't control groups any longer when being bridged, so you have to delete user groups in the app that you have bridged Coppermine with.

### Triggering synchronisation (bridged only)

When Coppermine is being bridged, you create and delete custom groups using the application that you have bridged Coppermine with. However, each time you edit groups inside the app that you have bridged with, you should go to Coppermine's group control panel once to trigger a syncronisation between Coppermine and the app you have bridged with in terms of groups. In other words: you have to make Coppermine aware of the changes that have taken place in the other app.

Keep in mind that the entire set of group names from your bridging app that shows in Coppermine's groups control panel after bridging is just a set of names for Coppermine. Coppermine is not "aware" of permissions on the level of your bridging app, so a group of moderators or otherwise privileged members doesn't mean that the group will have any special permissions in Coppermine right after bridging.

### Membership in more than one group

A user can be member of several groups, where one group is the primary group and all subsequent memberships are secondary group memberships. All registered users are members of the built-in group "Registered" no matter what - you can't change that.

There is no limit in the number of groups that a user can be a member of (at least there is no such limit built into Coppermine), but the administration effort increases if you have too many groups, so you need to find a level of permission that works for your puposes.

#### Limitations in Coppermine group architecture

There are some things that other applications are capable to do that Coppermine currently can not do:

- Coppermine doesn't have moderator features, so you are welcome to name a custom group that way, but this won't help permissions-wise, nor can this feature easily be implemented, as the black/white toggle `is-admin/is-not-an-admin` can be found all over Coppermine's core code.
- A user account can be member in several groups, but you can not nest groups, i.e. groups can not be members of other groups. In this aspect, Coppermine differs to other permission models (like LDAP or similar).
- Some permission levels (i.e. the right to view a particular album that can be assigned on the album properties dialog) are being assigned per group, but you can only specify one group and not several of them in those dialogs. Again, it wouldn't be easy to circumvent that.