wiki.blueonyx.it

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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:
  * [[info:devel:devguide|The Blueonyx Developer’s Guide]]
  * [[info:devel:building|How to setup a Blueonyx development environment]]
  * For more information on PHP the widely-used, general-purpose scripting language that is especially suited for Web development and can be embedded into HTML see: http://www.php.net/PHP
  * For more information on gettext' utilities which are a set of tools that provides a framework to help produce multi-lingual messages http://www.gnu.org/software/getteXt/gettext.html
===== 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.

  - What is the Sausalito software architecture designed to provide?
  - What are the Sausalito processes?
  - What are the main components of CCE?
  - What are SET transactions and how are they triggered?
  - What is the purpose of the Cobalt System Configuration Protocol?
  - How is an Event Handler registered?
  - What are GET transactions?
  - What is the purpose of the Navigation sub-system?
  - 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.

^Element^Attributes^Description^
|class|Name|Name of the class being defined or extended|
|:::|version|Version number for the class structure|
|:::|namespace|Optional name of the class structure|
|Property|Name|Nameof the property|
|:::|type|Data type of the property|
|:::|default|Default value for the property|
|:::|optional|Defines whether the property can be an empty string("") or a valid fact used to make a decision|
|:::|array|Defines whether the property is an array of the specified type, can be any string, or is unspecified|
|typedef|name|Symbolic name for t y p e|
|:::|type|Validation class for typedef|
|:::|data|Data validator: re = regular expression and extern = path to external program|
|:::|errmsg|Error 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 ‐‐>.

<code xml>
<! --
        $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>
</code>

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
^Typedef^Description^
|scalar|Zero or more characters of any value|
|word|One or m o r e non-whitespace characters|
|alphanum|One or more alphanumeric characters|
|int|A positive integer; any integer except zero preceded by an optional unary minus (negative) sign, or zero|
|uint|An unsigned integer, which c a n be any positive integer greater than or equal to zero|
|boolean|A 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|
|ipaddr|A set of four integers between 0 and 255 separated by periods, for example, 192.168.1.254|
|network|A network number, such as 10.9.0.0/16|
|emailaddr|The address of anemail user; for example, harry@suncobalt.com|
|netmask|A number from 1 to 32, or a dot‐quadded IP mask|
|fqdn|A fully qualified domain name; for example, www.suncobalt.com|
|hostname|A non-period hostname;for example, www or smtp|
|domainname|A fully qualified domain name or a domain name; for example, www.suncobalt.com or suncobalt.com|
|password|Scalar 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 ===
^Event^Definition^
|_CREATE|When an object of the specified class is created|
|_DESTROY|When an object of the specified class is destroyed|
|propertyname|When 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.

<code>
# $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
</code>


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

<code perl>
#!/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);
}
</code>

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

^Command^Description^
|auth|Authenticates asa user to get that user's access privileges (starts a new session)|
|authkey|Authenticates to an already existing session|
|endkey|Expires the current sessionid|
|whoami|Returns the oid (Object Identification) of the currently authenticated user|
|bye|Closes the connection|
|commit|Triggers any postponed handler activity|
|create|Creates a new object of a certain class|
|destroy|Destroys an object|
|find|Finds all objects that match a given criteria|
|get|Gets all properties for a certain object or object name space|
|names|Lists name spaces associated with a Class|
|classes|Lists all classes|
|set|Sets 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
^Command^Description^
|baddata|Reports that an unrecognized attribute or value was passed|
|info|Reports a piece of information|
|warn|Reports 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 range^Type of response^
|100-199|Informational|
|200-299|Success|
|300-399|Warning|
|400-499|Failure|
|900-999|System~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.
wiki.blueonyx.it

User Tools

Site Tools

Page Tools
