$Id: FoundationClassLib.spec.txt,v 1.1 2000/03/16 00:23:27 jmayer Exp $
COBALT CONFIDENTIAL.

Cobalt Foundation Class Library

1.0 Abstract

	Microsoft Foundation Classes, Java Foundation Classes ...
		... Cobalt Foundation Classes.
		
	Oh yeah.  Cobalt Foundation Classes.  The Cobalt Configuration
	Engine pumps the CFCs through little tubes to make everything
	... cool.   Without any ozone layer depletion.  And that's
	what Cobalt Networks is all about.

	Before you read this document, you should first glance through:
		CCE.specification.txt
		Security.Model.txt
		CSCP.spec.txt

	FIXME: This classes are really RaQ centric.  I'd like to see
	the CFC encapsulate both RaQ and Qube functionality.  Somebody,
	please patch in the functionality gaps to make this Qube
	compatible.

2.0 Class Overview

	There are three classes of classes presented here:
	
	Base classes provide just the raw basic functionality of the
	UNIX system (managing sites, users, network interfaces, etc.).
	No services are configured at this layer: this is just the
	skeleton upon which the rest of the configuration rests.
	
	Service classes provide the muscles: these provide all of the
	configurable options as seen from the system manager, the site
	manager, and the user.
	
	UI provides the skin that holds this organism together.  It's
	alive!

3.1 A Few Words About Security

	The current spec for the security model defines an ACL
	on an object-by-object basis, not a property-by-property
	basis.  This is why some otherwise logically united objects
	(ie. User) have been split into multiple logical objects
	(ie. User and UserPrivate).  In this manner, properties that
	need different access restrictions have been split into 
	separate objects.
	
	FIXME: is there a better solution?
	
	In the class definitions that follow, a rough sketch of the
	expected access permissions for instances of that class are
	described within the [sqaure braces].  The access permissions
	are simplified down to: root, siteadmin, user (meaning the user
	associated with that object), and other.
	
	See the Security Model document for more information.

3.2 A few word about data types

	A data type such as (hostname) indicates that the variable
	is a scalar that adheres to the "hostname" rule (likely a
	regex).
	
	A data type such as ( Classname) indicates that the
	variable is a reference list of objects derived from the class
	"Classname".
	
	See the CCE spec for more information on data typing.	

4.0 Base Classes

	Here is the list of base classes for a Cobalt product:

		Object
		OrgUnit
		AbstractSite
		Site
		System
		Cluster
		NetIface
		PPPIface
		NameServers
		EmailAddr
		Entity
		User
		Group
		UserInfo
		AbstractPriv
		UserPriv
		GroupPriv
		AbstractDefaults
		UserDefs
		SiteDefs
		Service
		SiteService
		UserService
		ServiceConf

4.1 Base Class Details

	Below are the formal class definitions.
	
	Conventions:
		1. Class names always begin with a capitol letter
		2. In the property lists for classes, the property type
		   is specified first, the property name second.
		3. If the property type is lower-case, that property is
		   a typed scalar (ie. a string that matches a criteria).
		4. If the property type starts with a capital letter, the
		   property is a reference to a list of objects.  The objects
		   must be instances of the named class, or instances of a
		   derived class of the named class.
		5. Intended access permissions for instances of this class
		   are summarized within [square braces].
		6. "Derived isa Super" denotes inheritance.
		7. Any class (except Object) which does not list a superclass 
		   inherits from Object.

	/*******************************************************************
	 * Object
	 *******************************************************************
	 * This is the base class of everything
	 */
	class Object {
		word		name;
	}

	/*******************************************************************
	 * OrgUnit
	 *******************************************************************
	 * Directory Service related classes
	 * these are just here to show how far this model can be taken
	 */
	class OrgUnit isa Object { 
		[r/w:root,admins]
		OrgUnit	orgs
		System	systems
		User		users		/* not for current version */
		User		admins	/* not for current version */
	}
	
	/*******************************************************************
	 * AbstractSite
	 *******************************************************************
	 * site/system related classes
	 */
	abstract class AbstractSite isa Object {
		hostname	hostname
		domain	domain
		NetIface	interfaces
		User		users
		User		admins
		UserDefs	user_defaults
	}
	
	/*******************************************************************
	 * System
	 *******************************************************************
	 */
	class System isa AbstractSite {
		[r/w: root]
		ipaddr		gateway
		NameServer		nameservers
		Site			sites
		SiteDefs		sitedefs
		TimeInfo		timeinfo
		SysService		services
		EmailAddr		problem_mail
	}

	/*******************************************************************
	 * AbstractSite
	 *******************************************************************
	 */
	class Site isa AbstractSite {
		[r/w: root, siteadmin]
		boolean	enabled
		int		max_users
		Quota		disk_quota
		SiteService	services
	}
	
	/*******************************************************************
	 * Cluster
	 *******************************************************************
	 * Qube3 isn't going to use this.  This is for later.
	 */
	class Cluster isa System {
		word		name
		System 	nodes		/* not for current version */
	}
	
	/*******************************************************************
	 * NetInterface
	 *******************************************************************
	 */
	class NetInterface {
		[r/w:root]
		boolean	enabled
		boolean	dynamic
		ipaddr	ip
		ipaddr	netmask
		NetService	services
	}
	
	/*******************************************************************
	 * PPPInterface
	 *******************************************************************
	 */
	class PPPInterface isa NetInterface {
		[r/w: root]
		scalar	phone_number
		username	username
		scalar	password
		scalar	modem_init
		scalar	tty
	}
	
	/*******************************************************************
	 * NameServer
	 *******************************************************************
	 */
	class NameServer {
		[r/w: root]
		ipaddr	address
	}
	
	/*******************************************************************
	 * EmailAddr
	 *******************************************************************
	 */
	class EmailAddr {
		[r/w:creator?]  /* FIXME: access control? */
		scalar	name
		emailaddr 	addr
	}

	/******************************************************************
	 * TimeInfo
	 ******************************************************************
	 */
	class TimeInfo {
	 	scalar	region
		scalar	country
		scalar	zone
		ipaddr	ntp_server
	}
		
	/*==============================================================
	 * User / group related classes
	 *==============================================================/

	/*******************************************************************
	 * Entity
	 *******************************************************************
	 */
	abstract class Entity {
		[r:all, w:root/siteadmin]
		word		name
		word		sortname /* to sort user, usually == name */
		quota		disk_quota
	}
	
	/*******************************************************************
	 * User
	 *******************************************************************
	 */
	class User isa Entity {
		boolean	enabled
		UserPriv	private
		UserInfo	info
		UserService	services
		int		uid	/* preference, not fact */
		int		gid 	/* preference, not fact */
		path		home 	/* FIXME: can we do without this? */
		path		shell /* preference, not fact */
	}
	
	/*******************************************************************
	 * Group
	 *******************************************************************
	 * FIXME: we don't really need this class.
	 */
	class Group isa Entity {
		GroupPriv	private
		int		gid
		Entity	members
	}
	
	/*******************************************************************
	 * UserInfo
	 *******************************************************************
	 */
	class UserInfo {
		[r:all, w:root/siteadmin/user]
		scalar	first
		scalar	middle
		scalar	last
	}
	
	/*******************************************************************
	 * AbstractPriv
	 *******************************************************************
	 * FIXME: we don't need this class either.
	 */
	abstract class AbstractPriv {
		[r:all, w:root/siteadmin/user]
	}
	
	/*******************************************************************
	 * UserPriv
	 *******************************************************************
	 */
	class UserPriv isa AbstractPriv{
		word		pwd
	}
	
	/*******************************************************************
	 * GroupPriv
	 *******************************************************************
	 */
	class GroupPriv isa AbstractPriv {
		word		pwd
	}
	
	/*******************************************************************
	 * AbstractDefaults
	 *******************************************************************
	 */
	abstract class AbstractDefaults {
	}
	
	/*******************************************************************
	 * UserDefs
	 *******************************************************************
	 */
	class UserDefs isa AbstractDefaults {
		[r/w:root/siteadmin]
		quota		disk_quota
		UserService	services
		scalar	name_template
	}
	
	/*******************************************************************
	 * SiteDefs
	 *******************************************************************
	 * gets cloned when a site is created 
	 */
	class SiteDefs isa AbstractDefaults {
		[r/w:root]
		ipaddr	ipaddr
		domain	domain
		quota		disk_quota
		int		max_users
		SiteService	services
	}
	
	/*******************************************************************
	 * All
	 *******************************************************************
	 * The All class is only used as a special "marker" class
	 * for the purposes of the security subsystem.  For practical
	 * purposes, think of the All object as being a group that
	 * automatically has every user in the system as
	 * a member.
	 */
	class All {
		/* empty */
	}

	/*******************************************************************
	 * Service: abstract base class for a service configuration class.
	 *******************************************************************
	 * Contains the one configuration item that all services must
	 * implement (enabled).  Also contains properties that will
	 * enable auto-generated service configuration UI.
	 */
	abstract class Service {
		[r/w: root]
		boolean	enabled
		/* these next three items are used for auto-generating 
		 * the service UI */
		tag		service_name
		tag		service_help
		url		service_config_link
	}

	/* See the section below for more information about why there
	 * are so many different service classes, and how that
	 * impacts system security.
	 */

	/*******************************************************************
	 * SysService: system-wide service settings
	 *******************************************************************
	 */
	abstract class SysService isa Service {
		[r/w: root]
	}

	/*******************************************************************
	 * SiteService: site-specific service settings, root-controlled
	 *******************************************************************
	 */
	abstract class SiteService isa Service {
		[r/w: root]
		SiteServiceConf	config
	}

	/*******************************************************************
	 * SiteServiceConf: site-specific settings, siteadmin-controlled
	 *******************************************************************
	 */
	abstract class SiteServiceConf {
		[r/w: root,siteadmin]
	}

	/*******************************************************************
	 * UserService: user-specific settings, siteadmin-controlled
	 *******************************************************************
	 */
	abstract class UserService isa Service {
		[r/w: root, siteadmin]
		UserServiceConf	config
	}
	
	/*******************************************************************
	 * UserServiceConf: user-specific settings, user-controlled
	 *******************************************************************
	 */
	abstract class UserServiceConf isa Service {
		[r/w: root, siteadmin, user]
	}
	
5.0 Service Classes

	To add services to this system, the various Service classes
	are specialized.  
	
	Services  will be expanded as the services develop.
	
	A Word About Services and Security:
	
	There are five varieties of service classes, that are
	distinguished by the expected level of access permissions
	for an object of that class.  The idea is to create
	fine-grained access control for the various services in
	the system.  This may seem complicated, but it is actually
	only a formalization of the way access control currently
	works in Cobalt product.
	
	(1) SysService: System-wide service settings, configurable
		only by root. (ie. "Is Telnet enabled on this box?")
	(2) SiteService: Site-specific service settings, configurable
		only by root (ie. "Is Telnet allowed on this site?")
	(3) SiteServiceConf: Site-specific service settings, 
		configurable by root or by the siteadmin (ie. "Even if
		Telnet is allowed, does the siteadmin want it to be
		enabled?").
	(4) UserService: User-specific service settings, configurable
		by root or the site-admin (ie. "Does the user have 
		shell access?")
	(5) UserServiceConf: User-specific service settings that can
		be configued by root, the site admin, or the user (ie.
		"Does the user want shell access enabled for her
		account?")
	
	In short, a user can only telnet into her account if:
	 	 (5) she has enabled shell access to her account, and
		 (4) her siteadmin hasn't taken away her shell access, and
	 	 (3) her siteadmin hasn't disable shell for her site, and
	 	 (2) the root user hasn't disallowed shell for her site, and
	 	 (1) the root user hasn't disallowed shell for the whole box.
	
	As seen below, not all services need all 5 of these class-types.
	
5.1 Bandwidth Management Service

	SiteBandwidthService: isa SiteService
		[r/w: root]
		limit (kbps)

5.2 Shell Service

	These classes allow: 

		- a root user to disable shell access for the whole host, or for
		  individual sites.
		- site admin or root user to disable shell access for the whole
		  site, or for individual users.
		- for a user to have shell access:
				UserShellService.enabled == true
				&& SiteShellServiceConf.enabled == true
				&& SiteShellService.enabled == true
				&& ShellService.enabled == true

	ShellService: isa SysService
		[r/w: root]
	
	SiteShellService: isa SiteService
		[r/w: root]
		config ( SiteShellServiceConf)
	
	SiteShellServiceConf: isa SiteServiceConf
		[r/w: root, siteadmin]
	
	UserShellService: isa UserService
		[r/w: root, siteadmin]

5.3 Email Service

	EmailService: isa SysService
		[r/w: root]
		domain_routing ( EmailDomainRoute)
	
	EmailDomainRoute:
		/* indicates what site email for a domain gets routed to */
		[r/w: root]
		domainname (domainname)
		site ( Site)

	UserEmailService: isa UserService
		[r/w: root, siteadmin]
	
	UserEmailServiceConf: ise UserServiceConf
		[r/w: root, siteadmin, user]
		aliases (aliases)
		forward (emailaddr)

5.2 FTP Service

	FTPService: isa SysService
		[r/w: root]
		max_users (integer)
		disk_quota (quota)
	
	SiteFTPService: isa SiteService
		[r/w: root]
		config ( SiteFTPServiceConf)
	
	SiteFTPServiceConf: isa SiteServiceConf
		[r/w: root, siteadmin]
	
	UserFTPService: isa UserService
		[r/w: root, siteadmin]

5.3 SSL Service

	SSLService: isa SysService
	
	SiteSSLService: isa SiteService
	
	SiteSSLServiceConf: isa SiteServiceConf
		certfile: (file)

5.4 MailList Service

	MailListService: isa SysService
	
	SiteMailListService: isa SiteService
	
	SiteMailListServiceConf: isa SiteServiceConf
		lists ( MailList)
	
	MailList
		name (alphanumeric)
		password (password)
		allow_subscriptions (boolean)
		allow_unsub_posting (boolean)
		local_recips ( Users)
		remote_recips ( EmailAddr)
	
	EmailAddr
		name (string)
		addr (emailaddr)

5.5 FPX Service
	
	/* controls who has ability to use FPX */

	FPXService: isa SysService
	
	SiteFPXService: isa SiteService
	
	SiteFPXServiceConf: isa SiteServiceConf

	UserFPXService: isa UserService

5.6 CGI Service

	/* controls who has ability to run cgi scripts */

	CGIService: isa SysService
	
	SiteCGIService: isa SiteService
	
	SiteCGIServiceConf: isa SiteServiceConf

	UserCGIService: isa UserService

	/* see a pattern developing, eh? */

5.7 SSI Service

	/* controls who has ability to perform server-side includes */
	
	/* left as an exercise to the student :-) */

5.8 POP3 Service

	/* controls who has access to POP3 */

	/* left as an exercise to the student :-) */

5.9 Web Service

	/* controls who has the ability to publish web pages, and
	   who serves pages for the domain */

	WebService: isa SysService
		[r/w: root]
		domain_routing ( WebDomainRoute)

	WebDomainRoute:
		/* indicate what site gets http requests to the domain */
		domainname (domainname)
		site ( Site)	

	SiteWebService: isa SiteService
	
	SiteWebServiceConf: isa SiteServiceConf

	UserWebService: isa UserService

5.10 NTP Service

	NTPService: isa SysService
		[r/w: root]
		ntpserver (hostname)
	
5.11 SNMP Service

	SNMPService: isa SysService
		[r/w: root]
		readonly (community)
		readwrite (community)

5.12 DNS Service

	FIXME: Don't know enough about exactly what parts of DNS we're
	configuring here.  Duncan or Will, fill this in?

5.13 Backup Service

	BackupService: isa SysService
		ServerHostname (hostname)
		ServerIPAddr (ip)

	/* Arkeia and Legato will specialize/extend this class */

FIXME: What services did I miss?

6.0 Actuators

	This section proposes the set of actuators (event handlers) that
	need to be written to handle all possible config changes
	described above.  
	
	Syntax:
	
		actuator-name: ( list of class.event pairs )
	
	For example:
	
		cob_user_add: ( User._NEW )
		
	FIXME: this is a lot of work here.  I'm not up to it tonight.

SystemConstructor: ( System._NEW )
	Creates new system object.

SystemName: ( System.hostname System.domain )

SystemRouteTable: ( System.gateway )

SystemResolver: ( System.nameservers NameServer.address )

SiteName: ( Site.hostname Site.domain )

SiteEnabler: ( Site.enabled )

SiteQuota: (Site.disk_quota)
	- changes the configuration of the quota system

NetInterface: ( NetInterface.enabled NetInterface.dynamic
	NetInterface.ip NetInterface.netmask )

PPPInterface: ( PPPInterface.enabled PPPInterface.dynamic
	PPPInterface.ip PPPInterface.netmask PPPInterface.tty 
	PPPInterface.phone_number PPPInterface.username
	PPPInterface.password PPPInterface.modem_init )




System._NEW

A.0 Change Log

	$Log: FoundationClassLib.spec.txt,v $
	Revision 1.1  2000/03/16 00:23:27  jmayer
	Copying over the old project documentation.  Much of this still needs
	to be brought up-to-date.
	
	Revision 1.12  2000/01/15 00:33:48  thockin
	* Added 'Object' as universal baseclass
	* Marked FIND as non-recursive
	* Added criteria to LIST
	
	Revision 1.10  1999/12/31 22:31:52  thockin
	Typos, expanded TimeInfo, looked for other things that were missing
	Looks good so far
	
	Revision 1.9  1999/12/24 10:30:42  jmayer
	Started to add actuators.  but now I'm tired.
	
	Happy holidays, everybody!
	
	Revision 1.8  1999/12/24 10:19:32  jmayer
	Added the special marker class "All."
	
	Revision 1.7  1999/12/23 10:24:23  jmayer
	Tweak. Tweak Tweak.
	
	Revision 1.6  1999/12/23 03:52:19  jmayer
	actually, this is really just testing a .procmail recipe.
	changes to FoundationClassLib.spec.txt are minimal.
	
	Revision 1.5  1999/12/23 03:35:55  thockin
	tweak tweak
	
	Revision 1.4  1999/12/23 03:33:42  thockin
	Tweak Tweak Tweak
	
	Revision 1.3  1999/12/23 00:54:31  jmayer
	tweak tweak tweak.
	
	Revision 1.2  1999/12/23 00:30:45  jmayer
	hacked with docs a bit.
	
	Revision 1.1  1999/12/22 08:32:48  jmayer
	A first stab at defining the Foundation Class library for Sausalito.
	
	This is, essentially, the interface to sauce.
	

-= the end =-
