User Tools

Site Tools


info:devel:architecture

Introduction to the Sausalito Architecture

Objectives

After completing this module, you should be able to:

  • Explain the Sausalito software architecture design goals
  • Create and extend object schemas
  • Use the Sausalito cceclient utility to activate systems changes from the command line
  • Analyze Cobalt Configuration Engine (CCE) server log files
  • Explain the contents of the /usr/sausalito directory tree
  • Extend the Server Desktop with menu items, options, and pages
  • Create languages for the Server Desktop using the 118n component
  • Create and implement a new Server Desktop style

Additional Resources

Additional resources ‐ The following reference provides additional details on the topics discussed in this module:

What Is Important in This Module?

This module describes the Sausalito architecture and how to use it to extend the server appliance’s out‐of-the-box service features. The major topics in this module are:

  • Sausalito Architecture Overview
  • Sausalito Software Architecture
  • SET Transaction Overview and Components 1 SET Transaction Configuration
  • Registering an Event Handler
  • CSCP Communication
  • GET Transactions
  • Server Desktop Screen Generation
  • Navigation Sub‐system Overview
  • Internationalization (i18n)
  • User Interface Foundation Classes (UIFC)

As you read this module, look for answers to the following questions. See Appendix A for answers.

  1. What is the Sausalito software architecture designed to provide?
  2. What are the Sausalito processes?
  3. What are the main components of CCE?
  4. What are SET transactions and how are they triggered?
  5. What is the purpose of the Cobalt System Configuration Protocol?
  6. How is an Event Handler registered?
  7. What are GET transactions?
  8. What is the purpose of the Navigation sub-system?
  9. What is the function of Internationalization (i18n)?

Overview

Sausalito is the name of the Sun Cobalt Qube 3 Plus server appliance’s software architecture, which is designed to provide an extensible development platform that enables third parties to customize and modularize the platform and quickly implement services, applications, and languages.

Having a clear understanding of Sausalito is helpful for maintaining the server appliance. This module describes the Sausalito architecture and the process for extending the server appliance’s out-of-the-box service features.

Figure 17-1 shows that the Sausalito software layer lies between the Server Desktop, applications, and the Linux operating system.

FIXME: Add a diagram here Sausalito on the server appliance platform layers

Sausalito Handles System Changes

Sausalito handles operating system modifications, such as creating, deleting, and modifying users and groups. Sausalito also handles requests for changing system functionality, such asenabling SMTP, CGI scripts, and Microsoft FrontPage server extensions. Having Sausalito handle these requests helps hide the complexities of the operating system from the end user.

Sausalito’s fully open Application Programming Interface (API) allows programmers to seamlessly integrate additional applications, giving them the look and feel of the server appliance.

Object-Oriented Programming

Sausalito is based on object-oriented programming; everything in the system is an object that can be added, removed, changed, and extended. Object-oriented programming helps Sausalito live up to its goal of extensibility.

Figure 17‐2 shows a block diagram of the Sausalito software architecture. This diagram expands later in this module to Show more details about Sausalito’s components and process flow.

FIXME: Add a diagram here Sausalito software architecture block diagram

Sausalito's Two Main Processes

Sausalito can be broken down into two main processes: SET transactions and GET requests. These t w o processes let you manipulate the system software through the Server Desktop, while keeping the system software and Server Desktop logically separate. Figure 17-3 shows the major Sausalito components and the process flow for the two main processes.

FIXME: Add a diagram here Sausalito components and process flow

Cobalt Configuration Engine

The main component of Sausalito is the Cobalt Configuration Engine (CCE), which is responsible for both SET transactions and GET requests. CCE is designed to act as a buffer between the system and the Server Desktop to keep the two logically separate.

CCE has several components:

  • The Cobalt Object‐oriented Database (codb)
  • The Cobalt System Configuration Protocol (CSCP)
  • Event handlers

CCE maintains the configuration state of Sausalito by:

  • Initiating event handlers to change the state of the system
  • Changing codb information
  • Delivering information from codb to the Server Desktop

SET Transaction Overview

This section provides an overview of the SET transaction process and components and their functions within Sausalito,

SET transactions are system changes performed by event handlers registered to objects or object properties being created, deleted, or modified. SET transactions are triggered by user input, such as:

  • Adding a new object such as a user or group, or
  • Modifying an existing object’s properties, such asenabling or disabling a service or modifying user information

Then the event handlers registered to the object or the object properties are executed.

The CCE Daemon

The CCE daemon (coed) listens on the cced.socket , which is a standard UNIX socket, and handles incoming connections and signals from the CSCP. The CCE daemon is the administrator of Sausalito: It initiates event handlers based on change requests and commits changes to codb, when applicable. When you check the system processes on the server appliance, you should see the cced process running. Figure 17‐4 shows the cced responsibilities:

FIXME: Add a diagram here The cced responsibilities

Cobalt Object-Oriented Database

In object-oriented programming, everything is an object. Objects have properties that contain values. For example, users and groups have names and disk quotas have sizes. In codb, the System object has properties for the server appliance’s services. For example, the FTP service has a maximum-number-of-connections property, a maximum-number-of‐ megabytes-per-transfer property, and other properties.

Figure 17‐5 shows a c o d b object expanded. Objects in codb are identified by numbers. Each object has a CLASS property that designates the type of the object (user, group, system, or network route, among others) and several other properties that contain configurable information. c o d b objects can be extended with additional properties.

FIXME: Add a diagram here The codb with an expanded object

codb is a holding tank for objects and their property values. The information stored in codb is what is retrieved by CCE and viewed through the Server Desktop. For example, a user is an object and that user object has property values that include user name,full name, maximum disk space, email aliases, and other properties. These object property values display in the Server Desktop when you View a specific user’s details.

Cobalt System Configuration Protocol

CSCP is a simple protocol used for communicating between clients and CCE, and between CCE and the event handlers. CSCP is the only mechanism by which CCE knows what actions to take. CSCP communicates requests from the client to CCE, and it communicates requests from CCE to the event handlers when system and service configuration files need to be added, removed, or modified. After the event handlers complete their work, either successfully or unsuccessfully, CSCP reports back to CCE with the status. Figure 17-6 shows the function of CSCP in Sausalito for handling the communication between requesting clients and CCE and between CCE and the event handlers.

FIXME: Add a diagram here CSCP functions in Sausalito

Event Handlers

Event handlers are executable scripts that are triggered by CSCP. They have specific functions for changing system state, and registering services and applications. Services and applications register themselves in CCE by requesting notifications when specific codb objects and object property values are added, removed, or modified.

When these notifications take place, the event handlers make the changes to the system and report back, using CSCP, to CCE with the success or failure status.

Event handlers make it possible for software developers to apply changes to the system without affecting existing functionality, as long as guidelines are followed for adhering to the modularity of Sausalito. Figure 17-7 shows how the event handlers in Sausalito handle changes to the system and configuration files.

FIXME: Add a diagram here Event Handler functions in Sausalito

Table 17‐1 on page 17‐13 shows an overview of the process flow for SET transactions:

FIXME: Add a diagram here

SET Transaction Configuration

Before SET transactions can take place in Sausalito, the system must be configured to recognize requested changes and system changes that must be made. This means:

  • Objects and object properties need to be defined
  • Event handlers need to be created and registered to the objects and object properties

Objects and object properties need to be defined for program packages, such as Apache, Proftpd, Active Monitor, Sendmail, and others. Then the objects and object properties need to be registered with the event handlers.

Note ‐ When an object is added, deleted, or modified, the event handlers registered to that object or that object’s properties are notified to make the necessary system changes.

Defining Objects and Object Properties

The structure of objects within codb is defined by schema definition files. These definition files provide schema, class, property, and typedef information.

At system startup, the definition files are read; they define what objects can be created, the properties the objects can have, and the data type the object properties can contain. The schema definition files are located in the /usr/sausalito/schemas/base/service‐type directories.

When cced is started, all files with a .schema file extension under the /usr/sausalito/schemas directory tree are used to build the object schemas.

The /usr/sausalito/schemas/base/service‐name directories are strictly for organization. If you have installed third-party applications, you might also find /usr/sausalito/schema/vendor‐name directories that contain schema definition files.

Table 17-2 contains the schema file elements and attributes discussed in this course. For a complete listing and description of the schema file elements and attributes, see the Sun Cobalt QubeTM 3 Developer’s Guide, which is referenced in “Additional Resources” on page 17‐2.

ElementAttributesDescription
classNameName of the class being defined or extended
versionVersion number for the class structure
namespaceOptional name of the class structure
PropertyNameNameof the property
typeData type of the property
defaultDefault value for the property
optionalDefines whether the property can be an empty string(“”) or a valid fact used to make a decision
arrayDefines whether the property is an array of the specified type, can be any string, or is unspecified
typedefnameSymbolic name for t y p e
typeValidation class for typedef
dataData validator: re = regular expression and extern = path to external program
errmsgError message returned by CCE

Schema File Example

The following is an example of a fairly simple definition file that extends the System object with an FTP name space that has two properties: enabled and maxconnections. This file is written in XML.The first seven lines are comments that are opened by <! ‐‐ and closed by ‐‐>.

<! --
        $Id: ftp.schema
        Copyright 2000, 2001 Sun Microsystems, Inc.  All rights reserved.
        Author: asun@cobalt.com
 
        This provides the schema for ftp.
-->
 
<class name="System" namespace="Ftp" version="1.0">
        <property
        name="enabled" type="boolean" default="0"
        writeacl="ruleCapable(serverFTP)"
    />
</class>

In line9,class name=“System” extends the System object with a new name space.

In line 10 and 11, the properties are defined for the System.Ftp object and name space. The enabled property has its type set to boolean and its default value set to true . The maxConnections property has its type set to integer (type=“int”) and its default value set to 25.

Type Definitions

Type definitions define what type of data is allowed for a certain property. For example, s c a l a r data is used for full user names; it allows first and last names to be any combination of letters, numbers, and white space.

If you have installed third-party software applications, you might find more type definitions defined in the /usr/sausalito/schemas directory. Table 17-3 on page 17-17 lists the server appliance type definitions (typedef),defined in the /usr/sausalito/schemas/basetypes.schema file.

Table 17-3 … Server appliance type definitions and descriptions

TypedefDescription
scalarZero or more characters of any value
wordOne or m o r e non-whitespace characters
alphanumOne or more alphanumeric characters
intA positive integer; any integer except zero preceded by an optional unary minus (negative) sign, or zero
uintAn unsigned integer, which c a n be any positive integer greater than or equal to zero
booleanA logical TRUE or FALSE; an empty string(“”) Or,the value zero, which is a logical FALSE, and any other value, which is a logical TRUE
ipaddrA set of four integers between 0 and 255 separated by periods, for example, 192.168.1.254
networkA network number, such as 10.9.0.0/16
emailaddrThe address of anemail user; for example, harry@suncobalt.com
netmaskA number from 1 to 32, or a dot‐quadded IP mask
fqdnA fully qualified domain name; for example, www.suncobalt.com
hostnameA non-period hostname;for example, www or smtp
domainnameA fully qualified domain name or a domain name; for example, www.suncobalt.com or suncobalt.com
passwordScalar data, masked in cced logs

Exercise: Extending an Object’s Schema

In this exercise you add functionality to your FTP server. The feature you add and make available to the admin user through the Server Desktop is root user access feature. This feature is disabled by default by the Proftpd application. Extending the schema is the first part of the process to add this feature to the Server Desktop. You extend the schema of the System object by addinga FtpRootLogin name space with an enabled property.

Tasks

Complete the following steps to set up a directory structure for your FTP feature:

1. Open a telnet window and change to the /usr/sausalito/schemas directory, create new directory using your_first_name/ftp and then change to that directory:

# cd /usr/sausalito/schemas
# mkdir -p your_first_name/ftp
# cd your_first_name/ftp

2. Copy the ftp.schema file from the server‐appliance-specific directory to your current directory and rename the file to ftproot.schema:

# cp /usr/sausalito/schemas/base/ftp/ftp.schema ftproot.schema

Complete the following steps to create and edit your new schema file:

1. Open the ftproot.schema file editing and switch to insert mode:

# vi ftproot.schema 
i

2. On the line that starts with <class name=“System”, change Ftp to FtpRootLogin.
3. On the line that starts with <property name=“enaabled”, change true to 0.
4. Switch to command mode by pressing the Escape key.
5. Move the cursor down one line and remove the line:

dd

Your final results should look like this, after the initial file comments:

<class name="System"namespace:"FtpRootLogin" version="l.0">
  <property name="enabled" type="boolean" default="0"/>
</class>

6. Save and close the file.

:wq

Complete the following steps to restart the CCE server, making the newname space and property available. Then, check for errors:

1. Check for errors by restarting CCE and then make sure CCE restarted:

# /etc/rc.d/init.d/cced.init restart
Shutting down cced: done
Starting cced: cced
Running CCE constructors:
# ps -e | grep cced
8584 ? 00:00:00 cced
#

If you do not receive a similar result as above, make sure the syntax in your ftproot.schema file is correct.

Registering an Event Handler

To register an event handler with the system, create an event handler configuration file with a .conf extension. The .conf file must contain the information that defines the class, name space, and properties for the object to which you want the event handler to be registered. Then, if the object is modified, the event handler will be triggered and make the necessary changes to the operating system. The . conf file must also contain the path to the executable script that is the event handler itself.

The .conf file can beplaced anywhere under the /usr/sausa1ito/conf directory tree. This makes it possible for third-party software developers to create their own /usr/sausalito/conf/vendor‐name directories, in which they can store their .conf files.

CCE finds all the .conf files in the /usr/sausalito/conf directory and subdirectories; however, all file names that begin with a period are ignored.

Event Handler File Format

The .conf file format is simple and can contain several lines with three fields per line. For example:

ClassEvent           Handler definition(File path)            Execution stage

ClassEvent

Class.Event is a string of text that defines:

  • An object
  • An optional n a m e space
  • A property or an object
  • An optional name space (optional)
  • An event based on the events listed in Table 17-4

Table 17-4 Valid class events

EventDefinition
_CREATEWhen an object of the specified class is created
_DESTROYWhen an object of the specified class is destroyed
propertynameWhen the specified property of the specified class is changed
*Wildcard, which means when any property of the specified class or class .namespace is changed

Handler Definition

The handler definition is the path to the eventhandler’s executable script. This path is preceded by either perl: or exec:. The perl: text causes CCE to use a persistent Perl daemon, thereby expediting the execution request. The exec: text executes the script or binary.

Execution Stage

The execution stage allows the handler writer to suggest a relative order for event handler execution. The following five defined, case-sensitive execution stages are listed in priority from highest to lowest:

  • VALIDATE
  • CONFIGURE
  • EXECUTE
  • TEST
  • CLEANUP

If the execution stage is not specified, the event handler is in the EXECUTE stage. Relative ordering between stages is guaranteed, but ordering within a given stage is not.

Example: Event Handler Configuration File

The following /usr/sausalito/conf/ftp/ftp.conf file is provided as an example. When any of the properties are modified on the System.Ftp.* or System.FileShare.* object and name space,the /usr/sausalito/handlers/base/ftp/system.pl script is executed to handle the request.

This file also controls the script for enabling anonymous FTP, and for enabling and disabling FTP service monitoring using the Active Monitor.

# $Id: ftp.conf,v 1.10 2000/09/15 01:03:54 thockin Exp $
# handlers for ftp
#
System.FileShare.*        perl:/usr/sausalito/handlers/base/ftp/guest.pl
System.Ftp.*              perl:/usr/sausalito/handlers/base/ftp/system.pl
ActiveMonitor.FTP.enabled perl:base/am/am_enabled.pl EXECUTE
ActiveMonitor.FTP.monitor perl:base/am/am_enabled.pl EXECUTE
System.Ftp.enabled        perl:base/ftp/enableAM.pl

Exercise: Creating and Registering an Event Handler

In this exercise you continue the process started in “Exercise: Extending an Object’s Schema” on page 17‐18. There, you extended the properties of the FTP server by adding the FTP root user access feature though the Server Desktop. Now complete the tasks of creating the event handler configuration file and writing the executable script for modifying the FTP server configuration file.

Tasks

Complete the following steps to create the event handler configuration file:

1. Open a telnet window and change to the /usr/sausalito/conf directory, create new directory using your_first_name/ftp and then change to that directory:

# cd /usr/sausalito/conf
# mkdir ‐p your_first_name/ftp
# cd your_first_name/ftp

2. Open for editing a ftpRootAccess.conf file and switch to insert mode:

# vi ftpRootLogin.conf
i

3. Add the following text(use a tab for the space between enabled and perl):

# handler for ftp root login
#
Systam.FtpRootLogin.enabled     perl:/usr/sausalito/handlers/your_first_name/ftp/rootLogin.pl

Make sure you replaced the your_first_name, with your real first name!

4. Switch to command mode by pressing the Escape key.

5. Save and close the file:

:wq

Complete the following steps to write the executable event handler Perl script for adding the root access directive to the FTP server configuration file:

1. Change to the /usr/sausalito/handlers directory, create new directory using your_first_name/ftp and then change to that directory:

# cd /usr/sausalito/handlers
# mkdir ‐p your_first_name/ftp
# cd your_first_name/ftp

2. Open for editing a rootLogin.pl file and switch to insert mode:

# vi rootLogin.pl
i

3. Insert the following text exactly as shown into the file. Use the Tab key to indent lines. It might take several attempts to get the text exactly right, so take your time.

Note ‐ This script is written to be streamlined and it does not follow good programming syntax guidelines for providing comments about the script’s use.

#!/usr/bin/perl -w -I/usr/sausalito/perl -I.
# System.FtpRootLogin.enabled modify handler
use strict;
use Sauce::Config;
use Sauce::Util;
use CCE;
 
my $cce = new CCE;
$cce->connectfd();
 
my $oid = $cce>event_oid() ;
my($ok, $obj) = $cce>get($oid, 'FtpRootLogin');
if (!$oid) {
        $cce>bye('FAIL');
        exit(1);
}
 
#
my $enabled = $obj>{enabled} ? "on" : "off";
 
my $fun = sub {
        my ($fin, $fout) = (shift, shift);
        my $found = 0;
        my $conf = "RootLogin\t\t\t$enabled\n";
        while (defined($_ = <$fin>)) {
                if(/^\s*RootLogin/) {
                        print $fout $conf;
                        $found = 1;
                } else {
                        print $fout $_;
                }
        }
        print $fout $conf unless ($found);
        return 1;
};
my $ret = Sauce::Util::editfile("/etc/proftpd.conf", $fun);
if ($ret) {
        $cce->bye('SUCCESS');
        exit(0); 
} else {
        $cce>bye('FAIL');
        exit(1);
}

4. Switch to command mode by pressing the Escape key.

5. Save and close the file:

:wq

6. Execute the file at the command line to test the syntax:

# perl -cw rootLogin.pl
rootAccess.pl syntax OK

The ‐cw option tells Perl to compile, but not execute, the program and to display warnings about errors.

If you receive warnings, check the contents of the rootAccess.pl file and make any necessary changes until you receive no more warnings.

7. Restart CCE:

# /etc/rc.d/init.d/cced.init restart
Shutting down cced: done
Starting cced: cced
Running CCE constructors:
#

CSCP Communication With CCE

Communication to CCE is done through CSCP and there are two modes of communication: client mode and handler mode. The handler mode has more commands than the client mode.

CCE Communication Modes

CSCP is shown in Table 17-1 on page 17-13. CSCP is used in the handler mode for communication between CCE and the event handlers; it is also used for communication between CCE and the Server Desktop.

CSCP is used in the client mode to establish a direct connection to CCE. To establish a direct connection to CCE, the cceclient utility is executed from the command line: /usr/sausalito/bin/cceclient. Table 17-5 lists the commands used for both client and handler CCSP communication modes.

Table 17-5 The client and handler mode commands

CommandDescription
authAuthenticates asa user to get that user's access privileges (starts a new session)
authkeyAuthenticates to an already existing session
endkeyExpires the current sessionid
whoamiReturns the oid (Object Identification) of the currently authenticated user
byeCloses the connection
commitTriggers any postponed handler activity
createCreates a new object of a certain class
destroyDestroys an object
findFinds all objects that match a given criteria
getGets all properties for a certain object or object name space
namesLists name spaces associated with a Class
classesLists all classes
setSets the properties of a certain object

Table 17-6 contains additional commands that are available in the handler mode when the CCE is communicating with an event handler:

Table 17-6 Additional Handler Mode Commands

CommandDescription
baddataReports that an unrecognized attribute or value was passed
infoReports a piece of information
warnReports a warning or error

CCE Response Codes

For every command given to CCE, a response code is returned. These response codes consist of a numeric code and a set of arguments. The value of the first digit of the numeric code defines whether the message is an informational message (1), a success message (2), a warning message (3), a failure message (4), or a system-issued message (9). Table 17‐7 describes the response types.

Table 17-7 CCE Response Codes

Numeric code rangeType of response
100-199Informational
200-299Success
300-399Warning
400-499Failure
900-999System~issucd message (which can be sent at any time)

Exercise: Testing Systems Changes From cceclient

In this exercise you test the new feature added to the FTP server for root login access. This test must be successful before you extend the Server Desktop with new menu items.

Tasks

Complete the following steps to determine the object number for the System object and test the FTP server changes performed by the event handler:

1. In telnet, communicate to CCE using the cceclient utility and find the number for the System object:

# /usr/sausalito/bin/cceclient

 100 CSCP/O.80

200 READY
find system
104 OBJECT 1
201 OK

2. Open another telnet session and list the /etc/proftpd.conffile contents:

# cat /etc/proftpd.conf

Notice that no RootLogin directive is listed in the file.

3. In the first telnet session that has cceclient running,for the System object (object 1), set the FtpRootLogin name space’s enabled property to 0. (Zero equals off.)

set 1.FtpRootLogin enabled="0"
201 OK

4. In the other telnet session, list the /etc/proftpd.conf file:

# cat /etc/proftpd.conf

Notice the last line of the file reads RootLogin off

5. Try to log in to the FTP server as root and exit:

# ftp localhost
Connected to localhost.
220 ProFTPD 1.2.0 Server (ProFTPD)
[www.server_appliance.com]
Name (localhost:admin): root
331 Password required for root.
Password: your_password
530 Login incorrect.
Login failed.
ftp> exit

Notice the Login Failed.

In the telnet window that has cceclient running, set the System object’s FtpRootLogin name space’s enabled property to 1.(One equals on.)

set 1.FtpRootLogin enabled=”1"
201 OK

7. In the other telnet session, list the /etc/proftpd.conf file:

# cat /etc/proftpd.conf

Notice that the last line of the file reads RootLogin on

8. Log in to the FTP server as root and exit:

# ftp localhost
Connected to localhost.
220 ProFTPD 1.2.0 Server (ProFTPD)
[www.server_appliance.com]
Name (localhostzadmin): root
331 Password required for root.
Password: your_password
230 User root logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> exit

Notice the 230 User root logged in.

info/devel/architecture.txt · Last modified: 2015/07/26 12:35 by