REBOL/IOS Filesets

Document Version 1.1
IOS Version 1.0

Contents:

1. What are Filesets?
2. Fileset Structure
      2.1 Fileset Names
      2.2 Fileset Files
      2.3 Fileset Tags
      2.4 Example Application Fileset
      2.5 Example Folder Fileset
      2.6 More Examples
3. Tags
      3.1 Valid Tags
      3.2 Default Tag Values
4. Users and Groups
5. Access Privileges
      5.1 Tag Privileges
      5.2 Other Privileges
      5.3 Examples

1. What are Filesets?

Filesets are collections of files and descriptive metadata. Filesets are used for organizing, distributing, synchronizing, and controlling files across all IOS servers and clients.

In essence, the REBOL/IOS distributed file system architecture is organized around nothing more than a collection of filesets. A typical IOS installation has several dozen, if not several hundred, active filesets.

Every fileset is identified by name, and filesets are commonly used to define the set of files used by IOS applications, including both their code and data. By default, the IOS Desktop application creates most folders as filesets (but that is done by convention, it is not a requirement).

Fileset metadata, called fileset "tags" are used to describe the icons, folders, services, users, groups, and permissions of a fileset. The fileset tags are represented by REBOL blocks, making them open ended and allowing new tags to be developed over time.

A fileset can be public and shared by all users, or it can be private and shared by a specific set of users or a group.

2. Fileset Structure

A fileset consists of a name, metadata about the fileset, and a collection of files.

Filesets are stored and transferred as a standard REBOL block, making them:

1. Machine and OS independent.
2. Easy to import, parse, and manipulate within REBOL.
3. Simple to transfer over the network.
4. Humanly readable should a problem occur that requires directly examining their contents.

2.1 Fileset Names

Fileset names are used to uniquely identify the fileset within the IOS distributed file system.

A fileset name must be a valid REBOL word as defined in the REBOL/Core User Guide. It can include most characters but not spaces and REBOL delimiters.

For example, these are valid fileset names:

contacts messenger bills-files tom!432

These are not valid fileset names:

123 ; must be a word 12files ; cannot start with numbers "fred" ; a word not a string freds files ; no spaces allowed (sounds) ; no parens allowed

In addition, the Desktop application imposes a specific fileset naming convention to help it identify private and public folders.

2.2 Fileset Files

The files of a fileset are normally related in some way. For example, an application fileset will often contain the code and data files that are used to implement the specific application. The files that are part of a desktop folder are the files that are related to the icons when you open the folder.

As an example, the ADMIN fileset typically contains these files:

%admin/reg-edit.r %admin/user-admin.r %admin/up-file.r %admin/cross-install.r

The files are written as file paths relative to the root location of the REBOL/Link client, as specified in the prefs.r file. References to files above the link root are not permitted and will cause an exception.

Note that the order of the files within a fileset is not important. Applications are free to put them in any order.

Some applications may require files be located in different physical directories. A file can be located anywhere within the client's directory hierarchy. This allows an application to include code modules, configuration files, or other data files that are located in special subdirectories.

For example, a fileset might include these files:

%apps/whiteboard/whiteboard.r %apps/whiteboard/templates.r %apps/whiteboard/objects/circle.r %apps/modules/draw-funcs.r

A file may be part of more than one fileset. For example, a common data file or code module may be used by different filesets.

2.3 Fileset Tags

A fileset includes metadata to describe its properties, users, privileges, desktop icons, folders, and more. These are called fileset tags.

Both the client and the server examine and act on the tags of a fileset. The server uses tags to determine what users should receive the fileset and what privileges are granted to modify various parts of the fileset. The client uses tags to determine where and how files should be displayed on the desktop.

Tags are expressed in standard REBOL context block format, making them easy for programs to create, update, and modify and easy for programmers and operators to read and debug.

Each tag consists of a name set to a value. For example:

install-date: 4-Dec-2001/18:00-8:00 users: ["admin" "carl"] folders: [[name: "Administration" path: %admin/]]

A number of standard tag names are defined and will be described below. Custom tags are also allowed, but should be used with a prefix to prevent them from colliding with future system tags.

2.4 Example Application Fileset

As an example, here is the definition for the CONTACTS application that is part of the standard distribution.

The fileset has the name:

contacts

It contains four files:

%apps/contacts/rebodex.r %apps/contacts/contacts.r %apps/contacts/names.r %apps/contacts/delta.r

These files provide the code and data that make the CONTACTS application work. Notice that the file paths are relative to the link-root directory of the client system.

The CONTACTS fileset includes these tags:

install-date: 5-Dec-2001/15:00:17-8:00 access: [ properties: rights: desktop: folders: icons: serve-code: change: delete: ["admin"] post: 'all ] icons: [ [ name: "Contacts" item: %apps/contacts/contacts.r folder: %apps/ image: %desktop/icons/contacts.gif info: "Open contact database" ] ]

From these tags, IOS can determine that:

• The fileset was created on 5-Dec-2001
• The fileset is distributed to all users (because no USERS or GROUPS tags appear).
• The fileset, its files, and tags can only be modified by the system administrator.
• All users can post data to the fileset's server-side script. (Described separately.)
• The fileset contains a single icon that is found in the apps folder.

2.5 Example Folder Fileset

Here is an example of a private folder that is shared between two users. The name of this fileset was generated by the desktop application when the user created the folder.

The name is:

users!carl!installer!!10950320

This fileset contains two files:

%users/carl/installer/install.r %users/carl/installer/uninstall.r

The fileset has these tags:

access: [ properties: rights: delete: ["carl"] folders: icons: change: ["carl" "tom"] ] users: ["carl" "tom"] folders: [ [ name: "Installer" path: %users/carl/installer/ ] ] icons: [ [ name: "Installer" type: 'folder item: %users/carl/installer/ folder: %users/carl/ info: "Example installer." ] [ item: %install.r ] [ item: %uninstall.r ] ]

The tags indicate:

• Only Carl can modify the properties and rights of the fileset, and only Carl can delete the fileset.
• Both Carl and Tom can add, modify, and delete files, folders, and icons within the fileset.
• The fileset is distributed only to Carl and Tom. No other users will receive the fileset. In fact, they won't even know that the fileset exists.
• A new desktop folder will be created for the fileset. This folder will appear in the existing users/carl folder.
• Three icons will be displayed for the fileset. One of the icons will appear in an existing users/carl folder. The other two will appear in the new users/carl/installer folder.

2.6 More Examples

Real fileset examples can be found in the fileset registry that is used by every IOS Link client. The file is a REBOL source file that caches the filesets used by the REBOL/Link client.

The registry.r file is found in your link-root directory and can be opened with any text editor, or you can open it from the desktop by pressing CTRL-E CTRL-O and select the registry.r file at the link-root.

Within the registry, filesets appear in the format:

fileset-name [ tags... ] [ files... ]

There are a few fileset administration applications that display and manipulate with this format. In addition, if you are familiar with how REBOL formats data, you can easily create your own script to display or browse this file.

Modifying Registry.r

Generally, do not modify your registry.r file. Doing so can create problems for your Link client, such as not displaying the correct files, or downloading files over again, etc. However, that warning aside, it can be quite educational and insightful to modify the registry file. For instance, you can experiment with the parameters of an icon or folder before actually submitting the change to the server. Before you modify the registry file, quit all REBOL/Link applications first. Modify the file with a text editor. Save it out. Then, restart the Link client to see any changes. The registry can also be modified in emergency situations, such as when a file has been unshared (does not appear on the desktop) but you still need to use it from your desktop for a short period of time. If you mess up the registry file, it's not a problem. You can create a fresh copy of the correct registry.r file by deleting the file and restarting your Link client. The client will automatically generate a new registry.r. (Note, that you must be online and able to connect to your IOS server for this to happen.)

3. Tags

Filesets contain metadata tags that describe a fileset's properties, privileges, desktop appearance, and more.

As shown earlier, tags are written in standard REBOL block format. Each tag name is a SET-WORD followed by a tag value. For example, the tag block for a fileset could be:

[ access: [post: 'all] users: ["ben" "bill" "bob"] icons: [ [item: %app1.r] [item: %app2.r] ] ]

Tags can appear in any order within the block and unknown tags will be ignored.

3.1 Valid Tags

These fileset tag words are defined (in alphabetical order):

	access	a block that specifies the access privileges to the fileset's tags and file lists.
	folders	a block of desktop folder specifiers. The structure of the folders block is determined by the desktop application and is ignored by the server.
	groups	a block of strings that specify what groups of users sync on the fileset.
	icons	a block of desktop icon specifiers. The structure of the icons block is determined by the desktop application and is ignored by the server.
	install-date	an optional date that is provided by installer scripts to indicate when a fileset was first installed.
	priority	an integer that specifies the download priority of a fileset. The range of the integer is +100 to -100. Filesets with greater numbers download first. If set to NONE, the fileset will not auto-download.
	services	a block of desktop service specifiers. The structure of the block is similar to that of icons.
	users	a block of strings that specify what users sync on the fileset. If this tag is missing, then all users will sync on the fileset.
	version	this is a tuple published in the System fileset to indicate the current Link client version number. It is checked by the Desktop application.

The structure of desktop related tags will be described in a separate document.

3.2 Default Tag Values

Most tags are not required, and tags all have reasonable default values if they are omitted. In fact you can create a fileset that contains no tags at all.

If no USERS tag or GROUPS tag is provided, then all users will receive the fileset.

If no PRIORITY tag is set, then files will be synchronized with a priority of zero.

If no ACCESS tag is provided, then the permissions will all default to the system administrator (users that have the serve-admin permission set).

4. Users and Groups

Filesets can be restricted to selected users. The USERS and GROUPS tags control who receives the fileset.

For a user to receive a fileset, the user name must either appear in the USERS block or be part of one of the groups in the GROUPS list. (Except if there are no such lists given, in which case everyone receives the fileset.) A user who is not listed for a fileset will not know that the fileset even exists. It will not appear in fileset lists in tools that provide such lists.

Just because a user is listed to receive a fileset does not imply that they have access rights to control, modify, or delete the fileset. A user also needs proper access permissions. See the Access Privileges section below.

As an example, if a fileset contains the tag:

users: ["bob" "bill" "ben"]

Then only those three users will receive the fileset. The fileset will be private to those users.

Similarly, if groups are supplied in a tag:

groups: ["management" "admin" "developers"]

then only users who are part of those groups will receive the fileset. (User group lists are normally created and managed by the IOS administrator with the User Admin application.)

If both a USERS and GROUPS list is provided, then all of the specified users (the union of the lists) will receive the fileset.

5. Access Privileges

The ACCESS tag controls what users and/or groups of users can control various permissions of a fileset.

Note the distinction between the USERS, GROUPS, and ACCESS tags. The USERS and GROUPS tags specify what users can receive the fileset. The ACCESS tag specifies what users can modify the fileset.

The ACCESS tag uses the standard REBOL object block format:

access: [ privilege1: value1 privilege2: value2 ... ]

It also allows cascaded assignments such as:

access: [privilege1: privilege2: privilege3: value]

Each privilege represents a type of access, and each value specifies a list of users that have the right to affect it. Users can be specified in three different ways.

To specify all users have the permission use the value:

'all

To specify a specific set of users have permission:

["user1" "user2" "user3" ...]

To specify users and/or groups:

["user1" "user2" ...] ["group1" "group2" ...]

Either block can be empty. For example, there are only groups listed in this line:

[] ["group1" "group2" ...]

If no ACCESS tag is specified within a fileset, all privileges are disabled for all users, except the system administrator.

5.1 Tag Privileges

The following access privileges allow the tags of a fileset to be added, modified, or removed.

	desktop	Controls desktop tags: services
	folders	Controls adding, changing, and removing folder tags.
	icons	Controls adding, changing, and removing icon tags.
	properties	Controls fileset property tags: version, install-date, priority.
	rights	Controls fileset access rights tags: users, groups, access This is an important privilege because it grants the right to add or modify any of the other tags within the same fileset. Essentially, if a user has this privilege, he has complete control over the fileset because he can change any of the other access rights.

5.2 Other Privileges

Other privileges are supported to allow specified users to:

	change	add, remove, and change files within the fileset.
	delete	delete the fileset
	post	send messages to the fileset's server-side functions
	server-code	create and modify server-side post and poll function code.

5.3 Examples

Give "Fred" all privileges for the fileset:

access: [ rights: properties: desktop: folders: icons: change: delete: post: server-code: ["fred"] ]

Give no users privileges. Which means that only users with system-admin privilege can modify the fileset.

access: [ rights: properties: desktop: folders: icons: change: delete: post: server-code: [] ]

Give all users all privileges for the fileset (usually not a good idea):

access: [ rights: properties: desktop: folders: icons: change: delete: post: server-code: 'all ]

More often, access would be set to allow one user to "own" the fileset but allow other users to add and modify its content:

access: [ rights: properties: delete: ["fred"] folders: icons: change: 'all ]

And, in the case of functional filesets (like Conference, Alerts, etc.), only the POST permission is granted to all users:

access: [ rights: properties: change: delete: ["fred" "steve"] post: 'all ]

Note that unspecified permissions are by default set to [], granting no users privilege.