# Quick Start for the 4Suite™ Repository

This version:
  Revision 0.4 (2003-07-17)
Principal authors:
  Uche Ogbuji (Fourthought, Inc.)
  Shatin Rai (Fourthought, Inc.)
Add'l contributors:
  Mike Brown (Fourthought, Inc.)

This document can be freely translated and distributed. It is released under the LDP License.

## Abstract

4Suite™ has many features. This document provides a step-by-step introduction to give the user familiarity with the document repository portion of the software.

# 1 Introduction

This document explains how to start using the document repository ("repo") and RDF database ("RDF model") features of 4Suite, after you have already installed the software according to the relevant installation guide. In older versions (0.11.1 and older), these features were called "4Suite Server", or "4SS" for short, and were distributed as an add-on to the main 4Suite libraries. The features are now distributed and installed along with the core libraries of 4Suite. Some additional configuration and activation is required before you can use them. If all you want to do is use the 4Suite Python libraries and their corresponding command-line tools, then you can ignore this entire document.

# 2 Notes

Since there is not yet a better name for the document repository, RDF model and related services, the term "4SS" (for 4Suite Server) still appears in some documentation and throughout the software.

Command-line examples provided in this document do not require superuser/Administrator privileges. The command-line utilities that come with 4Suite work on all supported platforms.

In this document, "{python}" in a filesystem path represents the directory in which 4Suite is installed. For example, on some Windows systems it is typically something like C:\Python22\lib\site-packages, and on Unix systems it is typically /usr/local/lib/python2.2/site-packages.

Command-line examples may be shown with "$" representing the command shell prompt. The actual prompt varies from system to system. Don't actually type "$".

Sometimes there will be a great deal of output from an instruction. If there is nothing of particular interest in the output, it will be omitted and replaced with the text "SNIP".

There are useful third-party resources mentioned in this document. Those that are necessary for you to access in order to follow instructions are directly linked from the text. Others are marked as endnotes and the links are available in the Resources section.

# 3 Prerequisites

It is assumed that the user has already installed 4Suite according to the UNIX or Windows installation guide (a "HOWTO").

# 4 Repository and RDF Model Setup

The repository and the RDF model are distinct, yet integrated, components of 4Suite. For a description of them and information about why you might want to use them, see other 4Suite documentation.

Setup requires creating a configuration file, setting 1 or 2 environment variables, and running a command-line utility to initialize the repository and model.

The configuration file tells 4Suite what kind of database to use for both the repository and the model. Currently, two kinds of databases are supported:

- PostGreSQL ("Postgres") - This free, open-source database server is the preferred back end, and is very efficient. However, it can be difficult for inexperienced users to set up if they haven't managed a Postgres server before. In the interest of keeping this guide "quick", instructions for using Postgres for the repository are not provided here.

- The OS's native fileystem ("FlatFile") - This is the easier option, and requires nothing more than an empty directory and some disk space, but is slower than a Postgres-based system. Inexperienced users should experiment first with this option, just to get up and running, and later they can start anew with Postgres, if they wish.

## 4.1 Create the Configuration File

The repository and model are never accessed directly; all communication with them is done via a network server called the Controller, or "4ssd". This daemon listens on a certain port (8803, by default) and uses a custom RPC protocol ("FtRpc") for request/response communication.

The controller needs a configuration file to tell it what driver to use for accessing the database (FlatFile or Postgres), where the database is, where to put the log file, etc. Sample config files for Windows and Unix are provided in the appendices of this document, and they are also provided in the 4Suite distribution; on Unix look for {PYTHON_HOME}/.../4ss.conf, and on Windows look for C:\Python23\Share\Settings\4Suite\4ss.conf.

1. Use one of the sample configuration files in the appendices below, making adjustments to the LogFile and PidFile elements as necessary (set these to wherever you want the files to be created). Save the config on your system anywhere, under any name. We typically call it "4ss.conf", but the name really doesn't matter.

2. Now set the environment variable FTSERVER_CONFIG_FILE to be the full path to the file. For example, if you put the file at /usr/local/etc/4ss.conf, then that's what you'd set FTSERVER_CONFIG_FILE to. If you put it at C:\temp\4ss.conf, then use that. This environment variable must be set.

3. If you are using FlatFile (you probably are, since these directions don't tell you otherwise), then you may want to set the environment variable FT_DATABASE_DIR. This variable tells 4Suite where to look for the FlatFile databases, so set it to the directory where you want the files to be stored. If FT_DATABASE_DIR isn't set, then the default will be {python}/Ft/Share/Data/FlatFile.

## 4.2 Test the Command Line Tools

4Suite comes with a rich set of command-line tools for various repository management tasks. There are two primary commands, each with a number of subcommands, available to users:

1. 4ss_manager - interface to subcommands only available to the repository superuser/administrator. It is generally only used for creating the repository and controlling the servers. For a list of 4ss_manager subcommands, type:

         $  4ss_manager --help

2. 4ss - interface to general repository access subcommands. These won't work until the repository is created and a server is started to listen for access requests. You will do that in a minute. In the meantime, though, you can still see a list of subcommands:

         $ 4ss --help

For help with each subcommand, you can append --help to the end. Compare the output of each of these examples:

    $ 4ss --help
    SNIP
    $ 4ss fetch --help
    SNIP
    $ 4ss fetch document --help
    SNIP

## 4.3 Initialize the 4Suite Repository ("repo")

Now, from a command shell in which the FTSERVER_CONFIG_FILE environment variable has been set, run 4ss_manager init. See the sample output below.

A full initialization may take a while, because over 1000 items will be created in the repository, including over 600 XML documents comprising the API documentation for most 4Suite modules. While arguments can be supplied on the command line to force installation of only certain components, it is best, for purposes of this walkthrough, to have a standard, fully-initialized repo.

If FT_DATABASE_DIR wasn't set, you'll get an informational message about that. It's safe to ignore.

    $ 4ss_manager init
    You are about to initialize 4Suite Server. This will erase ALL DATA in the databases.
    Are you sure (yes/no)? y
    Add super user name (or just "enter" to pass): su
    Password: su
    Reenter password: su
    Add super user name (or just "enter" to pass):
    Installing Repository
    Create Container: /ftss
    Create Container: /ftss/users
    Create Container: /ftss/groups
    Create User: /ftss/users/h      docDef=None
    Create Group: /ftss/groups/super-users
    SNIP

Note: For "Are you sure" question - type y - and add a super user name - in this example su - and enter the desired password - in this example su - and just press "enter" when prompted to add another superuser.

## 4.4 Start the 4SS daemon ("4ssd" or "the controller")

Assuming the init was successful, the servers to interface with the repo can now be started! Type the following command:

    $ 4ss_manager start
    4SS Manager Name: su
    Password for su:
    controller started (pid 1064)

Note: You'll be again asked for user name and password. Use the super user name and the password that you created in the Initialize the 4Suite Repository ("repo") section, (i.e. from the previous example, the 4SS Manager Name would be su and Password would be su).

In the next section, we'll play around with some of these resources.

# 5 Test the Repository Access Tools

## 5.1 4ss fetch container

Seeing the contents of any container of the XML repository is quite simple. For example, to see the resources that were added by the 4ss_manager init type the following:

    $ 4ss fetch container /ftss
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:
    Listing of /ftss
    text/xml   0.3kB Nov 21 01:18   users
    text/xml   0.3kB Nov 21 01:18   groups
    text/xml   0.7kB Nov 21 01:18   docdefs
    text/xml   3.7kB Nov 21 01:18   data
    text/xml   1.7kB Nov 21 01:18   demos
    text/xml   6.9kB Nov 21 01:19   commands
    text/xml   4.0kB Nov 21 01:19   dashboard
    text/xml   1.3kB Nov 21 01:24   docs
    text/xml   0.5kB Nov 21 01:24   servers
    total: 9

Note that you had to log in. By default, one has to log in to use any command, which can get tedious. We shall soon see a way of avoiding this. For Host <localhost> and Port <8803> just press enter on those ones. 8803 is the port used by FtRpc.server, which allows the client to interact with the repository, i.e. the command line tools you're using right now.

The first field is the Internet Media Type (IMT). The second is the size of the file followed by the third, which is the date the resource was last modified. Finally, the last field is the name of the resource. Just a quick note, because everything is defined by an XML file, all the entries above except error.log display as text/xml Internet Media Type. All those entries are in fact containers. For command line help, type 4ss fetch container --help at the prompt.

## 5.2 4ss fetch document

You can display any of the documents by reference to their URI, relative to the root of the repository. The following command displays the XML document that represents the /ftss/users container:

    $ 4ss fetch document /ftss/users
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:
    Document /ftss/users (text/xml)
    ----------------------------------------
    SNIP

For another example, try 4ss fetch document /ftss/docs/COPYRIGHT.doc

For command line help, type 4ss fetch document --help at the prompt.

## 5.3 4ss create user

Just as in operating system operations, it is a bad idea to use 4Suite as a superuser except as necessary. One of the first things you should do is to create a regular user for typical operations.

    $ 4ss create user uo

    Note: After entering the new user's password, you might be prompted for a user
    name. This is a user name of an existing user in 4SS with permissions to create
    a new user.

    Enter new password for uo:
    Re-enter password:
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:

This creates a new user named "uo". The first two prompts are for the password of the new user. Then you are prompted for the superuser, whose privileges are required. For command line help, type 4ss create user --help at the prompt.

The 4ss fetch command can display various aspects of things in the repository. Compare the output of 4ss fetch user uo, 4ss fetch resource /ftss/users/uo, 4ss fetch rawfile /ftss/users/uo, and 4ss fetch document /ftss/users/uo.

## 5.4 4ss create container

It is useful to create a home container for this new user, a place where that user has permission to create, modify and delete. This must be done as superuser:

    $ 4ss create container /home
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:

    $ 4ss create container /home/uo
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:

There won't be any output from these commands, unless there was a problem.

For command line help, type 4ss create container --help at the prompt.

## 5.5 4ss set owner

Next we give the new user full ownership and permissions over this container. This must also be done as superuser:

    $ 4ss set owner /home/uo uo

There won't be any output from this command, unless there was a problem.

Note: in order to give other users and groups various permissions on this container (or any other resource), you would use the 4ss set acl command, which is discussed in Appendix B. You may not need to bother with this command in typical operation.

## 5.6 4ss create document

Now let us add an XML document to our brand new home container. Using whatever text editor is convenient, type in the following and save it as a file called profile.xml:

    <?xml version='1.0' encoding='UTF-8'?>
    <profile xmlns:V='http://www.w3.org/2001/vcard-rdf/3.0#'>
        <V:FN>Uchenna Ogbuji</V:FN>
        <V:N>
          <V:Family>Ogbuji</V:Family>
          <V:Given>Uchenna</V:Given>
        </V:N>
        <V:EMAIL>uche.ogbuji@fourthought.com</V:EMAIL>
    </profile>

Now type the following command to read profile.xml and store it in the repository in the /home/uo container:

    $ 4ss create document --type=xml /home/uo/profile.xml profile.xml
    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:

There won't be any output from this command, unless there was a problem.

Different types of documents are stored in different ways in the repository. The first option, --type, indicates the document type to use as a guide for this purpose, and is one of: xml, xslt, rdf, container, user, group, alias, xpathdocdef, xsltdocdef, or schematron. It's not strictly necessary; the type is inferred from the '.xml' suffix, but it's better to be specific.

The first argument after the --type option is a file name or URI of the file containing the data to add.

The second argument is the full path in the repository where you want the document to go. Any additional command-line arguments are optinoal and are interpreted as aliases to be assigned to the new resource. For more information, type in 4ss create document --help at the command line.

## 5.7 4ss agent

If you've been following along with these examples, you're probably quite tired of logging in over and over. You can avoid this by using two 4SS tools: 4ss login and 4ss agent. We'll focus on the latter. 4ss agent allows you to log in once, and creates a new command shell in which you don't even have to log in as that user.

    $ 4ss agent
    Username: uo
    Password:
    Host <localhost>:
    Port <8803>:
    Starting new shell: /bin/bash

Now you can execute commands, and the credentials for user "uo" will automatically be applied. For example, let us now examine the contents of the home container:

    $ 4ss fetch container /home/uo
    Listing of /home/uo
    text/xml   0.3kB Nov 21 03:47   profile.xml
    total: 1

You can see the document we added earlier, and the fact that it inherited its access control from the container, i.e. 4ss set acl to view the access controls. For more information, type in 4ss agent --help at the command line.

## 5.8 4ss create rawfile

The repository can also store plain files. For example, these might be images or downloadable files to be retrieved by browsers.

            $ 4ss create rawfile --imt=image/jpeg /home/uo/4SS.jpg 4SS.jpg
    $ 4ss fetch container /home/uo
    Listing of /home/uo
    text/xml   0.3kB Nov 21 03:47   profile.xml
    image/jpeg 4.0kB Nov 21 04:01   4SS.jpg
    total: 2

The "--imt" argument is the Internet Media Type of the new file, then the source file name is specified, then the destination in the repository. One or more aliases can be specified after this. For command line help, type 4ss create rawfile --help at the prompt.

# 6 Working with the Web features

4Suite comes with a built-in Web server system, which allows one to use XML and RDF features to deploy Web applications.

You can define multiple servers, each of which represents a distinct site to be served by 4Suite. Each server is usually on a separate port. 4Suite comes with 2 HTTP servers built in: one for the dashboard, which we shall discuss later in this document. The other is for the demo applications that come with 4Suite.

## 6.1 Setting up a scratch server

In order to develop and test 4Suite apps, or to deploy little Web pages that don't merit a dedicated server, we highly recommedn that you set up a scratch server. This is basically just a 4Suite server which you can partition as you like, and host pages and apps on as you like. The Web app examples in this document will all use the sratch server.

As a convenience, Appendix A features a Python program that asks a few questions and then sets up a scratch server for you. If you have access to the Web, you can just download it from http://uche.ogbuji.net/tech/4Suite/scratch-server.py. If not, just copy and paste from the listing. By the way, if you are a Python developer, you might find the contents of scratch-server.py a useful example of the Python API.

Run the script. When it prompts you to log in, you must do so as superuser.

    $ python tech/4Suite/scratch-server.py
    4SS superuser name: su
    Password for su:
    In the following prompts, just hit enter if the given defaults are OK.
    Name for the container to create [web]:
    Port on which to host the HTTP server [8080]:
    Brief name to identify the server [4ss]:
    Contact e-mail address to display in case of error [root@localhost]:
    $

Adding or changing server specifications may be recognized by the running repository after a certain delay, or not at all, depending on your configuration options. Just to be sure, you may want to run 4ss_manager restart.

# 7 4Suite Repository Dashboard

Now that you've played with some of the command-line tools, this section will show those similar set of commands in a visual environment called the 4Suite Repository Dashboard. Dashboard comprises of a GUI interface to manage servers, users, groups, repository and the configuration.

## 7.1 Let's get started!

Open up your web browser and type in the following URL: http://localhost:8800/

Note: This is provided you've followed the installation guide and have the 4ss_manager running. Use a web browser and check out localhost ports 8800 and 8801. For example, http://localhost:8800/ for Dashboard and http://localhost:8801 for Demos.

## 7.2 Repository

The default redirect is set to the 4Suite Repository container manager. You should see the following (provided that you followed the command-line examples in the quick-start guide, else you would only see the ftss container).

Notice the ftss and the home directories. Since we've been playing with the "home" container, let's continue with it. Click on "home" directory, where you should find "uo" directory. Click on "uo", and you should see two files, "4SS.jpg" and "profile.xml", that were added to the container from the previous command-line section. Now if you click on the "4SS.jpg" file, you'll be able to view the file, on the web browser, by clicking on the "View Raw File Data".

You should also be able to replace the file. For "profile.xml", you can edit the document in the "Editing Content" area or view the document in the browser by pressing "View XML Document Data" button.

In the change directory field, type in /home/uo/ and press the "Change Directory" button.You should be able to add new resources by selecting the type (pull down menu) and clicking on the "Add Resource" button. You'll be taken to a page where you have the option of editing a file or browsing for the file. But you'll have to provide the name of the file for the repository, i.e. a local name, otherwise you'll get a randomly generated reference name for the file.

## 7.3 Brief overview of rest of the Dashboard features:

- Server Manager:

  Server manager allows a convenient way to edit server xml file.

- User Manager:

  Users name and passwords can be edited via the User Manager. Notice the usernames "su" and "uo" that you created in the previous section.

- Group Manager:

  You can edit, add, and remove members from a group.

- Configure:

  The configuration screen allows you to configure certain aspects of Dashboard. The temporary workspace entry allows you to define a directory on your local machine where GraphViz (refer to the installation guide for more information) will put its output files. The 'dot' executable directory is the directory where the GraphViz executable is located. The 'Default Manager' option allows you to determine whether or not to view XML based resources using their special managers or to use the generic raw-file manager (in this case to modify the XML content directly). The 'Display icons' option determines whether or not to show icons of container children in the container-manager. Finally, the last option allows the user to determine whether or not to rotate RDF visualizations by 90 degrees, which is helpful for very large graphs, which tend to be wider than they are tall.

# 8 Resources

## 8.1 4Suite @ SourceForge

4Suite Project Page - Bug Reports, Feature Requests, Patches

## 8.2 External Links

4suite.org - Documentation, Downloads, News, CVS, Developer Resources

4Suite Users Mailing List - Peer & Developer Support

4Suite Announcement Mailing List - Infrequent Announcements about 4Suite

Fourthought, Inc. - Commercial Development, Consulting & Support

# A Sample 4Suite server config file for Windows

    <?xml version='1.0' encoding='UTF-8'?>
    <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
      xmlns='http://xmlns.4suite.org/4ss/properties#'
      xml:base=''
    >
      <Core rdf:ID='Core'>

        <SystemContainer>ftss</SystemContainer>

        <!-- Use filesystem for repository -->
        <Driver rdf:parseType='Resource'>
          <rdf:type resource='http://xmlns.4suite.org/4ss/properties#FlatFile'/>
          <Root>xmlserver</Root>
        </Driver>

        <!-- Use PostGreSQL for repository -->
        <!-- User, Password, Host, Port are optional -->
        <!--
        <Driver rdf:parseType='Resource'>
          <rdf:type resource='http://xmlns.4suite.org/4ss/properties#Postgres'/>
          <DbName>xmlserver</DbName>
          <User>dbusername</User>
          <Password>dbpwd</Password>
          <Host>dbhost</Host>
          <Port>dbport</Port>
        </Driver>
        -->

        <!-- Controller PID and log file locations -->
        <PidFile>C:/Devel/tmp/4ss.pid</PidFile>
        <LogFile>C:/Devel/tmp/4ss.log</LogFile>

        <!-- Controller log level (optional; default: notice) -->
        <!-- one of emerg|crit|error|warning|notice|info|debug -->
        <LogLevel>debug</LogLevel>

      </Core>
    </rdf:RDF>

Some notes about the above --

Capitalization is important! The most common error is a mistyped URI or element name.

There must be only one Driver element. This element tells 4Suite whether to use FlatFile or Postgres, and provides additional configuration info specific to that database driver. So if you enable the Postgres Driver, be sure to comment out the FlatFile one.

The content of the Root element is the name of a subdirectory of the directory specified in the FT_DATABASE_DIR environment variable. It will be created if it doesn't exist.

The PidFile and LogFile can be any local file path, and do not have to exist. The directories they are in must exist and be writeable, though. If the LogFile already exists, it will be appended to.

Leave LogLevel at 'debug' while getting started or when just experimenting. On a production server, we recommend 'notice', to cut down on disk writes.

# B Sample 4Suite server config file for Unix

    <?xml version='1.0' encoding='UTF-8'?>
    <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
      xmlns='http://xmlns.4suite.org/4ss/properties#'
      xml:base=''
    >
      <Core rdf:ID='Core'>

        <SystemContainer>ftss</SystemContainer>

        <!-- Use filesystem for repository -->
        <Driver rdf:parseType='Resource'>
          <rdf:type resource='http://xmlns.4suite.org/4ss/properties#FlatFile'/>
          <Root>xmlserver</Root>
        </Driver>

        <!-- Use PostGreSQL for repository -->
        <!-- User, Password, Host, Port are optional -->
        <!--
        <Driver rdf:parseType='Resource'>
          <rdf:type resource='http://xmlns.4suite.org/4ss/properties#Postgres'/>
          <DbName>xmlserver</DbName>
          <User>dbusername</User>
          <Password>dbpwd</Password>
          <Host>dbhost</Host>
          <Port>dbport</Port>
        </Driver>
        -->

        <!-- Controller PID and log file locations -->
        <PidFile>/tmp/4ss.pid</PidFile>
        <LogFile>/tmp/4ss.log</LogFile>

        <!-- Controller log level (optional; default: notice) -->
        <!-- one of emerg|crit|error|warning|notice|info|debug -->
        <LogLevel>debug</LogLevel>

      </Core>
    </rdf:RDF>

Some notes about the above --

Capitalization is important! The most common error is a mistyped URI or element name.

There must be only one Driver element. This element tells 4Suite whether to use FlatFile or Postgres, and provides additional configuration info specific to that database driver. So if you enable the Postgres Driver, be sure to comment out the FlatFile one.

The content of the Root element is the name of a subdirectory of the directory specified in the FT_DATABASE_DIR environment variable. It will be created if it doesn't exist.

The PidFile and LogFile can be any local file path, and do not have to exist. The directories they are in must exist and be writeable, though. If the LogFile already exists, it will be appended to.

Leave LogLevel at 'debug' while getting started or when just experimenting. On a production server, we recommend 'notice', to cut down on disk writes.

# C Scratch Server set-up tool

    import sys, sha, getpass
    import posixpath
    from Ft.Server.Client import FtServerClientException
    from Ft.Lib import Uri
    from Ft.Server.Common import ResourceTypes, AclConstants
    from Ft.Server.Client import Core
    from Ft.Server.Client import SmartLogin

    def Run():
        print "At the following prompts, just hit enter if the given defaults are OK."
        server_file = raw_input("Path of the server file to create [/scratch/server.xml]: ")
        if not server_file: server_file = '/scratch/server.xml'
        server_port = raw_input("Port on which to listen for HTTP requests [8080]: ")
        if not server_port: server_port = '8080'
        server_name = raw_input("Brief name to identify the server [scratch-server]: ")
        if not server_name: server_name = 'scratch-server'
        contact = raw_input("Contact e-mail address to display in case of error [root@localhost]: ")
        if not contact: contact = 'root@localhost'
        server_doc = SERVER_FILE%locals()

        try:
            try:
                commit = 0
                #Get the repository by logging in
                repo = SmartLogin()
                container = posixpath.split(server_file)[0]
                cont = repo.createContainer(container, 1)
                cont.setAcl(AclConstants.WRITE_ACCESS,
                            AclConstants.USERS_GROUP_NAME, AclConstants.ALLOWED)
                cont.setAcl(AclConstants.READ_ACCESS,
                            AclConstants.USERS_GROUP_NAME, AclConstants.ALLOWED)
                cont.setAcl(AclConstants.READ_ACCESS,
                            AclConstants.WORLD_GROUP_NAME, AclConstants.ALLOWED)
                doc = repo.createDocument(
                    server_file, server_doc, imt='text/xml', docDef=None,
                    forcedType=ResourceTypes.ResourceType.SERVER)
                commit = 1
            finally:
                try:
                    if commit:
                        repo.txCommit()
                    else:
                        repo.txRollback()
                except:
                    pass

        except FtServerClientException, e:
            print e

    SERVER_FILE = """\
    <Server xmlns="http://xmlns.4suite.org/reserved"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
    >
      <dc:Description>Scratch server</dc:Description>
      <Status running='1'/>
      <Module>Http</Module>
      <Handler>http_basic</Handler>
      <Port>%(server_port)s</Port>

      <!-- contact information -->
      <ServerAdmin>%(contact)s</ServerAdmin>
      <ServerName>%(server_name)s</ServerName>

      <!-- logging -->
      <LogLevel>notice</LogLevel>

      <DocumentRoot>/</DocumentRoot>
    </Server>
    """

    if __name__ == "__main__":
        Run()

# D Using 4ss set acl interactively

Then give the new user full permissions over this container.

Note: ACL stands for access-control list. An access control list limits the operations possible on the resource. For each resource, there is a set of users and groups that can perform each of the operations. There are six operations currently: Read, Write, Execute, Delete, Change Permissions, and Change Owner.

    $ 4ss set acl /home/uo

    4SS User Name: su
    Password for su:
    Host <localhost>:
    Port <8803>:
    Current ACL Settings for: /home/uo
    Read ACL
      owner --> allowed
      world --> allowed
      super-users --> allowed
    Write ACL
      owner --> allowed
      super-users --> allowed
    Execute ACL
      owner --> allowed
      world --> allowed
      super-users --> allowed
    Delete ACL
      owner --> allowed
      super-users --> allowed
    Change Permissions ACL
      owner --> allowed
      super-users --> allowed
    Change Owner ACL
      owner --> allowed
      super-users --> allowed

Here, you'll be asked to enter a command. These commands allows you to change the above list of ACL permissions, i.e. Read ACL has super-users, world, and owner with the access permission of allowed to the /home/uo container. You'll see how to modify these permissions in the examples below.

- set - to completely replace existing specific ACL permission with a new set you specify

  For example, if you wanted to set permission of Write ACL to "uo", then type "s".

  Enter the type of access as write and the username to set as "uo".

  The others super-users and owners (that you can see above) will be replaced by "uo".

  Then only "uo" will have permission to write to that container, in this case /home/uo.

- add - to add additional users to a specific ACL permissions list

  For example, if you wanted to add user "uo" to the Write ACL, then type "a" and enter the type of access as write and the username to set as "uo". "uo" will be added to the existing list of users.

- remove - to remove users from a specific ACL permissions list

- quit and save - to exit the command and save the changes to ACL that you've made

- exit without save - exits and restores previous ACL setting

    Please enter a command:
    (s)et
    (a)dd
    (r)emove
    (q)uit and save
    (e)xit without save
    >> s

    Type of access: read | write | execute | delete | change owner | change
    permissions

    Please enter the type of access: write
    Please enter the ident (i.e. username) to set: uo
    Should uo be allowed write on /home/uo (yes/no): y
    Current ACL Settings for: /home/uo
    Read ACL
      super-users --> allowed
      world --> allowed
      owner --> allowed
    Write ACL
      uo --> allowed
    Execute ACL

    SNIP

    Please enter a command:
    (s)et
    (a)dd
    (r)emove
    (q)uit and save
    (e)xit without save
    >> q

This allows any user to read the contents of the container, but only user "uo" can modify, or add contents to the container. To add more permissions (such as delete), you would simply continue with the above example (instead of (q)uit, press (s)et and enter type of access as delete. For command line help, type 4ss set acl --help at the prompt.