Media Repository Administration

Introduction

The KCP media repository controls access using the standard Unix ownership and permission system. Specifically, it uses the User-Private-Group (UPG) idiom. This scheme works by associating a group with a directory and giving users, users that are allowed to make changes, membership in the group. In this document such groups are called "media groups".

If you are in a media group you have read/write access to the group's media files. Otherwise, you have read access -- or no access.

This is a simple approach, and has some limitations.

• Any given file can be in only one directory and is associated with only a single group. Categorizing a file as modifiable by multiple groups is not possible.

• Files and directories have an owner as well as a group. Typically the owner has read/write permissions. When a file or directory's owner is not a member of the file or directory's group, looking solely at group membership does not reflect the owner's permissions.

• The UPG idiom assumes that files remain in the directories in which they were initially put, or a sub-directory. It works because new files are given the group of the directory in which they are placed. Moving files between directories that belong to different groups requires that the file's groups be manually changed to reflect the group of the new containing directory. At least this is required if directories are assumed to control permission, so that who has access to what can be readily determined by where a file is placed in the directory hierarchy. This problem is mitigated with the use of a bespoke auditing tool, kcpm-audit.

• Membership in a group gives read/write permissions but says nothing about who can read but not change a file. To grant or deny read-only permission a different mechanism is used, granting or denying access to "other", anybody who's not either the file's owner or a group member. So determining who has read-only access is different from, and more complicated than determining who has read-write access. To obtain any kind of access to a file a user must have at least read permissions on the directory containing the file, and all of the parent directories.

Although standard Unix command line tools are available for use and can do the job, to simplify and standardize a number of bespoke command line tools are made available to do things like create media user accounts, create permission controlled media directories, and other management tasks.

The system has some naming conventions which aim to simplify management and system use. These are enforced when using the bespoke management command line tools. The conventions are:

• Directories that introduce permission restrictions have names that end in either "_public" or "_private". The ones ending in "_public" contain files that are readable by anyone with a media login. The ones ending in "_private" are readable only by media logins who are members of the directory's group.

• The groups that categorize access to media files, in which media users are made members, begin with "m-".

About alternative permission control mechanisms

ACLs are a permission system that can be used in conjunction with the traditional Unix permission system. ACLs provide fine-grained control over who has permission to do exactly what to each file. But ACL use is non-obvious, and ACL permissions are unlikely to be visible in off-the-shelf graphical remote access mechanisms which use SFTP. So while ACLs are available their use is not recommended.

The Groups Built-In to the System

The media repository< system is constructed of 2 core groups. These are the groups which the operating system is aware of and which provide it control.

sftp-only

Members of this group are "media logins". A media login is a regular Unix login that is in the sftp-only group. These logins cannot reach the Unix shell, which processes Unix commands.

media-admin

Members of this group have permission to use the bespoke programs which require elevated system-level privileges, like create new logins or groups.

Working from the Unix command line

File Locations and Disk Space Management

All media files are located in the /srv/media/ directory.

The amount of available space, and space already used, can be seen with:

 df -h /srv/media

Using the Unix Command Line

All the command line tools take a --help argument, which causes the command to display a brief summary of its functionality and arguments. The bespoke command line tools generally have no other documentation. You will need to execute them with the --help argument to determine their usage and arguments. Documentation to the standard Unix command line tools are linked herein.

Permission Errors

Some of the standard Unix commands, like chown, which changes file or directory ownership, requires special permission to run. If a "permission denied" error is received, try running the command with the word sudo placed in front.

When specifying a file or directory, sudo will require the fully qualified path -- a pathname that starts with /srv/media/ and lists all intermediate directories.

Difficulties Involving Adding Groups

When a user is added to or removed from a group, the change does not take effect until after the user logs in.

This matters, among other times, when adding your login to a group. Your login normally does not have permission to work with a group when your login is not a group member. After adding yourself to a group it is usually best to login again to gain immediate access to the group.

User and group management tools

kcpm-adduser

Creates a media user (a member of the sftp-only group), or adds any user to a media group.

kcpm-deluser

Deletes a media user, if the user owns no files. Or removes a media user from a media group.

kcpm-user-list

Lists all members of the sftp-only group, and the groups they are in.

kcpm-group-list

Lists all media groups, and the users they contain. Media groups are identified by a "m-" prefix.

kcpm-addgroup

Creates a media group.

kcpm-delgroup

Deletes a media group, only if there are no members, and no files in the group.

Directory and file management tools

CAUTION

Do not move files between directories which are in different groups. If you do, by a method other than kcpm-mv, the file's group will not reflect the group of its containing directory. That means that when a file is moved to a publicly readable directory it can still be modified by the group members of the origin directory, and is not modifiable by the group members of the containing directory.

If you do move a file, the group of the file must be changed to match the group of its containing directory. As an alternative to moving (renaming), copy the file and delete the original. (This will involve downloading and re-uploading, unless you're working from the Unix prompt.)

kcpm-audit can be run to report on such discrepancies, and to change group membership of files to reflect that of their containing directory.

Directories are rooted at a setgid directory, group sftp-only, so all sub-directories are setgid.

kcpm-mkmdir

Given a group and a directory name, makes a directory in the group. The group then controls access to content added to the directory. --private makes a directory with a name ending in "_private". --public makes a directory with a name ending in "_public". The *_public directory is readable by anyone with a login. The *_private directory is readable only by members of the group.

This is a convenience utility. The chgrp command can be used to change the group of a directory, and chmod o-x will make a directory private. The *_public and *_private naming conventions are recommended. They provide clear guidance as to which directories control access.

kcpm-mv

Move or rename files or directories. Takes care of re-assigning groups when moving files.

This is a convenience utility. The chgrp -R command can be used to (recursively) change group permissions. Files should be in the group of their containing directory, so take care using -R when nested directories are in different groups.

kcpm-audit

Given a directory, recursively report on unexpected permissions structures.

• Directories named *_public that are in the group of the parent
• Directories named *_public that are private (o-x)
• Directories named *_private that are not private (o+x)
• Files that are not in the group of their parent directory
• Files or directories that are owned by a user who is not a member of the file or directory's group.

Or, changes permissions to fix all of the above.

chgrp (-R) ...

Change the group

chmod o-x ...

Remove public access from a directory.

chmod o+x ...

Add public access to a directory.

rm

Delete a file or a directory structure.

rmdir

Delete an empty directory.

mkdir

Make non-media-controlled directories

find . -group name

Find everything belonging to a group. Find has many options, and can even be used to execute commands on the files found. It is useful for things like bulk changing of file ownership.

ls -lhR

Show everything in the file system.

Techniques

Anything put in the top-level directory are read/writable to anyone with a login.

Make a test login to test access

A test login can be created, and put into any set of groups. This allows for testing of access, and emulating what a user who's in the same set of groups is allowed to do.

Layer directories to control access

"Regular" directories can be used at any level to structure content.

If you have topdir_private/subdir, in respective groups topdir and subdir, consider the content of subdir. Only topdir members have access. Members of subdir have read/write access, and topdir members have read-only access.