To initialize the 4Suite repo, type the following command:

$ 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.

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.

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 Initializing 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.

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.

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.

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.

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.

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.

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 profle.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:

$ 4ss create document --type=xml file:profile.xml /home/uo/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.

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.

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 4SS.jpg /home/uo/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.