REBOL/IOS User Administration

Document Version 1.3
IOS Version 1.0

Contents:

1. Overview
2. The User Admin Application
      2.1 Creating a User Account
      2.2 Deleting a User Account
      2.3 Modifying a User Account
      2.4 Important Notes
3. User Permissions
4. User Admin Scripting
      4.1 Script Headers
      4.2 Add a User
      4.3 Delete a User
      4.4 Changing a Password
      4.5 Changing User Attributes
      4.6 Requesting User Information
            4.6.1 User.r File
            4.6.2 User-Info Command
            4.6.3 Users Command
      4.7 User Info Report via HTML
      4.8 Exporting User Info to a Spreadsheet

1. Overview

This document contains everything you need to know for creating, deleting, and otherwise managing user accounts on REBOL/IOS.

The User-Admin application provides an easy-to-use interface for creating, deleting, and modifying user accounts. This application also allows an administrator to set the permissions available to all users.

In addition, you can write short scripts to perform all user administrative functions. This allows you to create custom operations that better suit the management process within your organization, making it more automated and efficient.

For example, you can create scripts to interface with external user management databases or spreadsheets. The design of IOS allows useful scripts to be written in the matter of minutes.

2. The User Admin Application

The User Admin application can be found in the Admin arena.

To view and access the Admin arena, you must be logged in as the Admin user. No other users will even know that the Admin arena exists, because it will not be synchronized on their systems.

Note: In 1.0, if you switch from logging-in as another user to logging in as the admin user, you may not see the Admin arena immediately. If that is the case, all you need to do is post a short message to the conference or messenger to force a resynchronization. Once this is done, the Admin arena will appear.

To run the User-Admin application, just click on its icon in the Admin arena. On a new IOS system, the application will look like:

The sections below describe how to create, delete, and modify user accounts.

2.1 Creating a User Account

To add a new user, follow these steps:

1. Click on the New button (only necessary if you've been editing other user information).
2. Type the login name of the user. Use alpha-numeric characters and dashes. Do not uses spaces or special characters.
3. Provide the email address. The email address is used as a key to identify the user. It must be unique for each user.
4. Click the Save button.
5. A window will pop-up to request a password. Use alpha-numeric characters and dashes. Do not use spaces or special characters.

As soon as the new account has been established by the server, you will see the new name appear in the account list on the left.

2.2 Deleting a User Account

To delete a user, follow these steps:

1. Click on the user account name.
2. Click the Delete button.
3. Confirm the deletion.

Note: Under IOS V1.0 you may see an error message telling you that the deletion failed. You can ignore this message. The account was deleted. The error occurs because certain synchronized files cannot be deleted from the user's server account. To verify the deletion, restart the User Admin application.

2.3 Modifying a User Account

Note: Under IOS V1.0 you can only modify the permissions and groups for a user. You must not modify the user name or email address.

To modify a user's permissions or groups:

1. Click on the user name.
2. Click on new permissions as needed.
3. Type groups names as needed. Separate them with spaces.
4. Click the Save button.

2.4 Important Notes

Here are some important notes about user administration:

• User passwords are stored in an encoded format. Once entered into the system, the precise password is no longer known. If you change a user's password, the user must enter that new password on the client. This is even true if you change a password back to the same value it was previously.
• The username and email address of a user cannot be modified.

3. User Permissions

The following user permissions are supported. These permissions can be controlled from the User Admin application and from user admin scripts.

	post	Allow the user to communicate with server-side scripts (called "post" functions). This permission is necessary to run many types of applications such as the contact database, shared calendar, and many others.
	new-app	Allow the user to create, modify, and delete filesets. This is required if you want the user to be able to create new folders and add or remove files from existing folders. In addition, it is needed to allow a user to create a new "distributed" application.
	user-info	Allow the user to obtain summary information about other users. This is required for applications that provide listings of user presence, such as the Who and Messenger reblets.
	users	Permit a user to request detailed user information. Allows administrative applications to request more detailed information about users.
	instances	Permit a user to request "user instance keys" that uniquely identify the presence of a user and differentiate between the same user who might be running on multiple clients.
	operator	Allow a user to perform server operations such as restarting the server. This permission should not normally be granted.
	user-admin	Allow a user to create, delete, and modify user accounts. This should only be granted to user administrators. This permission is required for the User Admin application.
	serve-code	Permit a user to submit a serve-side script (a "post" function). This should be granted only to system programmers and administrators. Server scripts can take full control of server resources.
	serve-admin	Grant a user full administrative privileges. This allows a user to change any and all system permissions and fileset attributes. This is a super-user mode that should only be provided to the most trusted of users.

In addition to these permissions, each fileset has its own permission attributes. These will be covered in a separate document.

4. User Admin Scripting

IOS supports scripting of all operations including user administration. This scripting feature lets you write custom scripts to add and remove users from other user databases, generate HTML or other types of reports, monitor user activity, and more.

4.1 Script Headers

All scripts listed below should include a script header of the form:

REBOL [Title: "User Admin" Type: 'link-app]

This title can be changed to further clarify the operation. The Type field must be set to allow the script to include the correct environment for the IOS Link client. If you forget to do so, an error will be generated telling you that certain IOS functions do not exist.

4.2 Add a User

Users are added by sending a NEW-USER command to the server. The script below will create a user named "Fred" with a password "derf":

send-server new-user ["Fred" "derf" fred@example.com]

The first two arguments are strings, and the third must be a unique email address.

Note that the connection to the sever is always encrypted, so the user information, including the password, is kept secure as it passes over the network. That is true for all IOS client-server communications.

If you need to supply variables for any fields, you will need to REDUCE the block to evaluate the variables. For example:

users: [ "Fred" "derf" fred@example.com "Sam" "mas" sam@example.com ] foreach [name pass email] users [ send-server new-user reduce [name pass email] ]

Forgetting to use REDUCE is a common error in such cases.

4.3 Delete a User

To delete a user, send the DELETE-USER command to the server along with the email address that uniquely identifies the user. For example, to delete the Fred user created above:

send-server delete-user fred@example.com

To delete users supplied in the above list:

users: [ "Fred" "derf" fred@example.com "Sam" "mas" sam@example.com ] foreach [name pass email] users [ send-server delete-user email ]

4.4 Changing a Password

The CHANGE-PASSWORD command is sent to the server to change the password for a user. The email address is used to uniquely identify the user. For example:

send-server change-password [fred@example.com "exderf"]

Note that the connection to the sever is always encrypted, so the password is kept secure as it passes over the network.

4.5 Changing User Attributes

Additional user information, such as permissions and groups, are stored in an object that can be sent to the server with the CHANGE-USER command. The command is given the user's email address and the user's object fields as an argument. Only the specified object fields will be affected. Fields that are not specified will not be changed.

The example below will change the groups and permissions for the user "Fred" created above:

user: context [ groups: [sales corporate management] rights: [post new-app user-info] ] send-server change-user reduce [fred@example.com user]

The above example is most typical, however there are other valid fields in the user object:

	name	The user account name (do not change).
	email	The user email address (do not change).
	groups	A block of groups. Each group is represented by a word (not a string). To create a new group, simply give it a name as a word and use CHANGE-USER to provide it to all users of the group.
	time-stamp	The date and time of the last activity of a user.
	log	A log of most recent commands and actions done by a user.
	rights	A list of permissions for a user. Each permission is represented with a word. Each word is listed and described in the permissions section above.

4.6 Requesting User Information

IOS provides three methods to obtain user information:

1. Every client has a synchronized list of users in its link system directory. This file can be read directly from the client.
2. The USER-INFO command can be sent to the server with a list of information fields that are required.
3. The USERS command can be sent to the server to request the user admin objects associated with every user.

Examples of these three methods are shown below.

4.6.1 User.r File

Every client includes a user.r file which is automatically synchronized whenever an administrative change is made to any user. The user.r file is in valid REBOL format and can be loaded as a data block. It is of the format:

[user1 [info1] user2 [info2] ...]

The example below shows how to load this user.r file and prints it to the console:

user-info: load link-root/system/users.r foreach [user info] user-info [ print [user mold info] ]

If you run this script, you may want to add a HALT at the end to keep the console window open.

4.6.2 User-Info Command

The most useful command is the USER-INFO command which will return a block of requested information about each user. For efficiency, it can request that only specific fields be returned. In addition, it can ask for the list to be limited to only the actively connected users.

The command has these formats:

send-server user-info [] send-server user-info [active] send-server user-info [[fields]] send-server user-info [active [fields]]

The word ACTIVE instructs the command to return only active users (users who still have session related info).

The field block is a list of information fields that can be returned. Each field is specified as a word. The results will be returned in the same order as they appear in this list. The accepted fields are:

name email time-stamp home location status client-ip log

If no list is provided, then a default set of fields is returned.

When the results of this command are returned to the client a notification event occurs. The example below shows how to handle such events:

insert-notify 'user-info none func [event data] [ probe data ] send-server user-info []

The INSERT-NOTIFY function above requests that the supplied function be executed when a USER-INFO notification event occurs. The result is then printed on the console.

The SEND-SERVER function with the USER-INFO command is used to request the user information from the server.

The format of the result is structure like this:

[time-stamp [user-name [user-info] user-name [user-info]...]]

The time-stamp is the precise server time. It can be used to determine the relative time for each active user.

The following example will print it in a more readable way:

insert-notify 'user-info none func [event data] [ print ["server time:" first data newline] foreach [user info] second data [ print [user mold info newline] ] ] send-server user-info []

Example results from the above command would look like:

server time: 6-Mar-2002/14:49:55.158107-8:00 admin [%U0/ 21-Feb-2002/10:57:40-8:00 none none serve@rebol.com] carl [%U2/ 6-Mar-2002/14:49:41.71825-8:00 "Lab" "unknown" carl@rebol.com "555.40.80.116"] cindy [%U3/ 6-Mar-2002/13:39:47.422165-8:00 "office" "unknown" cindy@rebol.com "555.40.80.10"] holger [%U1/ 6-Mar-2002/9:13:14.578558-8:00 "Laptop" "Here now" holger@rebol.net "555.20.17.9"] sterling [%U4/ 5-Mar-2002/20:12:19.74335-8:00 "Office" "Working furiously" sterling@rebol.com "555.20.14.4"] jeff [%U5/ 6-Mar-2002/13:55:14.374209-8:00 "chair" "Here now" jeff@rebol.com "555.20.11.10"] scot [%U6/ 6-Mar-2002/13:05:37.720355-8:00 "Laptop" "unknown" scots@rebol.com "555.3.9.24"]

To return just the datestamps of all users:

send-server user-info [[time-stamp]]

for systems with a large number of users, asking only for the required fields can save bandwidth.

To see just the time-stamps and email addresses of active users:

send-server user-info [active [time-stamp email]]

You will notice that the resulting fields are returned in the same order that you requested them.

4.6.3 Users Command

The USERS command can be sent to the server to obtain all information about all users. To receive the result of the command, you will need to set up a notification event handler.

The example below fetches information about all users and displays it.

insert-notify 'users none func [event data] [ foreach [user-id info] data [ print [user-id mold info] ] ] send-server users none

This command can only be executed from an account that has the USERS permission enabled. Otherwise, an error will occur.

4.7 User Info Report via HTML

The following complete script shows how to generate a useful user report that can be printed via HTML. Just cut and paste this into a file and execute it from REBOL/Link to try it.

REBOL [Title: "Print User Info" Type: 'link-app] html: make string! 10000 emit: func [data] [append html reduce data] insert-notify 'user-info none func [event data] [ emit [<HTML><BODY><H2>"Users as of " now </H2><TABLE BORDER=1>] foreach [user-id info] second data [ emit <TR> foreach field info [ emit [<TD> field </TD>] ] emit </TR> ] emit [</TABLE></BODY></HTML>] write %tmp-info.html html browse %tmp-info.html ] send-server user-info [ [name email time-stamp home location status] ]

4.8 Exporting User Info to a Spreadsheet

A similar technique to that above can be used for generating a spreadsheet of user information:

REBOL [Title: "User Info Spreadsheet" Type: 'link-app] out: make string! 10000 emit: func [data] [append out reduce data] insert-notify 'user-info none func [event data] [ foreach [user-id info] second data [ foreach field info [ emit [{"} form field {",}] ] clear back tail out ; remove last comma emit newline ] write %tmp-info.csv out browse %tmp-info.csv ] send-server user-info [ [name email time-stamp home location status] ]

The BROWSE function above will open the browser with the CSV file which will launch your default spreadsheet application. This behavior is platform dependent. For example, under Windows it will open Excel and show the spreadsheet.