REBOL/IOS Administrator's Guide

Document Version 1.4 - 20-Dec-2004
IOS Version 1.0

Contents:

1. Basic Architecture
2. System Compatibility
3. Distribution Files
4. Server Installation
      4.1 Overview
      4.2 Host Name
      4.3 Server/Client Key Pairs
      4.4 File Setup
      4.5 Test Drive the Server
      4.6 Automatic Startup
5. Client Installation
6. Default Admin Applications
      6.1 User Admin
      6.2 Reg Edit
      6.3 Up-File
7. Troubleshooting
8. Notices
9. Other Documents

1. Basic Architecture

REBOL/IOS operates in conjunction with a standard web server and communicates with its client systems through the HTTP web protocol. Using a technique called HTTP tunnelling IOS can be added to any existing TCP network without changes to the network infrastructure, firewalls, etc.

The diagram below illustrates the basic flow of IOS:

Here's how it works:

1. When a REBOL/Link client needs to communicate, it initiates a connection to a predetermined web server that is used as a gateway for connecting to the REBOL/Serve server.
2. The client's HTTP request specifies a CGI program on the web server that acts as a proxy to redirect data from the web server to the REBOL server.
3. The CGI proxy opens TCP connections to REBOL/Serve which is running continuously as a separate process (on the same physical server or elsewhere; it does not matter).
4. All communications from Link to Serve and back again is encrypted using session-based keys. (The strength of the encryption key is regulated by the US government and can vary dynamically depending on country.)
5. REBOL/Serve processes, stores, and archives files locally on the server in the file's normal, unencrypted format.
6. REBOL/Link and Serve coordinate to synchronize files between the server and the client. Files are automatically downloaded to the client as needed.

Multiple REBOL/Link clients can connect in this fashion, taking advantage of file transfer scalablity that is inherent in the Web server.

In addition, a single web server is capable of hosting multiple REBOL/IOS servers (additional cost). For example, the marketing and development departments may operate and manage their IOS servers separately. Each server is completely independent of (and secure from) the others.

2. System Compatibility

The REBOL/IOS server is supported on more than 20 types of operating systems, including Solaris, BSD, Linux, Windows NT, and others. If you have no existing preference, Unix style systems (e.g. Linux or BSD) are recommended over NT (for better performance, reliability, and ease of administration).

The REBOL/IOS system can operate with any web server that supports the HTTP protocol.

The REBOL CGI Proxy is provided in both binary executable and source code formats. If the necessary binary does not exist for your specific hardware or OS, you can easily compile it from its source.

3. Distribution Files

All files are contained in a single archive that creates a directory called "rebol-serve" when restored. The primary server files are:

rebol-serve - The server executable rebol-proxy - The CGI proxy executable

These files contain server configuration information:

locations.r - resource location variables serve-config.r - configuration information

This file is a shell script that can be used to start the server with the correct command line arguments:

start-serve - shell script to start server

In addition, these directories and files are created and maintained by the server and should not be modified in any way:

applications/ - dir of fileset information archive/ - dir of archived files data/ - dir of fileset data file-table.r - file database post-data/ - dir of post function data serve-dat.r - internal data serve-license.r - encryption key serve-log.txt - debug log serve-state.r - state table the-journal.r - file changes users/ - dir of user information users.txt - user database

Warning

Do not modify the above files or any of the files in the REBOL/serve subdirectories. These files are being synchronized and improper modifications could result in serious errors, including loss of data or improper synchronization.

The archive also contains a link/ directory with one or more copies of the Link client in the link directory:

rl*-*-*-3-1.exe - Windows REBOL/Link binary rl*-*-*-4-2 - Linux REBOL/Link binary rl*-*-*-*-* - Other binaries, as included

Note that these files contain an embedded encryption key that allows them to access your unique instance of REBOL/serve. Other link binaries cannot access your system, even if a username and password are known.

The archive also includes a scripts/ directory that contains these additional scripts to help initialize REBOL/IOS:

rc.local - lines we add to start server on system boot serve - used to start multiple servers (if they exist) serveup - calls the start-serve script for IOS servers start-serve - starts a single server instance

This documentation is also included:

express.html - This administrator's guide as HTML express.txt - This administrator's guide as text

And, this source code is provided:

proxy/ - The web server CGI proxy

4. Server Installation

Assuming that you are already running a compatible web server, REBOL/IOS typically can be installed in less than five minutes.

4.1 Overview

During this procedure, you will:

• Unzip the distribution files on the server
• Put the files in their appropriate directories
• Run the IOS server to verify operation
• Run an IOS client to verify operation

4.2 Host Name

Your server was pre-configured with a host name according to the information you provided during purchase. It was suggested that you create a unique alias for the server, such as:

express.yourdomain.com

The information you provided is embedded in the binary of your copy of the REBOL server.

4.3 Server/Client Key Pairs

It is important to know that both the server software and the client software contain unique encryption keys that are used for authentication and certification. These keys are unique to your copies.

You cannot use another copy of REBOL/Link with this server, just as you cannot use this copy of REBOL/Link with another server. This approach provides a greater level of security, because even if someone obtains a username and password for your system, they cannot access your information unless they have obtained a copy of your REBOL/Link client.

4.4 File Setup

Here's how to setup the server files:

1. Unzip the REBOL/IOS distribution package into any secure directory on the same system as your web server. A good way to do this is to setup a new user account called called rebol-serve, logon to that account, and store the files there.
2. Copy the appropriate rebol-proxy file for your system from the proxies directory to your web-servers cgi-bin directory. If you do not see a proxy that matches your system, the source code is provided.
3. Give the rebol-proxy the correct file permissions as needed by your web server to allow the file to be executed as a CGI file. On most web servers, a cgi file such as this must be executable by all users. Note, however, that root (superuser) permission is not required.

Windows Internet Information Server (IIS) Note

If you are using the MS Windows Web Server, here are the steps needed to set execute permissions for your scripts (CGI) directory: Open the Internet Information Services (IIS) manager (normally found in the Start menu, programs, administrative tools section under "Internet Services Manager"). In the left-hand panel, click the name of your server to open it, then, under it click the "default web site" directory. In the right-hand panel, right click the "scripts" directory (or the CGI directory, depending on how you had your IOS host path configured) and open the "properties" option. Under the "virtual directory" tab, verify that the execute permissions option is set to "scripts and executables". Now open the scripts directory and right click on rebolproxy.exe, click on the file security tab, and click the edit button for "anonymous access and authentication control". Verify that "anonymous access" option is enabled. This allows your users to run the rebolproxy file in your scripts directory, which operates as a router to your IOS server (which implements its own high-strength user authentication methods).

4.5 Test Drive the Server

You can now start the REBOL/IOS server to verify operation.

1. Be sure you are logged in to the rebol-server or appropriate account. IF YOU DON'T, files will not be created with correct ownership and the server may not operate correctly.
2. Run the program "rebol-serve" from the shell. You should see it output a few lines to verify that it is running.
3. Run a REBOL/Link client as described in the next section. Verify that you can connect to the server.

If you cannot connect to the server, see the Troubleshooting section below.

Warning

Never directly modify files in REBOL/serve subdirectories. These files are being synchronized and improper modifications could result in serious operational errors, including loss of data or improper synchronization. When left alone, the system runs very well. You will only break it.

4.6 Automatic Startup

Assuming that you were able to connect in the above steps, you will want to add REBOL/Serve to your server startup scripts to initialize it when the server boots.

Startup scripts vary between systems. For instance, under Linux you will modify the /etc/rc.d/rc.local file. Example scripts are provided in the distribution package.

5. Client Installation

The REBOL/Link client takes just a few seconds to install. Here are the steps:

1. Copy the Link binary to a computer that is connected to the server. (Note you might want to put the Link program on your internal web-site to make it easier for your users to download. But, we don't recommend putting it on an external web-site.)
2. Run Link.
3. Read and accept the license agreement.
4. Change the installation directory and options as appropriate (although we recommend that for the initial test, you leave them set to their defaults to eliminate potential errors).
5. Click Install.
6. If you require web proxy settings to reach your web server, enter them in the Proxy panel.
7. The Setup panel will appear. Under Accounts, enter a user name of "admin" and a password of "test".
8. Click Save. If it is working properly, your Link desktop should restart, download the system desktop, display it and begin downloading other files.

If you were not able to connect, return to the Setup panel and re-enter the "admin" username and "test" password. Be sure that the password is lowercase. Click on the "Test Settings" button to view each step that occurs in the login process. See the troubleshooting section for details.

Change Admin Password

Once you have successfully logged in, change the Admin password with the User Admin application described in the next section.

6. Default Admin Applications

When you initially login as "admin", you should see an admin button. Click on it to view the admin folder. The folder will contain the following applications.

6.1 User Admin

This application is provided to help you create, modify, and delete user accounts.

To run it, single click on the User-Admin icon. You will see a window such as this:

Click the New button to create a new account, or select one of the existing accounts to modify its attributes.

Note that this application is just one way to create user accounts. You can also create accounts programmatically from existing databases or through web or email transactions. For more information, read the REBOL/IOS User Administration.

6.2 Reg Edit

This is a raw IOS registry editor that can be used to modify or delete existing filesets. In the hands of a skilled operator, this tool can be extremely useful. However, this application should only be used with full knowledge of the IOS fileset system and its tags. Improper use of this tool can create problems.

6.3 Up-File

This is a low-level file uploader that is useful for updating any IOS file, even hidden files (such as the desktop, icons, or document graphics).

To use it, click on the fileset that you want to update, then pick the file from the right-hand panel. A file requestor will prompt you for the new file, and it will be uploaded.

Note that you can only update, this application does not add new files.

7. Troubleshooting

If REBOL/IOS does not work, here are a few items to check:

1. Is REBOL/Serve running? Verify that there is a rebol-serve process running on the hosting server. (e.g. in UNIX do a PS command to see processes.)
2. Does the REBOL/Serve installation directory contain all of the files from the IOS package?
3. Check that your Web server is running. Is it configured for CGI operation, and does CGI have the correct directory path to the rebol-proxy program (installed above)?
4. Does the rebol-proxy have the correct permissions? It needs to be executable by all users.
5. Can the system with the Link client connect to your server? Run a browser to check a web page on the same web server that holds the rebol-proxy. (Note, however, that if you open the browser with a URL to the rebol-proxy, you will normally see an "internal server error message" depending on your web server. That's because REBOL uses its own protocol with this proxy, so normal web page access fails.)
6. On the client, check the servers.r file in the Link installation directory. Open it with a text editor. Does the host field contain the correct name for your web server. This is not a URL, it's a string that holds the name of the server.
7. If you think the client requires a proxy to connect to your web server, verify that it has been set correctly. This can be done from the Link Setup Proxy panel. You can also verify these settings by examining the prefs.r file in your Link installation directory (once installation has succeeded).
8. Verify that you are using a correct username and password.
9. If you change any of the REBOL/Serve files directly on the server, you may have created serious problems for IOS. One way to handle the situation is to remove the installation and start over. Keep in mind that all recently sync'd Links will contain the files necessary to restore your server.
10. It is possible to restore the server from an up-to-date Link that has all of the current files. Save all of the Link files in all of its subdirectories immediately before restarting serve.
11. If you are having problems logging in, select the test button from the Setup panel. It will provide feedback as the connection is being made.

8. Notices

• The security of files stored on your server is your responsibility. REBOL/IOS files are not normally stored on the server in encrypted format, so use correct account permissions to keep your files secure.
• Be sure to change your Admin password and always use good passwords that contain a mixture of numbers and punctuation characters such as .-!_+=.
• All code for the system, applications, and administration is REBOL Technologies copyrighted and licensed code for your use only.

9. Other Documents

Other information about REBOL/IOS can be found here:

REBOL/IOS Documentation