View source for Media Repository Administration

== Introduction ==

The KCP media repository controls access using the standard Unix
[https://www.gnu.org/software/coreutils/manual/html_node/Changing-file-attributes.html  ownership] and
[https://www.gnu.org/software/coreutils/manual/html_node/File-permissions.html permission] system.
Specifically, it uses the [https://flylib.com/books/en/4.150.1.60/1/ 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 ===

[https://manpages.debian.org/bookworm/acl/acl.5.en.html ACL]s 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 <code>sftp-only</code> 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 <code>/srv/media/</code> directory.

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

  [https://www.gnu.org/software/coreutils/manual/html_node/df-invocation.html df] -h /srv/media

=== Using the Unix Command Line ===

All the command line tools take a <code>--help</code> 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
<code>--help</code> 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 <code>chown</code>, 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 <code>sudo</code> placed in front.

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


== User and group management tools ==

;kcpm-adduser
: Creates a media user, or adds a media 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.
  --private makes a *_private directory
  --public makes a *_public directory.
  The named 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
  <code>-R</code> when nested directories are in different groups.

kcpm-audit
  Given a directory, recursively:
  Reports 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.
    
[https://www.gnu.org/software/coreutils/manual/html_node/chgrp-invocation.html chgrp] (-R) ...
  Change the group

[https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html chmod] o-x ...
[https://www.gnu.org/software/coreutils/manual/html_node/chmod-invocation.html chmod] o+x ...
  Change public access to a directory.

[https://www.gnu.org/software/coreutils/manual/html_node/rm-invocation.html rm]
  Delete a file or a directory structure.
[https://www.gnu.org/software/coreutils/manual/html_node/rmdir-invocation.html rmdir]
  Delete an empty directory.


[https://www.gnu.org/software/coreutils/manual/html_node/mkdir-invocation.html mkdir]
  Make non-media-controlled directories

[https://www.gnu.org/software/findutils/manual/html_mono/find.html 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.

[https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html 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.