+You may return. + Index: openacs-4/packages/acs-admin/www/send-email.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/send-email.tcl,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-admin/www/send-email.tcl 30 Nov 2002 17:12:49 -0000 1.2 @@ -0,0 +1,36 @@ +ad_page_contract { + email sending page + + @author Hiro Iwashima
" + ad_script_abort +} + +if { $show_sent_message_p != "t" } { + # Do not show any message. Just go to return url + ad_returnredirect $return_url + ad_script_abort +} Index: openacs-4/packages/acs-admin/www/apm/index.xql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/apm/index.xql,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-admin/www/apm/index.xql 13 May 2001 14:30:00 -0000 1.3 +++ openacs-4/packages/acs-admin/www/apm/index.xql 30 Nov 2002 17:13:06 -0000 1.4 @@ -1,16 +1,24 @@[ad_quotehtml $errmsg]
Done.
-You can send the user email or go back.
+You can send the user email or go back.
Index: openacs-4/packages/acs-admin/www/users/modify-admin-privileges.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/users/modify-admin-privileges.tcl,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-admin/www/users/modify-admin-privileges.tcl 24 Sep 2002 00:12:32 -0000 1.1 +++ openacs-4/packages/acs-admin/www/users/modify-admin-privileges.tcl 30 Nov 2002 17:13:22 -0000 1.2 @@ -22,20 +22,14 @@ if $confirmed_p { if [string equal grant $action] { - db_exec_plsql grant_admin { - select acs_permission__grant_permission( - acs__magic_object_id('security_context_root'), - :user_id, - 'admin') - } + permission::grant -object_id [acs_magic_object "security_context_root"] -party_id $user_id -privilege "admin" } else { - db_exec_plsql revoke_admin { - select acs_permission__revoke_permission( - acs__magic_object_id('security_context_root'), - :user_id, - 'admin') - } + permission::revoke -object_id [acs_magic_object "security_context_root"] -party_id $user_id -privilege "admin" } ad_returnredirect $return_url + + # We need to flush all permission checks pertaining to this user. + # this is expensive so maybe we should check if we in fact are cacheing. + util_memoize_flush_regexp "^permission::.*-party_id $user_id" } Index: openacs-4/packages/acs-admin/www/users/one-oracle.xql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-admin/www/users/one-oracle.xql,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-admin/www/users/one-oracle.xql 9 May 2001 22:32:25 -0000 1.2 +++ openacs-4/packages/acs-admin/www/users/one-oracle.xql 30 Nov 2002 17:13:22 -0000 1.3 @@ -5,7 +5,7 @@
- Return to user administration -
- View admininstrative page for newly created user, @first_names@ @last_name@ +
- View administrative page for newly created user, @first_names@ @last_name@
This procedure is defined in the server but not documented via ad_proc or proc_doc and may be intended as a private interface.
The procedure is defined as:
+proc $proc {[info args $proc]} {
+[ad_quotehtml [info body $proc]]
+}"
+ } elseif {![empty_string_p [namespace eval :: [list info commands $proc]]]} {
+ set error_msg "The procedure $proc is an available command on the server and might be found in the TCL or AOLServer documentation or in documentation for a loadable module (like ns_cache for example).
" + } else { + set error_msg "The procedure $proc is not defined in the server.
" + } } else { if { $source_p } { Index: openacs-4/packages/acs-api-browser/www/proc/index.vuh =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-api-browser/www/proc/index.vuh,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-api-browser/www/proc/index.vuh 20 Aug 2002 12:41:27 -0000 1.1 +++ openacs-4/packages/acs-api-browser/www/proc/index.vuh 30 Nov 2002 17:13:46 -0000 1.2 @@ -1,3 +1,3 @@ -rp_form_put query_string [string range [ad_conn extra_url] [string length "proc/"] end] -rp_form_put search_type "Feeling Lucky" -rp_internal_redirect "/packages/[ad_conn package_key]/www/proc-search" +set query_string [string range [ad_conn extra_url] [string length "proc/"] end] +set url "[ad_conn package_url]proc-search?[export_vars { query_string { search_type "Feeling Lucky" } }]" +ad_returnredirect $url Index: openacs-4/packages/acs-bootstrap-installer/db-init-checks-postgresql.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-bootstrap-installer/db-init-checks-postgresql.tcl,v diff -u -N -r1.4 -r1.5 --- openacs-4/packages/acs-bootstrap-installer/db-init-checks-postgresql.tcl 5 Sep 2002 05:54:45 -0000 1.4 +++ openacs-4/packages/acs-bootstrap-installer/db-init-checks-postgresql.tcl 30 Nov 2002 17:13:56 -0000 1.5 @@ -46,8 +46,10 @@ } - ## Make sure the function is dropped - catch { ns_db dml $db "drop function __test__();" } + ## Make sure the __test__() function is dropped if it exists + if {![empty_string_p [ns_db 0or1row $db "select proname from pg_proc where proname = '__test__' and pronargs = 0"]]} { + catch { ns_db dml $db "drop function __test__();" } + } if { [catch { ns_db dml $db "create function __test__() returns integer as 'begin end;' language 'plpgsql'" } errmsg] } { append my_errors "\n" Index: openacs-4/packages/acs-bootstrap-installer/installer/create-administrator-2-postgresql.xql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-bootstrap-installer/installer/Attic/create-administrator-2-postgresql.xql,v diff -u -N --- openacs-4/packages/acs-bootstrap-installer/installer/create-administrator-2-postgresql.xql 17 Apr 2001 22:59:51 -0000 1.2 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,14 +0,0 @@ - -createlang plpgsql your_database_name
Help to the folks keeping an OpenACS installation up and running.
Help to the folks keeping an OpenACS installation up and running.
This is the place to look if you want to extend OpenACS and build on top - of what's already here. Here you can find out about the guts of the system.
Table of Contents
- 4. OpenACS Developer's Guide
- 5. Other Developer Resources
- 6. Engineering Standards
- 7. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.5 Package Manager Requirements
- OpenACS 4.5 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
This is the place to look if you want to extend OpenACS and build on top + of what's already here. Here you can find out about the guts of the system.
Table of Contents
- 4. OpenACS Developer's Guide
- 5. Other Developer Resources
- 6. Engineering Standards
- 7. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6 Package Manager Requirements
- OpenACS 4.6 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
+
Tcl API
Tcl API
apm-install-procs.tcl (Supports installation of packages)
20-apm-load-procs.tcl (Bootstraps APM for server startup)
-apm-admin-procs.tcl (Supports APM UI)
PL/SQL file
PL/SQL file
+In general terms, a package is a unit of software that serves a single well-defined purpose. That purpose may be to provide a service directly to one or more classes of end-user, (e.g., discussion forums and file storage for community members, user profiling tools for the site publisher), or it may be to act as a building block for other packages (e.g., an application programming interface (API) for storing and querying access control rules, or an API for scheduling email alerts). Thus, packages fall into one of two categories: -
OpenACS Applications: a "program or group of programs +
OpenACS Applications: a "program or group of programs designed for end users" (the Webopedia definition); also known as modules, for historical reasons. Examples of applications include Bboard and News. -
OpenACS Services: the aforementioned building blocks. +
OpenACS Services: the aforementioned building blocks. Examples of services include the OpenACS Content Repository, the OpenACS Templating -System, and the OpenACS Kernel, which includes +System, and the OpenACS Kernel, which includes APM.
An installation of the OpenACS includes the OpenACS Kernel, some services that extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of subsites. A subsite can contain multiple @@ -89,21 +89,21 @@ packages for other ACS users to download and install.
For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):
[D]APM itself is part of a package, the OpenACS Kernel, an OpenACS +3.2 (say, bboard and e-commerce):
[D]APM itself is part of a package, the OpenACS Kernel, an OpenACS service that is the only mandatory component of an OpenACS installation.
The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, including:
Borrowing from all of the above, OpenACS 3.3 introduces its own package -management system, the OpenACS Package Manager (APM), which consists of:
a standard format for APM packages (also called -"OpenACS packages"), including:
version numbering, independent of any other package and the OpenACS as a -whole
specification of the package interface
specification of dependencies on other packages (if any)
attribution (who wrote it) and ownership (who maintains it)
web-based tools for package management:
obtaining packages from a remote distribution point
installing packages, if and only if:
all prerequisite packages are installed
no conflicts will be created by the installation
configuring packages (obsoleting the monolithic OpenACS configuration -file)
upgrading packages, without clobbering local modifications
uninstalling unwanted packages
a registry of installed packages, database-backed and +management system, the OpenACS Package Manager (APM), which consists of:
a standard format for APM packages (also called +"OpenACS packages"), including:
version numbering, independent of any other package and the OpenACS as a +whole
specification of the package interface
specification of dependencies on other packages (if any)
attribution (who wrote it) and ownership (who maintains it)
web-based tools for package management:
obtaining packages from a remote distribution point
installing packages, if and only if:
all prerequisite packages are installed
no conflicts will be created by the installation
configuring packages (obsoleting the monolithic OpenACS configuration +file)
upgrading packages, without clobbering local modifications
uninstalling unwanted packages
a registry of installed packages, database-backed and integrated with filesystem-based version control -
web-based tools for package development:
creating new packages locally
releasing new versions of locally-created packages
The design chosen for APM was meant to satisfy the following constraints:
The process of authoring a package must be as simple as possible.
Strict conventions must be established that provide a set of canonical locations and names for files and patterns, for OpenACS application @@ -124,7 +124,7 @@ subsites across the system, and be available for distribution to other OpenACS installations without doing a monolithic upgrade or reinstall.
The APM is composed of systems for accomplishing a set of package-related tasks. Each of these tasks comprise a feature area that has an API, data -model, and a UI:
Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance
Authoring a Package
Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model +model, and a UI:
Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance
Authoring a Package
Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model creation script, but need not to be used. This API is part of the APM PL/SQL package.
@@ -165,7 +165,7 @@
package_key in apm_package_types.package_key%TYPE
) return integer;
-Maintaining Multiple Versions of a Package
While the package authoring API provides a means for registering a +
Maintaining Multiple Versions of a Package
While the package authoring API provides a means for registering a package, some information about a package is version dependent. For example, between versions, the owner of a package, its vendor, its URI, and its dependency information may change. The API for package versions allows this @@ -245,7 +245,7 @@ );
Files associated with a version can be added and removed. The path is -relative to the package-root which is +relative to the package-root which is acs-server-root/packages/package-key.
-- Add a file to the indicated version.
function add_file(
@@ -327,7 +327,7 @@
version_name_two in apm_package_versions.version_name%TYPE
) return integer;
-Creating Instances of a Package
Once a package is registered in the system, it is possible to create +
Creating Instances of a Package
Once a package is registered in the system, it is possible to create instances of it. Each instance can maintain its own content and parameters.
@@ -382,7 +382,7 @@ show errors -
Specifying Configuration Parameters for each Instance
A parameter is a setting that can be changed on a package instance basis. +
Specifying Configuration Parameters for each Instance
A parameter is a setting that can be changed on a package instance basis. Parameters are registered on each package_key, and the values are associated with each instance. Parameters can have default values and can be of type 'string' or 'number.' There is support with this @@ -513,14 +513,14 @@ site-wide administration.
APM has two parameters for configuring how it interacts with the UNIX filesystem, accessible via the Site Map admin page. These parameters need not be changed under most circumstances, but may -need to be tweaked for Windows compatibility.
GzipExecutableDirectory +need to be tweaked for Windows compatibility.
GzipExecutableDirectory This directory points to where the gunzip program can be found for uncompressing gzip archives. This is needed for the installation of .apm files which are simply gziped tarballs. Default is /usr/local/bin -
InfoFilePermissionsMode +
InfoFilePermissionsMode This sets the default UNIX permissions used when creating files using the APM. Default is 775.
APM has been in production since OpenACS 3.3, and as of version 4.0 offers a stable set of features. One major feature planned is integration with the OpenACS @@ -542,6 +542,4 @@ all of this functionality in one interface and it can be confusing from a usability perspective.
System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon -Salz, Michael Yoon, and Lars Pind.
+
The following is a requirements document for the OpenACS Package Manager + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality with the following specific enhancements:
A public procedural API. (v 3.3 only has web-based UI)
Support for dependency checking.
Support for compound packages (to support installation chaining).
Support for on-line parameter setting.
Support for sub-site level configuration (requires revised ad_parameter and /admin pages at sub-site level; deprecation of site-wide parameter file).
To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -4.
We gratefully acknowledge the authors of APM 3 for their original design +4.
We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the design and open-source implementation of the Red Hat Package manager, the Debian packaging system, and PERL's CPAN in the development of the ideas @@ -29,36 +29,36 @@ packaging, installing, and configuring OpenACS software in a consistent, user-friendly, and subsite-aware manner.
The OpenACS Package Manager (APM) consists of: -
A standard format for APM packages including:
Version numbering, independent of any other package and the OpenACS as a -whole
Specification of the package interface
Specification of dependencies on other packages (if any)
Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
Obtaining packages from a remote distribution point
Installing packages, if and only if:
All prerequisite packages are installed
No conflicts will be created by the installation
Configuring packages (obsoleting the monolithic OpenACS configuration -file)
Upgrading packages, without clobbering local modifications
Uninstalling unwanted packages
A registry of installed packages, database-backed and +
A standard format for APM packages including:
Version numbering, independent of any other package and the OpenACS as a +whole
Specification of the package interface
Specification of dependencies on other packages (if any)
Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
Obtaining packages from a remote distribution point
Installing packages, if and only if:
All prerequisite packages are installed
No conflicts will be created by the installation
Configuring packages (obsoleting the monolithic OpenACS configuration +file)
Upgrading packages, without clobbering local modifications
Uninstalling unwanted packages
A registry of installed packages, database-backed and integrated with file system-based version control -
Web-based tools for package development:
Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package -should never break an OpenACS installation
Web-based tools for package configuration:
The ability to change package parameter values on-line through a simple +
Web-based tools for package development:
Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package +should never break an OpenACS installation
Web-based tools for package configuration:
The ability to change package parameter values on-line through a simple web interface.
A new ad_parameter which does not require a monolithic site-wide parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site level.
The APM is intended for the following classes of users, which may or may not -overlap:
Developers (referred to as 'the developer') use +overlap:
Developers (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural -API for direct control of the APM system.
Site-wide administrators (referred to as 'the +API for direct control of the APM system.
Site-wide administrators (referred to as 'the administrator') use the APM to install packages for their OpenACS instance, -and optionally make them available to sub-sites.
Sub-site administrators (referred to as 'the +and optionally make them available to sub-sites.
Sub-site administrators (referred to as 'the sub-admin') use an administration interface to configure and enable -packages for their sub-site.
Initial Package Development
David Developer writes a piece of software used to do +packages for their sub-site.
Initial Package Development
David Developer writes a piece of software used to do knowledge management (km) for the OpenACS. He distributes his data model, procedure code, UI pages, and his documentation according to the APM specification. He splits the documentation and the code into sub-packages, and creates a KM installation-chain to install both with the APM developer -UI. Noting that his software was built with Patricia -Programmer's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built with Patricia +Programmer's Super Widget toolkit, he specifies that as a dependency. Moreover, since this package is capable of being used at the sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The @@ -72,16 +72,16 @@ installation was successful, the package is available for use.
Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there are initialization routines, she must restart the server for the package to -be ready for use. Annie restarts the server.
Initial Subsite Use of Package
Annie Admin decides to make the KM module available only to a particular +be ready for use. Annie restarts the server.
Initial Subsite Use of Package
Annie Admin decides to make the KM module available only to a particular sub-site type on her OpenACS system, and not others. She specifies this option -using the Sub-site type UI (not part of APM).
Annie Admin notifies Sally SubAdmin by e-mail that a new +using the Sub-site type UI (not part of APM).
Annie Admin notifies Sally SubAdmin by e-mail that a new package is now available for use. Sally goes to her sub-site /admin page and sees that a new entry, KM, is available. Sally clicks on it and finds links to the installed KM documentation and to the web based configuration utility. Then, Sally configures the package using an automatically generated web interface and enables KM for use on her sub-site. After some initial use of the package, Sally decides to change some parameters using the SubAdmin UI. -These changes take effect immediately, without any server restarts.
Upgrade Process
Sally SubAdmin finds a bug in the KM system and sends a report to David +These changes take effect immediately, without any server restarts.
Upgrade Process
Sally SubAdmin finds a bug in the KM system and sends a report to David Developer. David reads the bug report and verifies that the bugs are present in the current version. Because the bugs are present in the shared procedure file, David assigns a watch to the file. David makes the necessary @@ -92,195 +92,195 @@ repository.
Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform +in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software -exhibits different behavior.
4.500.0 Package Identification -(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed +exhibits different behavior.
4.500.0 Package Identification +(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed to be unique to the local OpenACS site must be maintained by the APM. For -example, "apm."
4.500.5 A package id (primary key) that is guaranteed to +example, "apm."
4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."
4.500.10 A package URL that is guaranteed to be unique +"25."
4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For example, "http://openacs.org/software." -
4.505.0 Version Identification - (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to -be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique +
4.505.0 Version Identification + (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to +be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package.
The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages -that already do all of the below in raw SQL.
4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, +that already do all of the below in raw SQL.
4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, the APM API can return the status of the package on the local OpenACS -instance.
4.405.0 Package Information Procedures
4.405.1 The APM API can return information for any +instance.
4.405.0 Package Information Procedures
4.405.1 The APM API can return information for any locally installed packages, including the version number, paths and files, -and package key.
4.410.0 Sub-site Procedures
4.410.1 After a package has been installed at the +and package key.
4.410.0 Sub-site Procedures
4.410.1 After a package has been installed at the site-wide level, the system API will provide means to check for package -presence, creation, enabling, disabling, and destruction on a subsite.
4.415.0 Parameter Values (replaces ad_parameter)
4.415.1 The system API shall allow subsite parameters for +presence, creation, enabling, disabling, and destruction on a subsite.
4.415.0 Parameter Values (replaces ad_parameter)
4.415.1 The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only -take effect after a server restart (default is immediate).
4.415.5 Parameters for a given subsite and package can be +take effect after a server restart (default is immediate).
4.415.5 Parameters for a given subsite and package can be returned by the system API.
Provisions will be made to assure that packages are securely -identified.
4.600.1 Each package will have a PGP signature and there +identified.
4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package. -
4.600.5 The APM will provide a facility to validate both +
4.600.5 The APM will provide a facility to validate both the PGP signature and MD5 stamps information before a package install.
The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the actions taken here can dramatically affect the state of the running OpenACS.
The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects -throughout the OpenACS and should not be used on a production site.
10.0 Define a package.
The developer must be able to create a new package by specifying some +throughout the OpenACS and should not be used on a production site.
10.0 Define a package.
The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a -package key, version information, owner information, and a canonical URL.
10.1 The APM must maintain the state of all locally -generated packages.
10.50 If the developer fails to provide the required -information, the package cannot be created.
10.55 All of the package information should be editable -after creation, except for the package key.
4.10.60 The package creator must specify whether the +package key, version information, owner information, and a canonical URL.
10.1 The APM must maintain the state of all locally +generated packages.
10.50 If the developer fails to provide the required +information, the package cannot be created.
10.55 All of the package information should be editable +after creation, except for the package key.
4.10.60 The package creator must specify whether the package is capable of being used in sub-sites, or if only a single, global -instance of the package is permitted.
4.10.65 If the developer fails to provide unique +instance of the package is permitted.
4.10.65 If the developer fails to provide unique information for unique fields specified in the data model requirements, the -package cannot be created.
20.0 Add files to a package
20.1 The developer must be able to add files to the +package cannot be created.
20.0 Add files to a package
20.1 The developer must be able to add files to the package. This is done by copying the files into the package directory in the host OS's file system. Files can be added at any point after package -creation.
20.3 Once a package has been versioned and distributed, +creation.
20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.
20.5 The APM's UI should facilitate the process of +number.
20.5 The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, -and allowing the developer to confirm adding them.
20.10 The developer cannot add files to a given package -via the UI that do not exist in the file system already.
20.15 Package file structure must follow a specified -convention. Please see the design -document for what we do currently.
30.0 Remove files from a package
The developer must be able to remove files from a package. This can be -done in two ways.
30.1 Access the APM UI, browse the file list, and remove -files.
30.1.1If a file is removed from the package list, but not -from the file system, an error should be generated at package load time.
30.5 Remove the file from file system.
30.5.1 The APM UI should take note of the fact that the +and allowing the developer to confirm adding them.
20.10 The developer cannot add files to a given package +via the UI that do not exist in the file system already.
20.15 Package file structure must follow a specified +convention. Please see the design +document for what we do currently.
30.0 Remove files from a package
The developer must be able to remove files from a package. This can be +done in two ways.
30.1 Access the APM UI, browse the file list, and remove +files.
30.1.1If a file is removed from the package list, but not +from the file system, an error should be generated at package load time.
30.5 Remove the file from file system.
30.5.1 The APM UI should take note of the fact that the file is gone and offer the developer an option to confirm the file's deletion. -
40.0 Modify files in a package.
40.1 The developer should be able to modify files in the -file system. The APM UI should not interfere with this.
40.5 However, if the developer modifies files containing -procedural definitions, APM UI should allow a means to watch +
40.0 Modify files in a package.
40.1 The developer should be able to modify files in the +file system. The APM UI should not interfere with this.
40.5 However, if the developer modifies files containing +procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 -for more detail.
40.10 Also, although a change in files implies that the +for more detail.
40.10 Also, although a change in files implies that the package distribution file is out of date, it is the developer's -responsibility to update it.
4.45.0 Manage Package Dependency Information.
4.45.1 The developer should be able to specify which -interfaces the package requires.
4.45.5 The developer should be able to specify which -interfaces the package provides.
4.45.10 Circular dependencies are not allowed.
50.0 Watch a file
4.50.1 The developer should be able to assign a watch to -any Tcl procedure file, whether in /packages or /tcl.
50.5 If a watched file is locally modified, then it will +responsibility to update it.
4.45.0 Manage Package Dependency Information.
4.45.1 The developer should be able to specify which +interfaces the package requires.
4.45.5 The developer should be able to specify which +interfaces the package provides.
4.45.10 Circular dependencies are not allowed.
50.0 Watch a file
4.50.1 The developer should be able to assign a watch to +any Tcl procedure file, whether in /packages or /tcl.
50.5 If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect -immediately.
4.50.10 The setting of a watch should be persistent +immediately.
4.50.10 The setting of a watch should be persistent across server restarts. -
60.0 Display an XML package specification
60.1 The developer should be able to view the XML package +
60.0 Display an XML package specification
60.1 The developer should be able to view the XML package specification that encodes all package information. -
70.0 Write an XML package specification to the file -system
70.1 The developer should be able to write an up-to-date -XML specification to disk.
70.5 The developer should be able to request the current -XML specification for all installed, locally generated packages.
130.0 Distribution file generation
130.1 The developer should be able to generate a .APM -distribution file for the package with just one click.
130.5 Generating a distribution file implies doing an +
70.0 Write an XML package specification to the file +system
70.1 The developer should be able to write an up-to-date +XML specification to disk.
70.5 The developer should be able to request the current +XML specification for all installed, locally generated packages.
130.0 Distribution file generation
130.1 The developer should be able to generate a .APM +distribution file for the package with just one click.
130.5 Generating a distribution file implies doing an "up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created. -
140.0 Access CVS information
140.1 The developer should be able to determine the CVS +
140.0 Access CVS information
140.1 The developer should be able to determine the CVS status of a package, or all packages, with a single click. -
4.200.0 Compound Package Construction
4.200.1 The developer can include .APM packages +
4.200.0 Compound Package Construction
4.200.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.
4.200.5 The recommended usage for this feature is to +file.
4.200.5 The recommended usage for this feature is to allow for separation of optional and required components from the installation as well as better organization of files once installed. For example, all documentation for the community-core can be packages as community-core-doc.apm. It is legal to include sub-packages with dependencies that are not satisfied by the packages in the compound package, but this is discouraged. In such a case, the sub-package should really be a -separate package that is required by the compound package.
4.200.10 If a sub-package is required for the +separate package that is required by the compound package.
4.200.10 If a sub-package is required for the installation of the compound package, the compound package should have a registered dependency on the sub-package.
The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete -packages.
80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed +packages.
80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its functionality is delivered through the Request Processor. As of OpenACS 4, this -is done through the sub-site system.
4.80.5 Moreover, the administrator must be able to +is done through the sub-site system.
4.80.5 Moreover, the administrator must be able to disable a package, thereby removing the functionality provided to a sub-site. As of OpenACS 4, this is done through the sub-site system. -
90.0 Package Install
90.1 The administrator must be able to install new -packages either from locally maintained .APM files or from URLs.
90.5 In the case of an URL, the APM transparently +
90.0 Package Install
90.1 The administrator must be able to install new +packages either from locally maintained .APM files or from URLs.
90.5 In the case of an URL, the APM transparently downloads the APM file off the web, proceeds with a file based installation, -and then optionally removes the .APM file just downloaded.
90.10.1 If .APM files are present in a package, then it -is considered a compound package (use 4.210.0).
90.15.0 Installation requires these steps:
90.15.1The package dependencies are scanned. If some +and then optionally removes the .APM file just downloaded.
90.10.1 If .APM files are present in a package, then it +is considered a compound package (use 4.210.0).
90.15.0 Installation requires these steps:
90.15.1The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that -installation cannot proceed until those packages are installed.
90.15.2 Assuming all dependencies are present, APM -extracts the contents of the APM file into the /packages directory.
90.15.3 The administrator is offered the option of -importing directly into CVS.
90.15.4 The administrator is given a list of data model -scripts found in the package and can select which ones to be executed.
90.15.5 If no errors are recorded during this process, -the package is enabled.
4.210.0 Compound package Install
4.210.1 If .APM files are present in a package, then it -is considered a compound package.
4.210.5.0 Installation of a compound package proceeds -according to the following sequence:
4.210.5.1 Identify the set of all sub-packages within -the compound package by scanning for all files with .APM.
4.210.5.2 Identify which sub-packages are required by +installation cannot proceed until those packages are installed.
90.15.2 Assuming all dependencies are present, APM +extracts the contents of the APM file into the /packages directory.
90.15.3 The administrator is offered the option of +importing directly into CVS.
90.15.4 The administrator is given a list of data model +scripts found in the package and can select which ones to be executed.
90.15.5 If no errors are recorded during this process, +the package is enabled.
4.210.0 Compound package Install
4.210.1 If .APM files are present in a package, then it +is considered a compound package.
4.210.5.0 Installation of a compound package proceeds +according to the following sequence:
4.210.5.1 Identify the set of all sub-packages within +the compound package by scanning for all files with .APM.
4.210.5.2 Identify which sub-packages are required by checking the dependencies of the compound package. If there dependencies not satisfied by the current system or the packages included with the compound package, halt installation and inform user to install these packages -first.
4.210.5.3 Present Administrator with the ability to +first.
4.210.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be -installed.
4.210.5.4 Proceed with the installation of each +installed.
4.210.5.4 Proceed with the installation of each sub-package, starting with required packages. If the sub-package is already installed, then do nothing. Else, If the sub-package is a normal package, -proceed according to 90.15.0, otherwise if it is a compound -package, proceed according to 4.210.5.0.
4.210.5.5 If all required sub-packages are installed, +proceed according to 90.15.0, otherwise if it is a compound +package, proceed according to 4.210.5.0.
4.210.5.5 If all required sub-packages are installed, proceed to install non-required sub-packages. If there was a failure during the installation of a required sub-package, then the installation of the -compound package is also a failure.
4.210.5.6 Any attempt to install a compound package in +compound package is also a failure.
4.210.5.6 Any attempt to install a compound package in the future involves a choice presented to the admin of installing any -uninstalled sub-packages.
4.220.0 Recovering from failed package installation
4.220.1 If any error is generated during package +uninstalled sub-packages.
4.220.0 Recovering from failed package installation
4.220.1 If any error is generated during package installation, the package is not considered installed. To recover from this -failure, the package should be selected for installation again.
100.0 Version Upgrade
100.1 The administrator can upgrade to a new version of a -package. This entails
100.1.1 Running any necessary and included upgrade -scripts.
100.1.5 Replacing any old files with new versions.
100.1.10 Marking the old version of the package as -'superseded' and disabling it.
100.1.15 Assuming no errors from above, the new package -is enabled.
110.0 Package Deinstall
110.1 The administrator must be able to deinstall a -package that has already been installed. Deinstallation entails:
110.1.1 Running any data model scripts necessary to drop -the package.
110.1.5 Moving all of the files into a separate location -in the file system from the installed packages.
4.110.1.10 If the package is a compound package, then +failure, the package should be selected for installation again.
100.0 Version Upgrade
100.1 The administrator can upgrade to a new version of a +package. This entails
100.1.1 Running any necessary and included upgrade +scripts.
100.1.5 Replacing any old files with new versions.
100.1.10 Marking the old version of the package as +'superseded' and disabling it.
100.1.15 Assuming no errors from above, the new package +is enabled.
110.0 Package Deinstall
110.1 The administrator must be able to deinstall a +package that has already been installed. Deinstallation entails:
110.1.1 Running any data model scripts necessary to drop +the package.
110.1.5 Moving all of the files into a separate location +in the file system from the installed packages.
4.110.1.10 If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some -sub-packages can be kept.
110.5 Deinstalled packages can be re-installed at a later -date.
4.110.10 If deinstalling a package or any of its +sub-packages can be kept.
110.5 Deinstalled packages can be re-installed at a later +date.
4.110.10 If deinstalling a package or any of its sub-packages breaks a dependency, then deinstallation cannot proceed until -the package registering the dependency is removed.
120.0 Package Deletion
120.1 The administrator should be able to completely +the package registering the dependency is removed.
120.0 Package Deletion
120.1 The administrator should be able to completely erase all records of the package. This involves removing all instances of the -package, all related database tables and content.
120.5 This option can only be used if all package +package, all related database tables and content.
120.5 This option can only be used if all package instances are deleted or marked as disabled. This is purposefully cumbersome because deleting all instances of a package can have far-sweeping -consequences throughout a site and should almost never be done.
150.0 Scan for new or modified packages
150.1 The administrator should be able to scan the file -system for any changes made in any of the installed package files.
150.5 The administrator should be able to scan the file +consequences throughout a site and should almost never be done.
150.0 Scan for new or modified packages
150.1 The administrator should be able to scan the file +system for any changes made in any of the installed package files.
150.5 The administrator should be able to scan the file system for any newly installed packages.
If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface. -
+these features should be quite straightforward.4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should +
4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an -option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin +option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site -type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all -parameters with current values must be available.
4.305.5 Changing the values for the parameters is -accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package +type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is +available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all +parameters with current values must be available.
4.305.5 Changing the values for the parameters is +accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its URLs properly. -
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package +
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package with a single click. Disabling a package means that the OpenACS will no longer -serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not +serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated. @@ -293,6 +293,4 @@ are set using the acs_attribute_values table. The automatic web interface for setting package parameters should be one and the same with the interface for setting acs object attribute values. Consequently, the implementation of -these features should be quite straightforward.
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 8/10/2000 Bryan Quinn, Todd Nightingale � Reviewed 8/11/2000 John Prevost, Mark Thomas, and Pete Su 0.2 Revised and updated 8/12/2000 Bryan Quinn 0.3 Reviewed, revised, and updated - conforms to requirements template. 8/18/2000 Kai Wu 0.4 Minor edits before ACS 4 Beta. 9/30/2000 Kai Wu
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 8/10/2000 Bryan Quinn, Todd Nightingale � Reviewed 8/11/2000 John Prevost, Mark Thomas, and Pete Su 0.2 Revised and updated 8/12/2000 Bryan Quinn 0.3 Reviewed, revised, and updated - conforms to requirements template. 8/18/2000 Kai Wu 0.4 Minor edits before ACS 4 Beta. 9/30/2000 Kai Wu View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/dev-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/dev-guide.html 10 Aug 2002 20:07:20 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/dev-guide.html 30 Nov 2002 17:16:23 -0000 1.8 @@ -1,4 +1,2 @@ -Chapter 4. OpenACS Developer's Guide +Chapter�4.�OpenACS Developer's Guide View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/developers-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/developers-overview.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/developers-overview.html 10 Aug 2002 20:07:20 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/developers-overview.html 30 Nov 2002 17:16:23 -0000 1.4 @@ -1,4 +1,2 @@ -Overview +Overview View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 10 Aug 2002 20:07:20 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 30 Nov 2002 17:16:23 -0000 1.9 @@ -1,21 +1,21 @@ -OpenACS Documentation Guide +
OpenACS Documentation Guide By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community -
+
ArsDigita created a good documentation ground for us to build upon. Some sections of the documentation, however, lack details and examples; others are simply nonexistant. Our goal is to give OpenACS a superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system.
- OpenACS™ is a powerful system, with + OpenACS is a powerful system, with incredible possibilities and applications, but with this power comes some complexity and a learning curve that will only be atenuated by good documentation. This is what we are after.
- The documentation for OpenACS™ is + The documentation for OpenACS is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the Why DocBook? section. I will add the reasons why @@ -32,31 +32,31 @@ In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge.
Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around - for a while (since early 90's), + for a while (since early 90's), it's well-tested, it's complete, it's extremely well-suited for technical documents and best of all, it's open-source. A growing community surrounds DocBook (has - mailing lists) + mailing lists) and a number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents.
This primer walks you through the basics, and should cover the needs for 95 percent of the documentation we produce. However, you're always welcome to check out DocBook's - + list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically - the same elements are valid in the XML DTD as long as you remember to: - + the same elements are valid in the XML DTD as long as you remember to: +
Always close your tags with corresponding end-tags and to - not use other tag minimization + not use other tag minimization
Write all elements and attributes in lowercase
@@ -99,22 +99,22 @@ The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - +
- book : Docs for one package - templating + book : Docs for one package - templating | - +--chapter : One section - for developers + +--chapter : One section - for developers | ---------+------------------------------------------------------ | - +--sect1 : Single document - requirements + +--sect1 : Single document - requirements | - +--sect2 : Sections - functional requirements + +--sect2 : Sections - functional requirements | - +--sect3 : Subsections - Programmer's API + +--sect3 : Subsections - Programmer's API | - ... : ... + ... : ...
The actual content is split up into documents that start at a sect1-level. These are then tied together in a top-level document that @@ -123,20 +123,20 @@ sources of these DocBook documents to get an idea of how they are tied together.
- + Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>.
- + You need to feed every <sect1> two attributes. The first attribute, id, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in the section called “Links”). The value of id has to be unique throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML.
- + The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.
@@ -151,7 +151,7 @@ </sect1>
- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -160,7 +160,7 @@ When it comes to naming your sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.
- + For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we will use the tag <computeroutput>. @@ -170,12 +170,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.
- + Linking falls into two different categories: inside the book you're making and outside: -
- 1. Inside linking, cross-referencing other parts of your book
+
- 1. Inside linking, cross-referencing other parts of your book
By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -
Check out how I link to a subsection of the Developer's Guide:
+
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML: @@ -212,8 +212,8 @@ Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its best to explain where the link takes you. -
- 2. Linking outside the documentation
- 2. Linking outside the documentation
+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -222,19 +222,19 @@
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
....will create a hyper-link to Oracle in the HTML-version of the documentation. -
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing +
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing entities, which is exactly how you'll make an ampersand: &
- NOTE: Currently this section currently only takes HTML-output into consideration - + NOTE: Currently this section currently only takes HTML-output into consideration - not a printed version
- Another Note: Also, it's still not a 100 percent sure that this is how we are going to + Another Note: Also, it's still not a 100 percent sure that this is how we are going to do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -260,9 +260,9 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.
+- + Here's how you make the DocBook equivalent of the three usual HTML-lists: -
- 1. How to make an <ul>
+
- 1. How to make an <ul>
Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as <para>, and that the tags are called <itemizedlist> @@ -271,20 +271,20 @@
<itemizedlist> - <listitem><para>Stuff goes here</para><listitem> - <listitem><para>More stuff goes here</para><listitem> + <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -
- 2. How to make an <ol>
+
- 2. How to make an <ol>
The ordered list is like the preceding, except that you use <orderedlist> instead:
<orderedlist> - <listitem><para>Stuff goes here</para><listitem> - <listitem><para>More stuff goes here</para><listitem> + <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> </orderedlist> -
- 3. How to make a <dl>
+
- 3. How to make a <dl>
This kind of list is called a variablelist and these are the tags you'll need to make it happen: <variablelist>, @@ -295,17 +295,17 @@ <varlistentry> <term>Heading (<dt>) goes here</term> - <listitem><para>And stuff (<dd>)goes here</para><listitem> + <listitem><para>And stuff (<dd>)goes here</para></listitem> </varlistentry> <varlistentry> <term>Another heading goes here</term> - <listitem><para>And more stuff goes here</para><listitem> + <listitem><para>And more stuff goes here</para></listitem> </varlistentry> </variablelist>
- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -342,7 +342,7 @@ <table> for an example.
- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.
@@ -376,7 +376,7 @@
bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xmlNote
- This example uses Daniel Veillard's xsltproc command available + This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. @@ -410,7 +410,7 @@ DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.In the process of transforming your HTML into XML, - HTML tidy + HTML tidy can be a a handy tool to make your HTML "regexp'able". Brandoch Calef has made a Perl script @@ -421,6 +421,4 @@
8/3/2002 Vinod Kurup 0.3 Added OpenACS information, updated tools, added extra links and added info to the Publishing section. - 12/24/2001 Roberto Mello 0.2 Changed recommendation from <phrase> to <emphasis role="strong"> 01/19/2000 Claus Rasmussen 0.1 Creation 12/2000 Claus Rasmussen 12/24/2001 Roberto Mello 0.2 Changed recommendation from <phrase> to <emphasis role="strong"> 01/19/2000 Claus Rasmussen 0.1 Creation 12/2000 Claus Rasmussen View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,4 +1,2 @@ -Chapter 6. Engineering Standards +Chapter�6.�Engineering Standards View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/for-everyone.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/for-everyone.html 10 Aug 2002 20:07:20 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/for-everyone.html 30 Nov 2002 17:16:24 -0000 1.8 @@ -1,4 +1,2 @@ -Part Part I. OpenACS For Everyone +High level information: What is OpenACS?
Table of Contents
Part�Part I.�OpenACS For Everyone High level information: What is OpenACS?
Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/general-documents.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/general-documents.html 10 Aug 2002 20:07:20 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/general-documents.html 30 Nov 2002 17:16:24 -0000 1.8 @@ -1,4 +1,2 @@ -Chapter 1. High level information: What is OpenACS? +Table of Contents
Chapter�1.�High level information: What is OpenACS? Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/groups-design.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Groups Design ++
OpenACS 4 Groups Design User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Data model
PL/SQL file
User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Data model
PL/SQL file
ER diagram
Transaction flow diagram
Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, @@ -62,16 +62,16 @@
The set of direct membership relationships between a group and a party.
- group_member_index -
A mapping of a party P to the groups -{Gi}the party is a member of; this mapping +
A mapping of a party P to the groups +{Gi}the party is a member of; this mapping includes the type of relationship by including the appropriaterel_id from the membership_rels table.
- composition_rels
The set of direct component relationships between a group and another group.
- group_component_index -
A mapping of a group Gto the set of groups -{Gi} that G is a component of; +
A mapping of a group Gto the set of groups +{Gi} that G is a component of; this mapping includes the type of relationship by including the appropriaterel_id from the composition_rels table.
New groups are created through the group.new constructor. When a specialized type of group is required, the group type can be extended @@ -116,26 +116,26 @@
A person may appear in the group member map multiple times, for example, by being a member of two different groups that are both components of a third -group. This view is strictly a mapping of approved members +group. This view is strictly a mapping of approved members to groups.
- group_component_map -
A mapping of a group Gto the set of groups -{Gi} group G is a component of; +
A mapping of a group Gto the set of groups +{Gi} group G is a component of; this mapping includes the type of relationship by including the appropriaterel_id from the composition_rels table.
- party_member_map -
A mapping of a party P to the set of parties -{Pi} party P is a member +
A mapping of a party P to the set of parties +{Pi} party P is a member of.
- party_approved_member_map -
A mapping of a party P to the set of parties -{Pi} party P is an -approved member of.
The API consists of tables and views and PL/SQL functions.
The group_types table is used to create new types of groups.
The group_member_map, group_approved_member_map, group_distinct_member_map, group_component_map, party_member_map, and party_approved_member_map views are -used to query group membership and composition.
Person
person.new creates a new person and returns the +used to query group membership and composition.
Person
person.new creates a new person and returns the person_id. The function must be given the full name of the person in two pieces: first_names and last_name. All other fields are optional and default to null except for object_type which defaults @@ -162,7 +162,7 @@ function person.name ( person_id persons.person_id%TYPE ) return varchar; -
User
acs_user.new creates a new user and returns the user_id. +
User
acs_user.new creates a new user and returns the user_id. The function must be given the user's email address and the full name of the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:
@@ -204,7 +204,7 @@ procedure acs_user.unapprove_email ( user_id users.user_id%TYPE ); -
Group
acs_group.new creates a new group and returns the +
Group
acs_group.new creates a new group and returns the group_id. All fields are optional and default to null except for object_type which defaults to 'group', creation_date which defaults to sysdate, and @@ -232,7 +232,7 @@ group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, ) return char; -
Membership Relationship
membership_rel.new creates a new membership relationship type +
Membership Relationship
membership_rel.new creates a new membership relationship type between two parties and returns the relationship type's rel_id. All fields are optional and default to null except for rel_type which defaults to membership_rel. The interface for this function is:
@@ -278,7 +278,7 @@ procedure membership_rel.delete ( rel_id membership_rels.rel_id%TYPE ); -
Composition Relationship
composition_rel.new creates a new composition relationship type +
Composition Relationship
composition_rel.new creates a new composition relationship type and returns the relationship's rel_id. All fields are optional and default to null except for rel_type which defaults to composition_rel. The interface for this function is:
@@ -301,6 +301,4 @@
- Documentation author -
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/22/2000 Rafael H. Schloming 0.2 Initial Revision 08/30/2000 Mark Thomas 0.3 Additional revisions; tried to clarify membership/compostion 09/08/2000 Mark Thomas Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/22/2000 Rafael H. Schloming 0.2 Initial Revision 08/30/2000 Mark Thomas 0.3 Additional revisions; tried to clarify membership/compostion 09/08/2000 Mark Thomas View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Groups Requirements +
OpenACS 4 Groups Requirements Almost all database-backed websites have users, and need to model the + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS @@ -16,7 +16,7 @@ person who is employed by (is a member of) a specific department is also a member of the division and the corporation, and works at (is a member of, but in a different sense) a particular office. OpenACS 4's Parties and Groups -system will support such complex relations faithfully.
Historical Motivations
The primary limitation of the OpenACS 3.x user group system is that it +system will support such complex relations faithfully.
Historical Motivations
The primary limitation of the OpenACS 3.x user group system is that it restricts the application developer to representing a "flat group" that contains only users: The user_groups table may contain the group_id of a parent group, but parent-child relationship @@ -33,29 +33,29 @@ (e.g., a row with a scope value of "group" but a null group_id)
perform extra checks in Tcl and PL/SQL functions and procedures to check both the user_id and -group_id values
In sum, the goal of the Parties and Groups system is to +group_id values
In sum, the goal of the Parties and Groups system is to provide OpenACS programmers and site administrators with simple tools that fully describe the complex relationships that exist among groups in the real world.
Pat Developer has a client project and wants to model the company, its offices, its divisions, and its departments as groups and the employees as -users.
We start with Groups, which contain members; the -member can be either a person or another group (i.e. a +users.
We start with Groups, which contain members; the +member can be either a person or another group (i.e. a member is a party).
In addition to membership, the party and groups system defines a -composition relationship that may exist between groups: A -group can be a component of another group. The child group +composition relationship that may exist between groups: A +group can be a component of another group. The child group is called a component group; the parent group is called a -composite group.
A group Gc can be a member and/or a component -of another group Gp; the difference is in the way -the members of Gc are related to -Gp:
If a party P is a member (or a component) of -Gc and if Gc is a -component of Gp, then P is also -a member (or a component) of Gp
If a party P is a member (or a component) of -Gc and if Gc is a -member of Gp, then no -relationship between P and -Gp exists as a result of the relationship between -Gp and Gp.
Consider an example to make this less abstract: Pretend that the Sierra +composite group.
A group Gc can be a member and/or a component +of another group Gp; the difference is in the way +the members of Gc are related to +Gp:
If a party P is a member (or a component) of +Gc and if Gc is a +component of Gp, then P is also +a member (or a component) of Gp
If a party P is a member (or a component) of +Gc and if Gc is a +member of Gp, then no +relationship between P and +Gp exists as a result of the relationship between +Gp and Gp.
Consider an example to make this less abstract: Pretend that the Sierra Club is a member of Greenpeace. The Sierra Club has chapters; each chapter is a component of the Sierra Club. If Eddie Environmentalist is a member of the Massachusetts Chapter of the Sierra Club, Eddie is @@ -68,160 +68,158 @@ Massachusetts chapter), and between the Sierra Club and Greenpeace.
Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum necessary to join a group.
The parties and groups system must support constraints between a composite -group GP and any of its component groups, -GC. For example, the system should be able to -enforce a rule like: Do not allow a party P to become a -member of GC unless P is already -a member of GP.
The data model for the parties and groups system must provide support for -the following types of entities:
- 10.0 Parties +group GP and any of its component groups, +GC. For example, the system should be able to +enforce a rule like: Do not allow a party P to become a +member of GC unless P is already +a member of GP.
+underlying API. The user interface may provide the following functions:The data model for the parties and groups system must provide support for +the following types of entities:
- 10.0 Parties -
A party is an entity used to represent either a -group or a person.
The data model should enforce these constraints:
10.10 A party has an email address, which can be -empty.
10.20 A party may have multiple email addresses -associated with it.
10.30 The email address of a party must be unique within -an OpenACS system.
- 20.0 Groups +
A party is an entity used to represent either a +group or a person.
The data model should enforce these constraints:
10.10 A party has an email address, which can be +empty.
10.20 A party may have multiple email addresses +associated with it.
10.30 The email address of a party must be unique within +an OpenACS system.
- 20.0 Groups -
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of -groups via OpenACS Objects.
- 30.0 Persons +
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of +groups via OpenACS Objects.
- 30.0 Persons -
A person represents an actual human being, past or -present.
- 40.0 Users +
A person represents an actual human being, past or +present.
- 40.0 Users -
A user is a person who has registered with an OpenACS site. A -user may have additional attributes, such as a screen name.
The data model should enforce these constraints:
40.10 A user must have a non-empty email address.
40.20 Two different users may not have the same email +
A user is a person who has registered with an OpenACS site. A +user may have additional attributes, such as a screen name.
The data model should enforce these constraints:
40.10 A user must have a non-empty email address.
40.20 Two different users may not have the same email address on a single OpenACS installation; i.e., an email address identifies a -single user on the system.
40.30 A user may have multiple email addresses; for -example, two or more email addresses may identify a single user.
40.40 A user must have password field which can be +single user on the system.
40.30 A user may have multiple email addresses; for +example, two or more email addresses may identify a single user.
40.40 A user must have password field which can be empty.
The data model for the parties and groups system must provide support for -the following types of relationships between entities:
- 50.0 Membership
+the following types of relationships between entities:
- 50.0 Membership
-A party P is considered a member of a -group G
when a direct membership relationship exists between P -and G
or when there exists a direct membership relationship between -P and some group GC and -GC has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple +A party P is considered a member of a +group G
when a direct membership relationship exists between P +and G
or when there exists a direct membership relationship between +P and some group GC and +GC has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple times only when all the memberships have different types; for example, Jane may be a member of The Company by being both an Employee and an -Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership -constraints.
50.50The data model should support the subclassing of +Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership +constraints.
50.50The data model should support the subclassing of membership via OpenACS Relationships.
- -60.0 Composition -
A group GC is considered a -component of a second group -GP
when a direct composition relationship exists between -GC and GP
or when there exists a direct composition relationship between -GC and some group Gi -and Gi has a composition relationship with -GP.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not -supported.
60.30The data model must support component -constraints.
60.40The data model should support the subclassing of -composition via OpenACS Relationships.
The API should let programmers accomplish the following tasks:
- 70.10 Create a group +60.0 Composition +
A group GC is considered a +component of a second group +GP
when a direct composition relationship exists between +GC and GP
or when there exists a direct composition relationship between +GC and some group Gi +and Gi has a composition relationship with +GP.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not +supported.
60.30The data model must support component +constraints.
60.40The data model should support the subclassing of +composition via OpenACS Relationships.
The API should let programmers accomplish the following tasks:
- 70.10 Create a group
The parties and groups system provides a well defined API call that creates a new group by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out -in the data model.
- 70.20 Create a person
+in the data model.
- 70.20 Create a person
The parties and groups system provides a well defined API call that creates a new person by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out -in the data model.
- 70.30 Create a user +in the data model.
- 70.30 Create a user
The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out in -the data model.
- 80.10 Refine a person to a user +the data model.
- 80.10 Refine a person to a user
The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on an existing person entity. This API is subject to the constraints laid out in the data -model.
- 80.30 Demote a user to a person +model.
- 80.30 Demote a user to a person
The parties and groups system provides a well defined API call that demotes an existing user entity to a person entity by running the appropriate transactions on the existing user. This API is subject to the constraints -laid out in the data model.
- 90.10 Update a party +laid out in the data model.
- 90.10 Update a party
The programmer should be able to modify, add, and delete attributes on any -party. This API is subject to the constraints laid out in the data model.
- 95.10 Get the attributes of a party +party. This API is subject to the constraints laid out in the data model.
- 95.10 Get the attributes of a party
The programmer should be able to view the attributes on any party. This -API is subject to the constraints laid out in the data model.
- 100.10 Delete a party +API is subject to the constraints laid out in the data model.
- 100.10 Delete a party
The system provides an API for deleting a party. This API is subject to -the constraints laid out in the data model.
100.30 The system may provide a single API call to remove -the party from all groups and then delete the party.
100.40 In the case of a group, the system may provide a +the constraints laid out in the data model.
100.30 The system may provide a single API call to remove +the party from all groups and then delete the party.
100.40 In the case of a group, the system may provide a single API call to remove all parties from a group and then delete the -group.
- 110.0 Add a party as a member of a group +group.
- 110.0 Add a party as a member of a group
The parties and groups system provides an API for adding a party as a member of a group. This API is subject to the constraints laid out in the -data model.
- 115.0 Add a group as a component of a second group +data model.
- 115.0 Add a group as a component of a second group
The parties and groups system provides an API for adding a group as a component of a second group. This API is subject to the constraints laid out -in the data model.
- 120.0 Remove a party as a member of a group +in the data model.
- 120.0 Remove a party as a member of a group
The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the -data model.
- 125.0 Remove a group as a component of a second -group +data model.
- 125.0 Remove a group as a component of a second +group
The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid -out in the data model.
- 130.0 Membership check +out in the data model.
- 130.0 Membership check
The parties and groups system provides an API for answering the question: -"Is party P a member of group -G?"
- 135.0 Composition check +"Is party P a member of group +G?"
- 135.0 Composition check
The parties and groups system provides an API for answering the question: -"Is group GC a component of group -GP?"
- 140.0 Get members query +"Is group GC a component of group +GP?"
- 140.0 Get members query
The parties and groups system provides an API for answering the question: -"Which parties are members of group G?"
- 145.0 Get components query +"Which parties are members of group G?"
- 145.0 Get components query
The parties and groups system provides an API for answering the question: -"Which groups are components of group G?"
- 150.0 Member-of-groups query +"Which groups are components of group G?"
- 150.0 Member-of-groups query
The parties and groups system provides an API for answering the question: -"Of which groups is party P a member?"
- 155.0 Component-of-groups query +"Of which groups is party P a member?"
- 155.0 Component-of-groups query
The parties and groups system provides an API for answering the question: -"Of which groups is group G a component?"
- 160.0 Allowed membership check +"Of which groups is group G a component?"
- 160.0 Allowed membership check
The parties and groups system provides an API for answering the question: -"Is party P allowed to become a member of group -G?"
- 165.0 Allowed composition check +"Is party P allowed to become a member of group +G?"
- 165.0 Allowed composition check
The parties and groups system provides an API for answering the question: -"Is group GC allowed to become a component -of group GP?"
- 170.0 Efficiency +"Is group GC allowed to become a component +of group GP?"
- 170.0 Efficiency
Since many pages at a site may check membership in a group before serving a page (e.g., as part of a general permissions check), the data model must support the efficient storage and retrieval of party attributes and -membership.
- 180.0 Ease of Use +membership.
- 180.0 Ease of Use
Since many SQL queries will check membership in a group as part of the where clause, whatever mechanism is used to check membership in SQL should be fairly small and simple.
The user interface is a set of HTML pages that are used to drive the -underlying API. The user interface may provide the following functions:
200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks -outlined in 130.x to 165.x
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/16/2000 Rafael Schloming 0.2 Initial revision 08/19/2000 Mark Thomas 0.3 Edited and reviewed, conforms to requirements template 08/23/2000 Kai Wu 0.4 Further revised, added UI requirements 08/24/2000 Mark Thomas 0.5 Final edits, pending freeze 08/24/2000 Kai Wu 0.6 More revisions, added composition requirements 08/30/2000 Mark Thomas 0.7 More revisions, added composition requirements 09/08/2000 Mark Thomas 200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks +outlined in 130.x to 165.x
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/16/2000 Rafael Schloming 0.2 Initial revision 08/19/2000 Mark Thomas 0.3 Edited and reviewed, conforms to requirements template 08/23/2000 Kai Wu 0.4 Further revised, added UI requirements 08/24/2000 Mark Thomas 0.5 Final edits, pending freeze 08/24/2000 Kai Wu 0.6 More revisions, added composition requirements 08/30/2000 Mark Thomas 0.7 More revisions, added composition requirements 09/08/2000 Mark Thomas View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/index.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/index.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,4 +1,2 @@ -OpenACS Documentation +Table of Contents
- Part I. OpenACS For Everyone
- Part II. For OpenACS Admins
- Part III. For OpenACS Developers
- 4. OpenACS Developer's Guide
- 5. Other Developer Resources
- 6. Engineering Standards
- 7. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.5 Package Manager Requirements
- OpenACS 4.5 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
OpenACS Documentation Table of Contents
- Part I. OpenACS For Everyone
- Part II. For OpenACS Admins
- Part III. For OpenACS Developers
- 4. OpenACS Developer's Guide
- 5. Other Developer Resources
- 6. Engineering Standards
- 7. Kernel Documentation
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6 Package Manager Requirements
- OpenACS 4.6 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,4 +1,2 @@ -Chapter 7. Kernel Documentation +Table of Contents
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.5 Package Manager Requirements
- OpenACS 4.5 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
Chapter�7.�Kernel Documentation Table of Contents
- Overview
- OpenACS 4 Object Model Requirements
- OpenACS 4 Object Model Design
- OpenACS 4 Permissions Requirements
- OpenACS 4 Permissions Design
- OpenACS 4 Groups Requirements
- OpenACS 4 Groups Design
- OpenACS 4 Subsites Requirements
- OpenACS 4 Subsites Design Document
- OpenACS 4.6 Package Manager Requirements
- OpenACS 4.6 Package Manager Design
- OpenACS 4 Security Requirements
- OpenACS 4 Security Design
- OpenACS 4 Security Notes
- OpenACS 4 Request Processor Requirements
- OpenACS 4 Request Processor Design
- Database Access API
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 10 Aug 2002 20:07:20 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 30 Nov 2002 17:16:24 -0000 1.4 @@ -1,24 +1,22 @@ -Overview - Compared to its predecessors, version 4.5 of OpenACS has a much +
Overview + Compared to its predecessors, version 4.6 of OpenACS has a much more structured organization, i.e. the most significant change is found at the system architecture level, reflected in the following hierarchy: -
+The OpenACS 4.5 Kernel, which handles system-wide necessities +
The OpenACS 4.6 Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment. -
The OpenACS 4.5 Core, which comprises all the other packages +
The OpenACS 4.6 Core, which comprises all the other packages that ship with the kernel and are most frequently needed by users, such as templating, bboard, and user registration/management. The packages tend to be developed and distributed with the kernel. -
OpenACS 4.5 Application packages, which typically provide +
OpenACS 4.6 Application packages, which typically provide user-level web services built on top of the Kernel and Core. Such packages include those built by ArsDigita as well as external contributors. Application packages are developed separately from the Kernel, and are typically released independently of it.
This document provides a high level overview of the kernel package. Documentation for the other packages can be found elsewhere. -
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/more-developer-info.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/more-developer-info.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/more-developer-info.html 10 Aug 2002 20:07:20 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/more-developer-info.html 30 Nov 2002 17:16:24 -0000 1.8 @@ -1,4 +1,2 @@ -Chapter 5. Other Developer Resources +Chapter�5.�Other Developer Resources View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,12 +1,12 @@ -OpenACS 4 Object Model Design +
OpenACS 4 Object Model Design ++are his and his alone.The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
The motivation for most of the facilities in the OpenACS 4 Object Model can be +particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
The motivation for most of the facilities in the OpenACS 4 Object Model can be understood in the context of the 3.x code base and the kinds of programming idioms that evolved there. These are listed and discussed below.
Object identification is a central mechanism in OpenACS 4. Every application object in OpenACS 4 has a unique ID which is mapped to a row in a central table @@ -77,14 +77,14 @@ make sure every object the system is to manage is associated with a row in acs_objects. More importantly, if they do this, new services like general comments can be created without requiring existing applications -to "hook into" them via new metadata.
Note: Object identifiers are a good example of metadata +to "hook into" them via new metadata.
Note: Object identifiers are a good example of metadata in the new system. Each row in acs_objects stores information about the application object, but not the application object itself. This becomes more clear if you skip ahead and look at the SQL schema code that defines this table.
Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:
... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... The first row represents an entry in User 123's personal address book, +hypothetical rows in the address_book table:
... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.
In this way, the scoping columns identify the security context in which a @@ -245,8 +245,8 @@ the more limited domain of the metadata model, this is acceptable since the type hierarchy is fairly small. But the object system data model is not designed to support, for example, a huge type tree like the Java runtime -libraries might define.
This last point cannot be over-stressed: the object model is not -meant to be used for large scale application data storage. It is +libraries might define.
This last point cannot be over-stressed: the object model is not +meant to be used for large scale application data storage. It is meant to represent and store metadata, not application data.
Like most data models, the OpenACS Core data model has two levels:
The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)
You can browse the data models themselves from here:
Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Object Model Requirements +
OpenACS 4 Object Model Requirements A major goal in OpenACS 4 is to unify and normalize many of the core services + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
A major goal in OpenACS 4 is to unify and normalize many of the core services of the system into a coherent common data model and API. In the past, these services were provided to applications in an ad-hoc and irregular fashion. Examples of such services include:
General Comments
User/groups
Attribute storage in user/groups
General Permissions
Site wide search
General Auditing
All of these services involve relating extra information and services to @@ -24,7 +24,7 @@ within the OpenACS, and typically corresponds to a single row within the relational database.
The OpenACS 4 Object Model must address five high-level requirements that repeatedly exhibit themselves in the context of existing services in OpenACS 3.x, -as described below.
Object Identifiers for General Services
Generic services require a single unambiguous way of identifying +as described below.
Object Identifiers for General Services
Generic services require a single unambiguous way of identifying application objects that they manage or manipulate. In OpenACS 3.x, there are several different idioms that construct object identifiers from other data. Many modules use a (user_id, group_id, scope) triple combination @@ -46,12 +46,12 @@ that their definition and use is ad-hoc and inconsistent. This makes the construction of generic application-independent services difficult. Therefore, the OpenACS 4 Object Model should provide a centralized and uniform -mechanism for tagging application objects with unique identifiers.
Support for Unified Access Control
Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers.
Support for Unified Access Control
Access control should be as transparent as possible to the application developer. Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:
... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... The first row represents an entry in User 123's personal address book, +hypothetical rows in the address_book table:
... scope user_id group_id ... ... user 123 � ... ... group � 456 ... ... public � � ... The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.
In this way, the scoping columns identify the security context in which a @@ -65,7 +65,7 @@ page, a security problem could result.
Thus the OpenACS 4 Object Model must support a more general access control system that allows access control domains to be hierarchical, and specifiable with a single piece of data, instead of the old composite keys described -above.
Extensible Data Models
Another problem with previous OpenACS data models is that many of the central +above.
Extensible Data Models
Another problem with previous OpenACS data models is that many of the central tables in the system became bloated as they were extended to support an increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special @@ -83,10 +83,10 @@ custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data.
Design Note: While this doesn't really belong in a +between data.
Design Note: While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object -data model exist, which you can read about in Summary and Design Considerations.
Modifiable Data Models
Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in Summary and Design Considerations.
Modifiable Data Models
Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid changes to an application's database queries in the face of any custom @@ -103,7 +103,7 @@ store values for those attributes.
Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This ensures that all applications use the same -base schema, resulting in a uniform and more maintainable system.
Generic Relations
Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system.
Generic Relations
Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was done using mapping tables. The user/groups module has the most highly developed data model for this purpose, using a single table called @@ -127,8 +127,8 @@ that store metadata on application objects. The object type system supports subtyping with inheritance, so new object types can be defined in terms of existing object types.
The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include:
Parties and Groups
Permissions
Each of these is documented elsewhere at length.
The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules:
- 10.0 Object Identification and Storage
Object identification is a central mechanism in the new metadata system. +other parts of the Kernel data model include:
Parties and Groups
Permissions
Each of these is documented elsewhere at length.
The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules:
- 10.0 Object Identification and Storage
Object identification is a central mechanism in the new metadata system. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. Thus the only action required of an application to obtain any general service is to "hook into" the @@ -149,15 +149,15 @@ application data. More importantly, object identifiers will enable developers to readily build and use generic services that work globally across a system.
The object identifiers should be subject to the following -requirements:
10.10 Uniqueness
The object ID should be unique among all the IDs in the entire OpenACS system -in which the object lives.
10.20 Useful as a Reference
Applications should be able to use the unique object ID as a reference, -with which they can fetch any or all of the object's attributes.
10.30 Storable
Object IDs should be storable in tables. e.g. you should be able to use +requirements:
10.10 Uniqueness
The object ID should be unique among all the IDs in the entire OpenACS system +in which the object lives.
10.20 Useful as a Reference
Applications should be able to use the unique object ID as a reference, +with which they can fetch any or all of the object's attributes.
10.30 Storable
Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent -relationships.
10.40 Moveable
Objects should be mobile between databases. That is, information will +relationships.
10.40 Moveable
Objects should be mobile between databases. That is, information will often need to be moved between multiple servers (development, staging, and production), so a mechanism for moving this data is necessary. In addition, a mechanism for tagging these objects in a way similar to CVS would be useful -in determining which objects need to be synchronized.
- 20.0 Object Types
An object type refers to a specification of one or more +in determining which objects need to be synchronized.
- 20.0 Object Types
An object type refers to a specification of one or more attributes to be managed along with a piece of application data.
The object system should provide a data model for describing and representing object types. This data model is somewhat analogous to the Oracle data dictionary, which stores information about all user defined @@ -170,33 +170,33 @@ is meant to be a generalization of this mechanism. The data model should allow developers to at least do everything they used to with user/groups, but without its administrative hassles.
Therefore, the data model must be able to represent object types that have -the following characteristics:
20.10 Type Name
A human readable name for the object type.
20.20 Type Attributes
Attributes whose values are shared by all instances of the object -type.
20.30 Object Attributes
Attributes that are specific to each particular object belonging to a -given type.
The data model must also enforce certain constraints on object types:
20.40 Type Uniqueness
Object type names must be unique.
20.50 Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object type and -any of its parent types.
- 30.0 Type Extension
The Object Model must support the definition of object types that are +the following characteristics:
20.10 Type Name
A human readable name for the object type.
20.20 Type Attributes
Attributes whose values are shared by all instances of the object +type.
20.30 Object Attributes
Attributes that are specific to each particular object belonging to a +given type.
The data model must also enforce certain constraints on object types:
20.40 Type Uniqueness
Object type names must be unique.
20.50 Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object type and +any of its parent types.
- 30.0 Type Extension
The Object Model must support the definition of object types that are subtypes of existing types. A subtype inherits all the attributes of its parent type, and defines some attributes of its own. A critical aspect of the OM is parent types may be altered, and any such change must propagate to child subtypes.
The OM data model must enforce constraints on subtypes that are similar to -the ones on general object types.
30.10 Subtype Uniqueness
Subtype names must be unique (this parallels requirement 10.40).
30.20 Subtype Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object -subtype.
30.30 Parent Type Prerequisite
Subtypes must be defined in terms of parent types that, in fact, already -exist.
30.40
The extended attribute names in a subtype must not be the same as those in -its parent type.
- 35.0 Methods
35.10 Method and Type Association
The OM data model should define a mechanism for associating procedural +the ones on general object types.
30.10 Subtype Uniqueness
Subtype names must be unique (this parallels requirement 10.40).
30.20 Subtype Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object +subtype.
30.30 Parent Type Prerequisite
Subtypes must be defined in terms of parent types that, in fact, already +exist.
30.40
The extended attribute names in a subtype must not be the same as those in +its parent type.
- 35.0 Methods
35.10 Method and Type Association
The OM data model should define a mechanism for associating procedural code, called methods, with objects of a given type. Methods are associated with the each object type - not each object -instance.
35.20 Method Sharing
All instances of a given object type should share the same set of defined -methods for that type.
- 40.0 Object Attribute Value Storage
In addition to information on types, the OM data model provides for the +instance.
35.20 Method Sharing
All instances of a given object type should share the same set of defined +methods for that type.
- 40.0 Object Attribute Value Storage
In addition to information on types, the OM data model provides for the centralized storage of object attribute values. This facility unifies the many ad-hoc attribute/value tables that exist in various OpenACS 3.x data models, such as:
User groups: Each instance of a group type can have custom data.
Photo DB: Users can define their own custom metadata to attach to photograph objects.
Ecommerce: Vendors can attach custom fields to the data model describing -their products.
40.10 Generic Retrieval
Attributes should be stored so that they are retrievable in a way that is +their products.
40.10 Generic Retrieval
Attributes should be stored so that they are retrievable in a way that is independent of the type of the object that they belong to. That is, the only data needed to retrieve an attribute should be the system-wide ID of an -object (see requirement 10.20 above) and the attribute name.
40.20 Inherited Attributes
The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype.
40.30. Constraints on Attributes
The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name.
40.20 Inherited Attributes
The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype.
40.30. Constraints on Attributes
The system should allow the developer to put down constraints on the values that an attribute may hold, for the purposes of maintaining -application specific integrity rules.
- 50.0 Object Contexts
In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules.
- 50.0 Object Contexts
In OpenACS 3.x, there was a notion of "scope" for application objects. An object could be belong to one of three scopes: public, group or user. This provided a crude way to associate objects with particular scopes in the system, but it was awkward to use and limited in flexibility.
The OpenACS 4 Object Model provides a generalized notion of scope that allows @@ -205,66 +205,64 @@ object has no explicit permissions attached to it, then it inherits permissions from its context.
The context data model also forms the basis of the subsites system, and is a basic part of the permissions system, -described in separate documents.
The context data model should provide the following facilities:
50.10 Unique ID
Every context should have a unique ID in the system.
50.20 Tree Structure
The data model should support a tree structured organization of contexts. +described in separate documents.
The context data model should provide the following facilities:
50.10 Unique ID
Every context should have a unique ID in the system.
50.20 Tree Structure
The data model should support a tree structured organization of contexts. That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts -(i.e. contexts can have children).
50.30 Data Model Constraints
All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children).
50.30 Data Model Constraints
All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the -implementation.
Note:
The current system interprets the NULL context as meaning the default +implementation.
Note:
The current system interprets the NULL context as meaning the default "site-wide" context in some sense. I wanted to note this fact for others, but there is no need to make this a requirement of the system. I think it would be reasonable to have a NULL context be an error (psu -8/24/2000).
- 55.0 Object Relations
The data model should include a notion of pair-wise relations between +8/24/2000).
- 55.0 Object Relations
The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of the form "object X is related to object Y by relationship R," and also be -able to attach attributes to these facts.
The API should let programmers accomplish the following actions:
- 60.0 Object Type Creation
60.10 Create a New Object Type
The object system API should provide a procedure call that creates a new +able to attach attributes to these facts.
The API should let programmers accomplish the following actions:
- 60.0 Object Type Creation
60.10 Create a New Object Type
The object system API should provide a procedure call that creates a new object type by running the appropriate transactions on the object system data model. This API call is subject to the constraints laid out in the data -model. We call this operation "instantiating" an object.
60.20 Create a New Object Subtype
The object system API should provide a procedure call for creating +model. We call this operation "instantiating" an object.
60.20 Create a New Object Subtype
The object system API should provide a procedure call for creating subtypes of a given type. Operationally, this API is the same as requirement 60.10. Instances of subtypes automatically contain all attributes of the parent type in addition to all attributes of the subtype. This API is subject -to the constraints laid out in the data model.
60.30 Create a New Relation Type
There should be an API call to create a new type of object relation. +to the constraints laid out in the data model.
60.30 Create a New Relation Type
There should be an API call to create a new type of object relation. Relation types can be modeled as object types. The API below for manipulating -attributes can then be used to add attributes to relation types.
- 70.0 Update an Object Type
The object system API must allow the programmer to modify, add, and delete +attributes can then be used to add attributes to relation types.
- 70.0 Update an Object Type
The object system API must allow the programmer to modify, add, and delete attributes from any object type. Updates should be propagated to any child subtypes. This API is subject to the constraints laid out in the data -model.
- 80.0 Delete an Object Type
The system provides an API call for deleting an object type.
80.10
Deleting an object type destroys all instances of the type. It should be +model.
- 80.0 Delete an Object Type
The system provides an API call for deleting an object type.
80.10
Deleting an object type destroys all instances of the type. It should be an error to delete types that have dependent subtypes. This API is subject to -the constraints laid out in the data model.
80.10.10
However, the programmer should also be able to specify that all the +the constraints laid out in the data model.
80.10.10
However, the programmer should also be able to specify that all the subtypes and instances of those subtypes be destroyed before destroying the object type. This is similar to a "delete cascade" constraint in -SQL.
- 90.0 Object Instance Creation and Destruction
The system must provide API calls to manage the creation and destruction -of object instances.
90.10 Create an Instance of an Object Type
The system should provide an API call for creating a new instance of a +SQL.
- 90.0 Object Instance Creation and Destruction
The system must provide API calls to manage the creation and destruction +of object instances.
90.10 Create an Instance of an Object Type
The system should provide an API call for creating a new instance of a given object type. The new instance should be populated with values for each of the attributes specified in the definition of the type. In addition, it should be possible to create the new instance with an optional context ID -that refers to the default context that the object will live in.
90.20 Delete an Object Instance
The OM should provide an API call for object deletion. Objects can be +that refers to the default context that the object will live in.
90.20 Delete an Object Instance
The OM should provide an API call for object deletion. Objects can be deleted only when no other objects in the system refer to them. Since it might not be practical to provide a mechanism like "delete cascade" here in a reliable way, providing such a facility in the system is -optional.
- 94.0 Object Relation Creation and Destruction
The system must provide API calls to manage the creation and destruction -of object relations.
- 94.10 Create an Object Relation
The OM must provide an API call to declare that two objects are related to +optional.
- 94.0 Object Relation Creation and Destruction
The system must provide API calls to manage the creation and destruction +of object relations.
- 94.10 Create an Object Relation
The OM must provide an API call to declare that two objects are related to each other by a given relation type. This API call should also allow -programmers to attach attributes to this object relation.
- 94.20 Destroy an Object Relation
There should be an API call for destroying object relations and their -attributes.
- 95.10 Create and Destroy Contexts
The system should provide an API to create and destroy object -contexts.
- 100.10 Set Attribute Values for an Object
The system should provide an API for updating the attribute values of a -particular instance of an object type.
- 110.10 Get Attribute Values for an Object
The system should provide an API for retrieving attribute values from a -particular instance of an object type.
- 120.10 Efficiency
The Object Model must support the efficient storage and retrieval of +programmers to attach attributes to this object relation.
- 94.20 Destroy an Object Relation
There should be an API call for destroying object relations and their +attributes.
- 95.10 Create and Destroy Contexts
The system should provide an API to create and destroy object +contexts.
- 100.10 Set Attribute Values for an Object
The system should provide an API for updating the attribute values of a +particular instance of an object type.
- 110.10 Get Attribute Values for an Object
The system should provide an API for retrieving attribute values from a +particular instance of an object type.
- 120.10 Efficiency
The Object Model must support the efficient storage and retrieval of object attributes. Since the OM is intended to form the core of many general services in the OpenACS, and these services will likely make extensive use of the OM tables, queries on these tables must be fast. The major problem here seems to be supporting subtyping and inheritance in a way that does not severely -impact query performance.
- 130.10 Ease of Use
Most OpenACS packages will be expected to use the Object Model in one way or +impact query performance.
- 130.10 Ease of Use
Most OpenACS packages will be expected to use the Object Model in one way or another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue requirements on an application's data model. In other words, it should be easy to "hook into" the object model, and that ability should not have a major impact -on the application data model.
Note: Is the API the only way to obtain values? How does -this integrate with application level SQL queries?
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/10/2000 Bryan Quinn 0.2 Major re-write 08/11/2000 Pete Su 0.3 Draft completed after initial reviews 08/22/2000 Pete Su 0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu � Final edits before freeze 08/24/2000 Pete Su 0.5 Edited for consistency 08/27/2000 Kai Wu 0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su 0.7 Added requirement that knowledge-level objects must be moveable between +on the application data model. Note: Is the API the only way to obtain values? How does +this integrate with application level SQL queries?
+requirements on relation types.Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/10/2000 Bryan Quinn 0.2 Major re-write 08/11/2000 Pete Su 0.3 Draft completed after initial reviews 08/22/2000 Pete Su 0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu � Final edits before freeze 08/24/2000 Pete Su 0.5 Edited for consistency 08/27/2000 Kai Wu 0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su 0.7 Added requirement that knowledge-level objects must be moveable between databases. 08/29/2000 Richard Li 0.8 Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague -requirements on relation types. 09/06/2000 Pete Su 0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu 09/06/2000 Pete Su 0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 10 Aug 2002 20:07:20 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 30 Nov 2002 17:16:24 -0000 1.4 @@ -1,4 +1,28 @@ -Overview +Overview + OpenACS (Open Architecture Community System) is an advanced + toolkit for building scalable, community-oriented web applications. + If you're thinking of building an enterprise-level web application, + OpenACS is a solid, proven foundation that will give you a 3-6 month headstart. +
+ OpenACS is also a collection of pre-built applications and services that + you can use to build your web site/application. Through a modular architecture, + OpenACS has packages for user/groups management, content management, e-commerce, + news, FAQ, calendar, forums, bug tracking, full-text searching, and + much more. +
+ OpenACS relies on AOLserver, + the free, multithreaded, scalable, Tcl-enabled, web/application server used by + America On-Line for most of its web sites, and a true acid-compliant + Relational Database Management System (RDBMS). Currently OpenACS supports + PostgreSQL, an open source RDBMS, and Oracle. (read more) +
+ The OpenACS toolkit is based on the ArsDigita Community System. ArsDigita + (now part of Red Hat, Inc.) kindly made their work available under the + GPL, + making all of this possible. +
+ The OpenACS community would like to hear your comments and help you + in your endeavors with the system. Stop by our web site + and feel free to ask a question, post ideas or whatever. +
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/other-developer-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/other-developer-overview.html,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/other-developer-overview.html 10 Aug 2002 20:07:20 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/other-developer-overview.html 30 Nov 2002 17:16:24 -0000 1.4 @@ -1,4 +1,2 @@ -Overview +Overview View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Permissions Design +
OpenACS 4 Permissions Design Tcl in packages/acs-kernel
The goal of the Permissions system is to provide generic means to both @@ -48,14 +48,14 @@
The set of all defined privileges.
- acs_privilege_method_rules -
A relation describing the set of methods directly +
A relation describing the set of methods directly associated with each privilege.
- acs_privilege_hierarchy -
A relation describing which privileges directly +
A relation describing which privileges directly "contain" other privileges.
- acs_permissions
A table with one (party, object, privilege) -row for every privilege directly granted on any object in +row for every privilege directly granted on any object in the system - this is a denormalization of acs_privilege_method_rules and acs_privilege_hierarchy
There are also a number of views to make it easier to ask specific @@ -78,7 +78,7 @@ a party is a member of a group (at any depth).
- acs_object_party_method_map
Relation with every (object, party, method) -tuple implied by the above trees.
In general, only acs_object_party_method_map +tuple implied by the above trees.
In general, only acs_object_party_method_map should be used for queries from other modules. The other views are intermediate steps in building that query.
The data model also includes two simple PL/SQL procedures (acs_permission.grant_permission and @@ -95,15 +95,15 @@ acs_privilege_hierarchy)
objects get access control from direct grants, or inherit permissions from their context (unless the "don't inherit" flag is set)
There are three essential areas in which all transactions in the -permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This +permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide administrator chooses to change permissions policy.
These steps involve directly manipulating the acs_methods, acs_privileges, and acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide -administrators.
"Modification of permissions" - involves fairly +administrators.
"Modification of permissions" - involves fairly common operations. Users are typically able to administer permissions for objects they themselves create. The two basic operations here are "grant" and "revoke". Granting permissions is done via @@ -112,7 +112,7 @@ acs_permissions table.
Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on an object, the user must have the administer_privileges method -permission on that object.
"Queries on permissions" - by far the most +permission on that object.
"Queries on permissions" - by far the most common operation is querying the permissions database. Several kinds of questions are commonly asked: First, and most commonly, "Can this party perform this method on this object?" Two Tcl functions are provided to @@ -127,15 +127,15 @@ for appropriate methods.
Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done by querying against acs_permissions.
The API to the permissions system consists of a few well-known tables, -plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and +plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and acs_privilege_method_rules manage the set of permissions in the system. At installation time, a package will add to these three tables to introduce new permissions into the system.
The main table for queries is acs_object_party_method_map, which contains (object, party, method) triples for all allowed operations in the system.
Also of interest for queries is acs_permissions, which lists directly granted privileges. Neither acs_object_party_method_map (which is a view) nor acs_permissions should be updated -directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for +directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for an object. It should be given an (object, party, privilege) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure @@ -154,7 +154,7 @@ privilege acs_permissions.privilege%TYPE );
These procedures are defined in -permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this +permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this user perform this method on this object?" One returns true or false, the other presents an error page.
To receive a true or false value, Tcl code should call:
ad_permission_p $object_id $object_type $method -user_id $user_id @@ -184,6 +184,4 @@
- Documentation author -
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 10 Aug 2002 20:07:20 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Permissions Requirements +
OpenACS 4 Permissions Requirements +current user has access to should not add more than one line to a query.This document records requirements for the OpenACS 4 Permissions system, a + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
This document records requirements for the OpenACS 4 Permissions system, a component of the OpenACS 4 Kernel. The Permissions system is meant to unify and centralize the handling of access and control on a given OpenACS 4 system.
Any multi-user software system must address the general problem of permissions, or "who can do what, on what." On web services, which @@ -15,7 +15,7 @@ manner reduces both cost and risk: cost, in that less code has to be written and maintained for dealing with recurring permissions situations; risk, in that we need not rely on any single programmer's diligence to ensure -access control is implemented and enforced correctly.
Historical Motivations
In earlier versions of the OpenACS, permissions and access control was handled +access control is implemented and enforced correctly.
Historical Motivations
In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way @@ -33,14 +33,14 @@ common administrative interface, and easily deployed and maintained access control. The system must be flexible enough to support every access model required in OpenACS applications, but not so flexible that pieces will go unused -or fall outside the common administrative interfaces.
Terminology
The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.
Terminology
The primary question an access control system must answer is a three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the context of OpenACS Permissions, our simple sentence is, "Can this party -perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a +perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a distinguishable actor whose access may be controlled, this special word is used because one person may be represented by several parties, and one party -may represent many users (or no users at all).
The object of the sentence is "target" - this +may represent many users (or no users at all).
The object of the sentence is "target" - this is an entity, or object, that the party wishes to perform some action on. An entity/object here is anything that can be put under access control.
The verb of the sentence is "operation" - a behavior on the OpenACS system subject to control, this word is used to represent the fact that a @@ -50,45 +50,43 @@ that operation.
Examples of the essential question addressed by the Permissions system: Can jane@attacker.com delete the web security bboard? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news -instance?
10.0 Granularity
The system must support access control down to the level of a single +instance?
10.0 Granularity
The system must support access control down to the level of a single entity (this would imply down to the level of a row in the OpenACS Objects data -model).
20.0 Operations
The system itself must be able to answer the essential permissions -question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform -operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may -perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may -party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets -may party P perform operation O?"
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS +model).
20.0 Operations
The system itself must be able to answer the essential permissions +question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform +operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may +perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may +party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets +may party P perform operation O?"
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS package. Some privileges are of general utility (e.g. "read" and "write"). Others are of more limited use (e.g. "moderate" - applies mainly to a package like bboard, where many users are contributing content simultaneously). A package defining its own privileges should do so with moderation, being careful not to overload a privilege like -"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain +"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain privileges under others. For example, anyone with the "admin" privilege may also automatically receive "read", "write", -"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for +"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for aggregation will probably be addressed by the OpenACS 4 "Groups" system. Regardless of the exact behavior of aggregate parties, if an aggregate party exists, then access which is granted to the aggregate party -should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from +should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from some context. For example, if you do not have read access to a bboard, you -should not have read access to a message in that bboard.
70.20 Overriding
It must be possible to override defaults provided by the context of an -object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they +should not have read access to a message in that bboard.
70.20 Overriding
It must be possible to override defaults provided by the context of an +object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they would get by default. (For example, a user does not have the right to edit any message on a bboard. But a user does possibly have the right to edit -their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their +their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their inherited privileges would have allowed. (For example, a subdirectory in the file-storage might normally have its parent directory as context. It should -be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check (20.40) must be efficient enough for general use, i.e. scalable under fairly heavy website traffic. It can be expected that almost every page will contain at least one basic access check, and most pages will contain an allowed targets check (20.40).
In particular, constraining a SELECT to return only rows the current user has access to should not be much slower than the SELECT -on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where +on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly small and simple.
In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 8/17/2000 John Prevost 0.2 Revised, updated with new terminology 8/25/2000 John Prevost 0.3 Edited, reformatted to conform to requirements template, pending -freeze. 8/26/2000 Kai Wu 0.4 Edited for ACS 4 Beta release. 10/03/2000 Kai Wu Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 8/17/2000 John Prevost 0.2 Revised, updated with new terminology 8/25/2000 John Prevost 0.3 Edited, reformatted to conform to requirements template, pending +freeze. 8/26/2000 Kai Wu 0.4 Edited for ACS 4 Beta release. 10/03/2000 Kai Wu View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 30 Nov 2002 17:16:24 -0000 1.2 @@ -0,0 +1,693 @@ + +OpenACS 4.x Permissions Tediously Explained + by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello +
+ The general permissions system has a relatively complex data model in OpenACS 4.x. + Developers who haven't had the time to learn the internals of the data model + may end up writing seemingly correct code that crashes their system in + weird ways. This writeup is the result of my running into such a piece + of code and trying to understand exactly what went wrong. + It is geared towards developers who understand the general permissions + system to the extent that is described in the + + OpenACS 4.x Permisisons documentation, + but who haven't had the opportunity to take a long, careful look at the + system internals. +
+ In OpenACS 4.x, most of the interesting tables are expected to extend (subtype) + the acs_objects table, i.e. they are expected to have an integer + primary key column that references the object_id column of + acs_objects. +
+create table acs_objects ( + object_id integer + not null + constraint acs_objects_pk primary key, + object_type + not null + constraint acs_objects_object_type_fk references acs_object_types (object_type), + context_id + constraint acs_objects_context_id_fk references acs_objects(object_id), + security_inherit_p char(1) default 't' + not null, + constraint acs_objects_sec_inherit_p_ck + check (security_inherit_p in ('t', 'f')), + creation_user integer, + creation_date date default sysdate not null, + creation_ip varchar2(50), + last_modified date default sysdate not null, + modifying_user integer, + modifying_ip varchar2(50), + constraint acs_objects_context_object_un + unique (context_id, object_id) disable +); ++ This means that any interesting entity (object) + in the system has an entry in the acs_objects. This + allows developers to define relationships between any two entities A + and B by defining a relationship between their corresponding entries + in the acs_objects table. One of the applications of this + powerful capability is the general permissions system. +
+ At the heart of the permission system are two tables: acs_privileges + and acs_permissions. +
+ create table acs_privileges ( + privilege varchar2(100) not null + constraint acs_privileges_pk primary key, + pretty_name varchar2(100), + pretty_plural varchar2(100) + ); ++ create table acs_permissions ( + object_id + not null + constraint acs_permissions_on_what_id_fk references acs_objects (object_id), + grantee_id + not null + constraint acs_permissions_grantee_id_fk references parties (party_id), + privilege + not null + constraint acs_permissions_priv_fk references acs_privileges (privilege), + constraint acs_permissions_pk + primary key (object_id, grantee_id, privilege) + ); +
+ The acs_privileges table stores + named privileges like read, + write, delete, create, and + admin. The acs_permissions + table stores assertions of the form: +
+ Who (grantee_id) can do what (privilege) + on which object (object_id). +
+ The naive approach to managing system security would be to require application developers + to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users + who have the read privilege on all objects, then we would need to store 100,000,000 + entries of the form: +
Table�5.1.�
object_id grantee_id privilege object_id_1 user_id_1 'read' object_id_1 user_id_2 'read' ... object_id_1 user_id_n 'read' object_id_2 user_id_1 'read' object_id_2 user_id_2 'read' ... object_id_2 user_id_n 'read' ... ... object_id_m user_id_1 'read' object_id_m user_id_2 'read' ... object_id_m user_id_n 'read' + Although quite feasible, this approach fails to take advantage of the fact + that objects in the system are commonly organized hierarchally, + and permissions usually follow the hierarchical structure, so that if user + X has the read privilege on object A, she typically + also has the read privilege on all objects attached under A. +
+ The general permission system, as implemented in OpenACS 4.x, takes advantage + of the hierarchical organization of objects to unburden developers of the + necessity to explicitly maintain security information for every single + object. There are three kinds of hierarchies involved. + These are discussed in the following sections. +
+ Suppose objects A, B, ..., + and F form the following hierarchy. +
Table�5.2.�
A + object_id=10 +
B + object_id=20 +
C + object_id=30 +
D + object_id=40 +
E + object_id=50 +
F + object_id=60 +
+ This can be represented in the + acs_objects table + by the following entries: +
+ The first entry tells us that object 20 is the descendant of object 10, and + the third entry shows that object 40 is the descendant of object 20. By + running a CONNECT BY query, + we can compute that object 40 is the second-generation descendant of object 10. + With this in mind, if we want to record the fact that user Joe has the read privilege on objects + A, ..., F, we only need to record one entry in the + acs_permissions table. +
+ The fact that Joe can also read B, C, + ..., and F can be derived by ascertaining that these objects + are children of A by traversing the context hierarchy. + As it turns out, hierarchical queries are expensive. As + Rafael Schloming put it so aptly, Oracle can't deal with hierarchies for shit. +
+ One way to solve this problem is to cache a flattened view of the context tree like so: +
+ Note that the number of entries in the flattened view grows exponentially with + respect to the depth of the context tree. For instance, if you have a fully + populated binary tree with a depth of n, then the number of entries + in its flattened view is +
+ 1 + 2*2 + 3*4 + 4*8 + 5*16 + ... + (n+1)*2n = n*2n+1 + 1
+ Despite its potentially great storage costs, maintaining a + flattened representation of the context tree is exactly what OpenACS 4.x + does. The flattened context tree is stored in the + acs_object_context_index table. +
+ create table acs_object_context_index ( + object_id + not null + constraint acs_obj_context_idx_obj_id_fk references acs_objects(object_id), + ancestor_id + not null + constraint acs_obj_context_idx_anc_id_fk references acs_objects(object_id), + n_generations integer + not null + constraint acs_obj_context_idx_n_gen_ck check (n_generations >= 0), + constraint acs_object_context_index_pk + primary key (object_id, ancestor_id) + ) organization index; +
+ A few things to note about this table are these. Number one, it is + an index-organized + table, which means it is substantially optimized for access by primary key. + Number two, as the above computations suggest, the size of the table + grows polynomially + with respect to the average number of descendants that an object + has, and exponentially + with respect to the depth of the context tree. +
+ The acs_object_context_index is kept in sync with the + acs_objects + table by triggers like this: +
+create or replace trigger acs_objects_context_id_in_tr +after insert on acs_objects +for each row +begin + insert into acs_object_context_index + (object_id, ancestor_id, n_generations) + values + (:new.object_id, :new.object_id, 0); + + if :new.context_id is not null and :new.security_inherit_p = 't' then + insert into acs_object_context_index + (object_id, ancestor_id, + n_generations) + select + :new.object_id as object_id, ancestor_id, + n_generations + 1 as n_generations + from acs_object_context_index + where object_id = :new.context_id; + elsif :new.object_id != 0 then + -- 0 is the id of the security context root object + insert into acs_object_context_index + (object_id, ancestor_id, n_generations) + values + (:new.object_id, 0, 1); + end if; +end; +
+ One final note about + acs_objects. By setting + an object's security_inherit_p column to 'f', you can stop permissions + from cascading down the context tree. In the following example, Joe does not have + the read permissions on C and F. +
Table�5.6.�
+A
+object_id=10
+readable�by�Joe
+ ������
+B
+object_id=20
+readable�by�Joe
+��������������
+C
+object_id=30
+security_inherit_p�=�'f'
+not�readable�by�Joe
+ ������
+D
+object_id=40
+ ������
+E
+object_id=50
+ ������
+F
+object_id=60
+security_inherit_p�=�'f'
+not�readable�by�Joe
+ ������+ Privileges are also organized hierarchically. In addition to the five main system privileges + defined in the ACS Kernel data model, application developers may define their own. For instance, + the Bboard package defines the following privileges: +
Table�5.7.�
privilege create_category create_forum create_message delete_category delete_forum delete_message moderate_forum read_category read_forum read_message write_category write_forum write_message + By defining parent-child relationship between privileges, the OpenACS data model + makes it easier for developers to manage permissions. Instead of granting + a user explicit read, write, delete, + and create + privileges on an object, it is sufficient to grant the user the admin + privilege to which the first four privileges are tied. To give + a more detailed example, the Bboard privileges are structured + as follows. +
Table�5.8.�
admin create delete read write moderate forum create category create forum create message delete category delete forum delete message read category read forum read message write category write forum write message + The parent-child relationship between privileges is represented in + the acs_privilege_hierarchy table: +
+ create table acs_privilege_hierarchy ( + privilege + not null + constraint acs_priv_hier_priv_fk references acs_privileges (privilege), + child_privilege + not null + constraint acs_priv_hier_child_priv_fk references acs_privileges (privilege), + constraint acs_privilege_hierarchy_pk + primary key (privilege, child_privilege) + ); +
+ As in the case of the context hierarchy, it is convenient to have a flattened representation + of this hierarchal structure. This is accomplished by defining the following view. +
+ create or replace view acs_privilege_descendant_map + as + select + p1.privilege, + p2.privilege as descendant + from + acs_privileges p1, + acs_privileges p2 + where + p2.privilege in + (select + child_privilege + from + acs_privilege_hierarchy + start with + privilege = p1.privilege + connect by + prior child_privilege = privilege + ) + or p2.privilege = p1.privilege; +
+ As the number of different privileges in the system is expected to be + reasonably small, there is no pressing need to cache the flattened ansector-descendant + view of the privilege hierarchy in a specially maintained table like + it is done in the case of the context hierarchy. +
+ Now for the third hierarchy playing a promiment role in the permission system. The party + data model is set up as follows. +
+ create table parties ( + party_id + not null + constraint parties_party_id_fk references acs_objects (object_id) + constraint parties_pk primary key, + email varchar2(100) + constraint parties_email_un unique, + url varchar2(200) + ); +
+ create table persons ( + person_id + not null + constraint persons_person_id_fk references parties (party_id) + constraint persons_pk primary key, + first_names varchar2(100) + not null, + last_name varchar2(100) + not null + ); +
+ create table users ( + user_id + not null + constraint users_user_id_fk references persons (person_id) + constraint users_pk primary key, + password char(40), + -- other attributes + ); +
+ create table groups ( + group_id + not null + constraint groups_group_id_fk references parties (party_id) + constraint groups_pk primary key, + group_name varchar2(100) not null + ); +
+ Recall that the grantee_id column of the + acs_permissions table references + parties.party_id. + This means that you can grant a privilege on an object to a party, person, user, or group. + Groups represent aggregations of parties. The most common scenario that you are likely + to encounter is a group that is a collection of users, although you could also + have collections of persons, groups, parties, or any mix thereof. +
+ Given that the most common use of groups is to partition users, how do you + build groups? One way is to grant membership explicitly. If you have + a group named Pranksters, you can assign membership to Pete, + Poly, and Penelope. The fact that these users are members of the + Pranksters group will be recorded in the + membership_rels and acs_rels tables: +
+ create table acs_rels ( + rel_id + not null + constraint acs_rels_rel_id_fk references acs_objects (object_id) + constraint acs_rels_pk primary key, + rel_type + not null + constraint acs_rels_rel_type_fk references acs_rel_types (rel_type), + object_id_one + not null + constraint acs_object_rels_one_fk references acs_objects (object_id), + object_id_two + not null + constraint acs_object_rels_two_fk references acs_objects (object_id), + constraint acs_object_rels_un + unique (rel_type, object_id_one, object_id_two) + ); +
+ create table membership_rels ( + rel_id + constraint membership_rel_rel_id_fk references acs_rels (rel_id) + constraint membership_rel_rel_id_pk primary key, + -- null means waiting for admin approval + member_state varchar2(20) + constraint membership_rel_mem_ck + check (member_state in ('approved', 'banned', 'rejected', 'deleted')) + ); +
+ The acs_rels + table entries would look like so: +
Table�5.10.�
rel_type object_one object_two + membership_rel + + Pranksters + + Pete + + membership_rel + + Pranksters + + Poly + + membership_rel + + Pranksters + + Penelope + + Another way of building up groups is by adding subgroups. Suppose + we define Merry Pranksters and Sad Pranksters as subgroups + of Pranksters. We say that the Pranksters group + is composed of + groups Merry Pranksters and Sad Pranksters. This + information is stored in the acs_rels + and composition_rels tables. +
+create table composition_rels ( + rel_id + constraint composition_rel_rel_id_fk references acs_rels (rel_id) + constraint composition_rel_rel_id_pk primary key +); +
+ The relevant entries in the + acs_rels look like so. +
Table�5.11.�
rel_type object_one object_two + composition_rel + + Pranksters + + Merry Pranksters + + composition_rel + + Pranksters + + Sad Pranksters + + The composition relationship means that if I add Matt, Mel, and Mary to the + Merry Pranksters, + they should also automatically become members of the Pranksters group. + The situation we are + facing in trying to determine whether or not a user is member of a group is similar to the one + discussed above in the case of the context hierarchy. Groups can form hierarchies with + respect to the composition relationship. The compositon relationship is transitive. If + G1 is a subgroup of G2, and G2 is a subgroup of G3, then + G1 is a subgroup of G3; that is, any member of G1 is also a member + of G3. +
+ Traversing the group composition hierarchy requires running + hierarchical queries, + which are expensive in Oracle. As we saw in the Context Hierarchy section, one way of + reducing the performance hit incurred by hierarchical queries is to cache query results in + a table maintained by triggers. The OpenACS 4.x data model defines two such tables: +
+ create table group_component_index ( + group_id not null + constraint group_comp_index_group_id_fk + references groups (group_id), + component_id not null + constraint group_comp_index_comp_id_fk + references groups (group_id), + rel_id not null + constraint group_comp_index_rel_id_fk + references composition_rels (rel_id), + container_id not null + constraint group_comp_index_cont_id_ck + references groups (group_id), + constraint group_component_index_ck + check (group_id != component_id), + constraint group_component_index_pk + primary key (group_id, component_id, rel_id) + ) organization index; +
+ create table group_member_index ( + group_id + not null + constraint group_member_index_grp_id_fk references groups (group_id), + member_id + not null + constraint group_member_index_mem_id_fk references parties (party_id), + rel_id + not null + constraint group_member_index_rel_id_fk references membership_rels (rel_id), + container_id + not null + constraint group_member_index_cont_id_fk references groups (group_id), + constraint group_member_index_pk + primary key (member_id, group_id, rel_id) + ) organization index; +
+ The group_component_index table stores a flattened representation of the + group composition hierarchy that is maintained in sync with the acs_rels + and composition_rels tables through triggers. +
+ As far as the group_member_index table goes, I am not sure I understand its + purpose. It maintains group-member relationships that are resolved with respect + to group composition. Note that information stored in + group_member_index can be trivially derived by joining + membership_rels, + acs_rels, + and group_component_index. Here + is a view that does it. (This view is not part of the OpenACS Kernel data model.) +
+create or replace view group_member_view +as +select + gci.group_id, r.object_id_two as member_id +from + ( + select + group_id, group_id as component_id + from + groups + union + select + group_id, component_id + from + group_component_index + ) gci, + membership_rels mr, + acs_rels r +where + mr.rel_id = r.rel_id + and r.object_id_one = gci.component_id; +
+ A heuristic way to verify that group_member_view is essentially identical + to group_member_index is to compute the + symmetric difference between the two: +
+select + group_id, member_id +from + ( + select group_id, member_id from group_member_view + minus + select group_id, member_id from group_member_index + ) +union +select + group_id, member_id +from + ( + select group_id, member_id from group_member_index + minus + select group_id, member_id from group_member_view + ) +
+ The query returns no rows. The important point is, if we + have a flattened view of the composition hierarchy -- like one provided + by the group_component_index table -- + membership relationship resolution can be computed trivially with no hierarchical + queries involved. There is no need to keep the view in a denormalized + table, unless doing so results in substantial performance gains. +
+ Security information is queried by calling the acs_permission.permission_p + function in OpenACS 4.x. +
+ create or replace package body acs_permission + as + -- some stuff removed for the sake of brevity + + function permission_p ( + object_id acs_objects.object_id%TYPE, + party_id parties.party_id%TYPE, + privilege acs_privileges.privilege%TYPE + ) return char + as + exists_p char(1); + begin + -- XXX This must be fixed: -1 shouldn't be hardcoded (it is the public) + select decode(count(*),0,'f','t') into exists_p + from acs_object_party_privilege_map + where object_id = permission_p.object_id + and party_id in (permission_p.party_id, -1) + and privilege = permission_p.privilege; + return exists_p; + end; + + end acs_permission; +
+ The function simply queries + acs_object_party_privilege_map, + which is a humongous view that joins three flattened hierarchies: + the context tree, the privilege hierarchy, + the party composition (and membership) hierarchy. As such, + it contains an extremely large number of rows. About + the only kind of query you can run against it is the one + performed by the acs_permission.permission_p + function. Anything other than that would take forever to + finish or would ultimately result in an Oracle error. +
+ For example, do not try to do things like +
+select count(*) + from acs_object_party_privilege_map; +
+ To give another example of things to avoid, I have seen code like this: +
+ declare + cursor cur is + select + object_id, party_id + from + acs_object_party_privilege_map + where + privilege = 'foo_create'; + begin + -- revoke all 'foo_create' permissions + for rec in cur + loop + acs_permission.revoke_permission ( + object_id => rec.object_id, + grantee_id => rec.party_id, + privilege => 'foo_create' + ); + end loop; + + acs_privilege.remove_child('admin','foo_create'); + acs_privilege.drop_privilege('foo'); + + end; + / +
+ The acs_permission.revoke_permission function merely runs a + delete statement like so: +
+ delete from + acs_permissions + where + object_id = revoke_permission.object_id + and grantee_id = revoke_permission.grantee_id + and privilege = revoke_permission.privilege; +
+ Note that in the above example, acs_permissions had only + one entry that needed to be deleted: +
+ The above script would never get around to deleting this entry because it had + to loop through a gazillion rows in the humongous + acs_object_party_privilege_map view. +
+create or replace view acs_object_party_privilege_map +as +select + ogpm.object_id, + gmm.member_id as party_id, + ogpm.privilege +from + acs_object_grantee_priv_map ogpm, + group_member_map gmm +where + ogpm.grantee_id = gmm.group_id +union +select + object_id, + grantee_id as party_id, + privilege +from + acs_object_grantee_priv_map; +
+create or replace view acs_object_grantee_priv_map +as +select + a.object_id, + a.grantee_id, + m.descendant as privilege +from + acs_permission_all a, + acs_privilege_descendant_map m +where + a.privilege = m.privilege; +
+create or replace view acs_permissions_all +as +select + op.object_id, + p.grantee_id, + p.privilege +from + acs_object_paths op, + acs_permissions p +where + op.ancestor_id = p.object_id; +
+create or replace view acs_object_paths +as +select + object_id, + ancestor_id, + n_generations +from + acs_object_context_index; +
+ +create or replace view group_member_map +as +select + group_id, + member_id, + rel_id, + container_id +from + group_member_index; +
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/rp-design.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Request Processor Design +
OpenACS 4 Request Processor Design -pageroot -- Any directory that contains scripts and/or +provides to the browser.
+pageroot -- Any directory that contains scripts and/or static files intended to be served in response to HTTP requests. A typical -OpenACS installation is required to serve files from multiple pageroots.
global pageroot -(/web/servicename/www) -- Files appearing under +OpenACS installation is required to serve files from multiple pageroots.
global pageroot +(/web/servicename/www) -- Files appearing under this pageroot will be served directly off the base url -http://www.servicename.com/
package root -(/web/servicename/packages) -- Each subdirectory of +http://www.servicename.com/
package root +(/web/servicename/packages) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several -packages.
package pageroot -(/web/servicename/packages/package_key/www) --- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is +packages.
package pageroot +(/web/servicename/packages/package_key/www) +-- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is a global namespace containing variables associated with the current -request.
abstract URL -- A URL with no extension that doesn't -directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL +request.
abstract URL -- A URL with no extension that doesn't +directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL that has been translated into a file system path (probably by prepending the appropriate pageroot), but still doesn't have any extension and so does -not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file -or path that actually references something in the filesystem.
Package Lookup
One of the first things the request processor must do is to determine which package instance a given request references, and based on this information, which pageroot to use when searching for a file to serve. During this process the request processor divides the URL into two pieces. The first portion identifies the package instance. The rest identifies the path into the package pageroot. For example if the news package is mounted on /offices/boston/announcements/, then a request for /offices/boston/announcements/index would be split into the -package_url (/offices/boston/announcements/), and the +package_url (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be -able to figure out which package_id is associated with a +able to figure out which package_id is associated with a given package_url, and package mountings must be persistent across server restarts and users must be able to manipulate the mountings on a live site, -therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete +therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the session security system. After authentication has been performed the user is authorized to have read access for the given package by the OpenACS 4 Permissions Design. If authorization succeeds then the request is served, otherwise it is -aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list +aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list of abstract paths and searches each path for a concrete file. The first path searched is composed of the package pageroot with the extra portion of the URL appended. The second abstract path consists of the global pageroot with @@ -60,16 +60,16 @@ directory. Files take precedence over directory listings, so an index file in the global pageroot will be served instead of a directory listing in the package pageroot, even though the global pageroot is searched later. If a -file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request -processor searches the filesystem for a virtual url handler -(.vuh) file. This file contains normal tcl code, and is in +file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request +processor searches the filesystem for a virtual url handler +(.vuh) file. This file contains normal tcl code, and is in fact handled by the same extension handling procedure that handles .tcl files. The only way this file is treated differently is in how the request processor searches for it. When a lookup fails, the request processor generates each valid prefix of all the abstract paths considered in the concrete file search, and searches these prefixes in order from most specific to least specific for a matching .vuh file. If a file is found then the -ad_conn variable path_info is set to the portion of the url +ad_conn variable path_info is set to the portion of the url not matched by the .vuh script, and the script is sourced. This facility is intended to replace the concept of registered procs, since no special distinction is required between sitewide procs and package specific @@ -89,16 +89,14 @@ off the rightmost path components until a match is reached. This way the time required to lookup a URL is proportional to the length of the URL, not to the number of entries in the mapping.
The request environment is managed by the procedure -ad_conn. Variables can be set and retrieved through use of +ad_conn. Variables can be set and retrieved through use of the ad_conn procedure. The following variables are available for public use. If the ad_conn procedure doesn't recognize a variable being passed to it for a lookup, it tries to get a value using ns_conn. This guarantees that -ad_conn subsumes the functionality of ns_conn.
Request processor [ad_conn urlv] A list containing each element of the URL [ad_conn url] The URL associated with the request. [ad_conn file] The filepath including filename of the file being served [ad_conn request] The number of requests since the server was last started [ad_conn start_clicks] The system time when the RP starts handling the request � Session System Variables: set in +ad_conn subsumes the functionality of ns_conn. +authorization has been performed.Request processor [ad_conn urlv] A list containing each element of the URL [ad_conn url] The URL associated with the request. [ad_conn file] The filepath including filename of the file being served [ad_conn request] The number of requests since the server was last started [ad_conn start_clicks] The system time when the RP starts handling the request � Session System Variables: set in sec_handler, check security with ad_validate_security_info [ad_conn session_id] The unique session_id coming from the sequence sec_id_seq [ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is -blank [ad_conn sec_validated] This becomes "secure" when the connection uses SSL � Database API [ad_conn db,handles] What are the list of handles available to AOL? [ad_conn db,n_handles_used] How many database handles are currently used? [ad_conn db,last_used] Which database handle did we use last? [ad_conn db,transaction_level,$db] Specifies what transaction level we are in [ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted � APM [ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once. -Set in apm_load_xml_packages � Packages [ad_conn package_id] The package_id of the package associated with the URL. [ad_conn package_url] The URL on which the package is mounted. � Miscellaneous [ad_conn system_p] If true then the request has been made to one of the special directories +blank [ad_conn sec_validated] This becomes "secure" when the connection uses SSL � Database API [ad_conn db,handles] What are the list of handles available to AOL? [ad_conn db,n_handles_used] How many database handles are currently used? [ad_conn db,last_used] Which database handle did we use last? [ad_conn db,transaction_level,$db] Specifies what transaction level we are in [ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted � APM [ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once. +Set in apm_load_xml_packages � Packages [ad_conn package_id] The package_id of the package associated with the URL. [ad_conn package_url] The URL on which the package is mounted. � Miscellaneous [ad_conn system_p] If true then the request has been made to one of the special directories specified in the config file (somewhere), and no authentication or -authorization has been performed. � Documentation [ad_conn api_page_documentation_mode_p] � � Documentation [ad_conn api_page_documentation_mode_p] � View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Request Processor Requirements +space.+
OpenACS 4 Request Processor Requirements The following is a requirements document for the OpenACS 4.0 request + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
The following is a requirements document for the OpenACS 4.0 request processor. The major enhancements in the 4.0 version include a more sophisticated directory mapping system that allows package pageroots to be mounted at arbitrary urls, and tighter integration with the database to allow @@ -19,11 +19,9 @@ for the connecting party. Eventually this may also require determining the capabilities of the connecting browser and choosing the most appropriate form for the delivered content.
It is essential that any errors that occur during the above steps be -reported to developers in an easily decipherable manner.
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL -space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context +reported to developers in an easily decipherable manner.
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL +space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context or state associated with a pageroot based on it's location within the URL -space.
30.0 Authentication
30.10 The request processor must be able to verify that the connecting -browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the -connecting browser represents is allowed to make the request.
50.0 Scalability
30.0 Authentication
30.10 The request processor must be able to verify that the connecting +browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the +connecting browser represents is allowed to make the request.
50.0 Scalability
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/security-design.html 10 Aug 2002 20:07:21 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/security-design.html 30 Nov 2002 17:16:24 -0000 1.8 @@ -1,10 +1,10 @@ -OpenACS 4 Security Design +
OpenACS 4 Security Design + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
This document explains security model design for OpenACS 4. The security system with the OpenACS core must authenticate users in both secure and insecure environments. In addition, this subsystem provides sessions on top of the @@ -43,10 +43,10 @@ for a secure authentication token. However, the basic architecture here lays the foundation for a secure system and can be easily adapted to a more secure authentication system by forcing all logins to occur over HTTPS.
The authentication system issues up to four signed cookies (see below), -with each cookie serving a different purpose. These cookies are:
name value max-age secure? ad_session_id session_id,user_id SessionTimeout no ad_user_login user_id Infinity no ad_user_login_secure user_id,random Infinity yes ad_secure_token session_id,user_id,random SessionLifetime yes ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the -previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure +with each cookie serving a different purpose. These cookies are:
name value max-age secure? ad_session_id session_id,user_id SessionTimeout no ad_user_login user_id Infinity no ad_user_login_secure user_id,random Infinity yes ad_secure_token session_id,user_id,random SessionLifetime yes ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the +previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure hash
ad_secure_token -
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure +
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure hash
user_id is extraneous
The Tcl function (sec_handler) is called by the request processor to authenticate the user. It first checks the ad_session_id cookie. If there is no valid session in progress, @@ -86,7 +86,7 @@ immediately
nothing: if the cookie is present, it remains
The current state of the permanent login cookies is not taken into account when determining the appropriate action. -
previous login state permanent login requested secure connection action on insecure action on secure other y y set set same y y set set other y n set delete same y n set nothing same n y nothing delete other n y delete delete other n n delete delete same n n delete delete ad_user_login +
previous login state permanent login requested secure connection action on insecure action on secure other y y set set same y y set set other y n set delete same y n set nothing same n y nothing delete other n y delete delete other n n delete delete same n n delete delete ad_user_login callssec_setup_session which actually calls sec_generate_session_id_cookie to generate the new cookie with refer to the appropriate user_id. If the connection is secure @@ -206,13 +206,13 @@ token_id is returned out of the entire set of cached token_ids. In addition, a thread-persistent cache called tcl_secret_tokens is maintained on a per-thread basis.
Thus, the L2 ns_cache functions as a server-wide LRU cache that has a -minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the +minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the multiple server case, where a user agent may have a signature guaranteed by a -secret token issued by another server in the cluster.
signature cache Since the cache always maintains a +secret token issued by another server in the cluster.
signature cache Since the cache always maintains a minimum of 100 (set by a parameter) tokens populated at startup, it can be used to provide a random token for signature purposes.
The per-thread cache functions as an L1 cache that indiscriminately caches -all secret tokens. Note that this is not an LRU cache +all secret tokens. Note that this is not an LRU cache because there is no cache eviction policy per se -- the cache is cleared when the thread is destroyed by AOLserver.
-ad_user_login user_id Logs the user in as user +ad_user_login user_id Logs the user in as user user_id. Optional forever flag determines whether or not permanent cookies are issued. -
ad_user_logout Logs the user out.
ad_check_password user_id password -returns 0 or 1.
ad_change_password user_id new -password
-ad_sign value Returns the digital signature of this +
ad_user_logout Logs the user out.
ad_check_password user_id password +returns 0 or 1.
ad_change_password user_id new +password
+ad_sign value Returns the digital signature of this value. Optional parameters allow for the specification of the secret used, the token_id used and the max_age for the signature. -ad_verify_signature value signatureReturns +ad_verify_signature value signatureReturns 1 or 0 indicating whether or not the signature matches the value specified. The secret parameter allows for specification of a different secret token to be used.
-ad_set_signed_cookie name data Sets a -signed cookie name with value data.
ad_get_signed_cookie name Gets the signed cookie +ad_set_signed_cookie name data Sets a +signed cookie name with value data.
ad_get_signed_cookie name Gets the signed cookie name. It raises an error if the cookie has been tampered with, or if -its expiration time has passed.
ad_set_client_property module name -data Sets a session property with name to value +its expiration time has passed.
ad_set_client_property module name +data Sets a session property with name to value data for the module module. The optional secure flag specifies the property should only be set if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional -session_id flag to access data from sessions other than the current one.
ad_get_client_property module name -data Gets a session property with name to for the +session_id flag to access data from sessions other than the current one.
ad_get_client_property module name +data Gets a session property with name to for the module module. The optional secure flag specifies the property should only be retrieved if the client is authorized for secure access (ad_secure_conn_p is true). There is also an optional session_id flag to access data from sessions other than the current one.
-SessionTimeout the maximum time in seconds (default 1200) -between requests that are part of the same session
SessionRenew the time in seconds (default 300) between +SessionTimeout the maximum time in seconds (default 1200) +between requests that are part of the same session
SessionRenew the time in seconds (default 300) between reissue of the session cookie. The minimum time that can pass after a session cookie is issued and before it is rejected is (SessionTimeout - SessionRenew). This parameter is used so that only one session_id cookie is set on a single page even if there are multiple images that are being -downloaded.
SessionLifetime the maximum possible lifetime of a -session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to +downloaded.
SessionLifetime the maximum possible lifetime of a +session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to cache. (default 100)
+dependent upon this function.The pseudorandom number generator used in the OpenACS is cryptographically weak, and depends primarily on the randomness of the ns_rand function @@ -339,17 +339,15 @@ points for the system; these vulnerabilities are currently theoretical in nature. The major cryptographic vulnerability of the system stems from the pseudorandom nature of the random number generators used in the system. -
Cryptographically weak PRNG see -above.
Dependence on sample -SQL command The list of random token that are placed in the secret +
Cryptographically weak PRNG see +above.
Dependence on sample +SQL command The list of random token that are placed in the secret tokens cache is randomly chosen by the Oracle sample command. This command may not be entirely random, so predicting the contents of the secret tokens cache may not -be as difficult as someone may anticipate.
Dependence on -ns_rand The actual token that is +be as difficult as someone may anticipate.
Dependence on +ns_rand The actual token that is chosen from the cache to be used is chosen by a call to -ns_rand.
ad_secure_conn_p +ns_rand.
ad_secure_conn_p As discussed above, the security of the secure sessions authentication system is -dependent upon this function.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Security Requirements +
OpenACS 4 Security Requirements + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
Virtually all web sites support personalized content based on user identity. @@ -15,36 +15,34 @@ vendors require that the user identity be securely validated.
+firewall, etc.).The security system consists of a number of subsystems. -
Signed Cookies
+
Signed Cookies
Cookies play a key role in storing user information. However, since they are stored in plaintext on a user's system, the validity of cookies is an important issue in trusting cookie information. Thus, we want to be able to validate a cookie, but we also want to validate the cookie without a database hit. -
10.0 Guaranteed Tamper Detection Any tampering of cookie -data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and +
10.0 Guaranteed Tamper Detection Any tampering of cookie +data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and verification of the cookie should be easily scalable and should not require a -database query on every hit.
Session Properties
+database query on every hit.
Session Properties
Applications should be able to store session-level properties in a database table. -
11.0 Storage API Session-level data should be accessible -via an API.
11.1 Purge Mechanism An efficient pruning mechanism +
11.0 Storage API Session-level data should be accessible +via an API.
11.1 Purge Mechanism An efficient pruning mechanism should be used to prevent old session level properties from filling up the -table.
Login
+table.
Login
The security system should support the concept of persistent user logins. This persistence takes several forms. -
12.0 Permanent Login Users should be able to maintain a -permanent user login so that they never need to type their password.
12.1 Session Login The security system should support +
12.0 Permanent Login Users should be able to maintain a +permanent user login so that they never need to type their password.
12.1 Session Login The security system should support the concept of a session, with authentication tokens that become invalid -after a certain period of time.
12.2 Session Definition A session is a sequence of +after a certain period of time.
12.2 Session Definition A session is a sequence of clicks by one user from one browser in which no two clicks are separated by -more than some constant (the session timeout).
12.3 Stateless The security system should not require +more than some constant (the session timeout).
12.3 Stateless The security system should not require state that is stored in the server. Required state may reside only in the user request (including cookies), and in the database. A single user should be able to log in to the system even if the user is sent to a different -AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store -passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL +AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store +passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL processing occurs outside of the web server (in specialized hardware, in a -firewall, etc.).
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Subsites Design Document +solvable by configuration instead of coding.+
OpenACS 4 Subsites Design Document *Note* This document has not gone through the any of the + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
*Note* This document has not gone through the any of the required QA process yet. It is being tagged as stable due to high demand.
An OpenACS 4 subsite is a managed suite of applications that work together for a particular user community. This definition covers a very broad range of @@ -41,7 +41,7 @@ URLs to operate together. This requirement would cause some packages to have more configuration options than normal since hard-coding the URLs would not be feasible anymore.
This section will cover all the APIs relevant to subsites, and so will -consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The +consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The apm_package.new function can be used to create a package of any type known to the system. The apm_package_types table can be queried for a list of installed packages. (See APM docs for more detail XXX: insert link here)
@@ -101,7 +101,7 @@ show errors -
Site Nodes
This data model keeps track of what packages are being served from what +
Site Nodes
This data model keeps track of what packages are being served from what URLs. You can think of this as a kind of rp_register_directory_map on drugs. This table represents a fully hierarchical site map. The directory_p column indicates whether or not the node is a leaf node. The pattern_p column @@ -182,7 +182,7 @@ show errors -
Request Processor
Once the above APIs are used to create packages and mount them on a +
Request Processor
Once the above APIs are used to create packages and mount them on a specific site node, the following request processor APIs can be used to allow the package to serve content appropriate to the package instance.
@@ -210,6 +210,4 @@ a particular configuration of site nodes/packages. As we build more fundamental applications that can be applied in more general areas, this feature will become more and more in demand since more problems will be -solvable by configuration instead of coding.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,9 +1,9 @@ -OpenACS 4 Subsites Requirements +
OpenACS 4 Subsites Requirements The following is a requirements document for OpenACS 4 Subsites, part of the + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
The following is a requirements document for OpenACS 4 Subsites, part of the OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve multiple user communities, by enabling the suite of available OpenACS applications to be customized for defined user communities.
Many online communities are also collections of discrete subcommunities, @@ -42,19 +42,17 @@ office. At this point, the Boston and Austin office admins can customize the configurations for each of their bboards, or they can just use the defaults.
Test plan (Not available yet)
A subsite API is required for programmers to ensure their packages are -subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be -possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related -objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the -package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the -canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding -to the main subsite's package ID (the degenerate subsite).
The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive +subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be +possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related +objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the +package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the +canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding +to the main subsite's package ID (the degenerate subsite).
+that package.The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive the underlying API for package instance management (i.e. adding, removing, or altering packages). It is restricted to administrators of the current subsite such that administrators can only manage their own subsites. Of course, -Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a -package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate -any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no +Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a +package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate +any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no longer accessible, but it does not remove data created within the context of -that package.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/unix-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/unix-install.html,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/unix-install.html 10 Aug 2002 20:07:21 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/unix-install.html 30 Nov 2002 17:16:24 -0000 1.7 @@ -1,4 +1,2 @@ -Chapter 2. Installing on Unix/Linux +Chapter�2.�Installing on Unix/Linux View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/win-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-install.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/win-install.html 10 Aug 2002 20:07:21 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/win-install.html 30 Nov 2002 17:16:24 -0000 1.9 @@ -1,4 +1,2 @@ -Chapter 3. Installing on Windows +Table of Contents
Chapter�3.�Installing on Windows Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/win-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/win-overview.html,v diff -u -N -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/win-overview.html 10 Aug 2002 20:07:21 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/win-overview.html 30 Nov 2002 17:16:24 -0000 1.5 @@ -1,4 +1,2 @@ -Overview +Overview View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/files/acs-pgbackup-init.txt =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/files/acs-pgbackup-init.txt,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/files/acs-pgbackup-init.txt 1 Feb 2002 17:12:18 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/files/acs-pgbackup-init.txt 30 Nov 2002 17:16:33 -0000 1.2 @@ -4,25 +4,28 @@ # created. # Original version by Don Baccus (dhogaza@pacifier.com> # Modified for openacs4 by Vinod Kurup+ + +-+-
-
-++
+
+-++[ad_conn path_info] + ++In a .vuh file, path_info is the trailing part of the URL not matched +by the .vuh file. + ($Id$) .tcl file and the other is a special.adp file. The.tcl file runs a script that sets up a set of name/value bindings that we calldata -sources . Thesedata sources are generally the results of Tcl and/or database queries +sources. Thesedata sources are generally the results of Tcl and/or database queries or some combination thereof. The template system automatically makes them available to the.adp file, or the display part of the template, which is written in a combination of HTML, special Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 1 Oct 2002 15:26:12 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 30 Nov 2002 17:17:01 -0000 1.7 @@ -61,20 +61,20 @@Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around - for a while (since early 90's ), + for a while (sinceearly 90's ), it's well-tested, it's complete, it's extremely well-suited for technical documents and best of all, it's open-source. A growing community surrounds DocBook (has -mailing lists ) +mailing lists ) and a number of free and commercial -tools are available +tools are available for editing and publishing DocBook documents.This primer walks you through the basics, and should cover the needs for 95 percent of the documentation we produce. However, you're always welcome to check out DocBook's - + list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTDIn the process of transforming your HTML into XML, - HTML tidy +HTML tidy can be a a handy tool to make your HTML "regexp'able".Brandoch Calef has made aPerl script Index: openacs-4/packages/acs-core-docs/www/xml/files/acs-pgbackup-init.txt =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/files/Attic/acs-pgbackup-init.txt,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/files/acs-pgbackup-init.txt 10 Aug 2002 21:38:38 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/files/acs-pgbackup-init.txt 30 Nov 2002 17:17:14 -0000 1.2 @@ -4,25 +4,28 @@ # created. # Original version by Don Baccus (dhogaza@pacifier.com> # Modified for openacs4 by Vinod Kuruphttp://openacs.org/community/ +See also: Teaching @@ -152,22 +153,22 @@ NOTE: This material was provided by ArsDigita Corporation. As ArsDigita has ceased their operations, we don't know for how long the following URLs will be operational, and we - could not simply mirror them before asking permission from th + could not simply mirror them before asking permission from the authors. If arsdigita.com goes dead, you can find these documents under http://web.archive.org/web/*/http://arsdigita.com .- - + -Philip and Alex's Guide to + Philip and Alex's Guide to Web Publishing SQL for Web Nerds +SQL for Web Nerds (tutorial for the SQL language; links into online Oracle docs for completeness)Tcl + Tcl for Web Nerds (tutorial for the Tcl language; in rough shape right now and you might consider using the Welch book (below))Install AOLserver 3.3+ad13 - by Vinod Kurup + byVinod Kurup - Download the Distribution +Download the Distribution -- Mat Kovach is graciously maintaining an AOLServer distribution that - includes all the patches and modules needed to run OpenACS &version;. These - instructions will describe how to install using his source - distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and - perhaps more to come), currently located at +uptime.openacs.org . -+ Mat Kovach is graciously maintaining an AOLServer distribution that + includes all the patches and modules needed to run OpenACS &version;. These + instructions will describe how to install using his source + distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and + perhaps more to come), currently located at -uptime.openacs.org . +- It's also possible to download all the pieces and patches yourself: - ++ It's also possible to download all the pieces and patches yourself: + -- -- AOLServer is available at aolserver.com -+ ++ AOLServer is available at aolserver.com +- ArsDigita's AOLServer distribution (including - internationalization patches, nscache, nsrewrite, nssha1 and the - oracle driver) is available at arsdigita.com -+ ArsDigita's AOLServer distribution (including + internationalization patches, nscache, nsrewrite, nssha1 and the + oracle driver) is available at arsdigita.com +- The OpenACS PostgreSQL driver is available from OpenACS -+ The OpenACS PostgreSQL driver is available from OpenACS +- nsxml is available at http://acs-misc.sourceforge.net . -+ nsxml is available at http://acs-misc.sourceforge.net . +- The patch that makes exec work - on BSD is available atsourceforge.net -+ The patch that makes exec work + on BSD is available atsourceforge.net +- The patch that makes ns_uuencode - work for binary files is available atsourceforge.net -+ The patch that makes ns_uuencode + work for binary files is available atsourceforge.net +- The patch that makes AOLServer respect the - -g flag is available atsourceforge.net -+ The patch that makes AOLServer respect the + -g flag is available atsourceforge.net ++ -- .... or just Download +Mat's - AOLServer distribution to -/tmp + .... or just DownloadMat's + AOLServer distribution to +/tmp -+ joeuser:~$ cd /tmp joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz joeuser:/tmp$ cd -+ + +- As - -root , untar -aolserver3.3ad13-oacs1-beta-src.tar.gz - into/usr/local/src + Asroot , untar +aolserver3.3ad13-oacs1-beta-src.tar.gz + into/usr/local/src -+ joeuser:~$ su - Password: ********** -root:~$ cd /usr/local/src -root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz +root:~# cd /usr/local/src +root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz +root:/usr/local/src# chown -R root.root aolserver- Create the nsadmin user +Set up your user account - You will need a special user account for running AOLServer. This user - will be called + AOLserver needs to be started as the root user if you want to use + port 80. Once it starts, though, it will drop the root privileges and + run as another user, which you must specify on the command line. It's + important that this user has as few privileges as possible. Why? + Because if an intruder somehow breaks in through AOLserver, you don't + want him to have any ability to do damage to the rest of your + server. At the same time, AOLserver needs to have write access to + some files on your system in order for OpenACS to function + properly. So, we'll run AOLserver as the +nsadmin and belong - to the special groupweb . -nsadmin 's home directory will - be/usr/local/aolserver .You must - execute these steps asroot . -nobody user and the +web group. We'll add your regular + user account to theweb group and + make sure that OpenACS files are group readable and writable. + +- Run these commands: - + Run these commands: ++ root:/usr/local/src# cd -root:~# groupadd nsadmin root:~# groupadd web -root:~# useradd -g nsadmin -G web -d /usr/local/aolserver nsadmin -root:~# passwd nsadmin -; Set password for nsadmin - -root:~# mkdir -p /web /usr/local/aolserver -root:~# chown -R nsadmin.web /usr/local/aolserver /web /usr/local/src/aolserver -root:~# chmod 775 /usr/local/aolserver /web +root:~# adduser joeuser web root:~# exit- Set up nsadmin's environment variables +- -- At this point, you should customize the - + Next, we'll set up our environment variables. Add the following lines + to yournsadmin login scripts. Login as -nsadmin and add the following - lines to your -/usr/local/aolserver/.bash_profile : -/home/joeuser/.bash_profile : --joeuser:~$ su - nsadmin -Password: *********** -nsadmin:~$ emacs .bash_profile +- Add the first set of lines, if you're using Oracle. The 2nd set - of lines, if you're using PostgreSQL. - -Oracle - Note: These environment variables are specific for a - local Oracle installation communicating via IPC. If you are - connecting to a remote Oracle installation, you'll need to adjust - these appropriately. Also, make sure that the '8.1.7' matches - your Oracle version. -+ +joeuser:~$ emacs .bash_profile + ++ + Add the first set of lines, if you're using Oracle. The 2nd set of + lines, if you're using PostgreSQL. + +Oracle Note: + These environment variables are specific for a local Oracle + installation communicating via IPC. If you are connecting to a remote + Oracle installation, you'll need to adjust these appropriately. Also, + make sure that the '8.1.7' matches your Oracle version. + +# For Oracle export ORACLE_BASE=/ora8/m01/app/oracle export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 @@ -167,246 +164,307 @@ export PATH=$PATH:/usr/local/pgsql/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib -- Be absolutely certain that you have entered these lines correctly - and that you have saved the file - a slight error in these lines - can lead to many inscrutable error messages. Logout and log back - in so these settings will take effect. Use the - +echo command to be sure that the - environment variables have been properly assigned. -- + +-nsadmin:~$ exit -joeuser:~$ su - nsadmin + Be absolutely certain that you have entered these lines correctly and + that you have saved the file - a slight error in these lines can lead + to many inscrutable error messages. Logout and log back in so these + settings will take effect. Use the + echo command to be sure that the + environment variables have been properly assigned. + ++joeuser:~$ exit +LOGIN: joeuser Password: ********* -nsadmin:~$ echo $PATH +joeuser:~$ echo $PATH ...some other directory paths...:/usr/local/pgsql/bin -nsadmin:~$ echo $LD_LIBRARY_PATH +joeuser:~$ echo $LD_LIBRARY_PATH :/usr/local/pgsql/lib -- Note: The result should be different if you're using Oracle. - - - +/ora8/m01/app/oracle/product/8.1.7 - should have been in$PATH . -+ + Note: The result should be different if you're using Oracle. + /ora8/m01/app/oracle/product/8.1.7 + should have been in$PATH . + +- Install libxml2 & headers +Install libxml2 & headers -+ - In order for nsxml to compile, you need libxml2 - (available from + In order for nsxml to compile, you need libxml2 + (available fromhttp://xmlsoft.org ). On Debian, - this can be installed by doingapt-get install - libxml2-dev . Users of other distributions can - download rpms fromftp.gnome.org . You'll - need thelibxml2 and -libxml2-devel packages. -http://xmlsoft.org ). On Debian, + this can be installed by doingapt-get install + libxml2-dev . Users of other distributions can + download rpms fromrpmfind.net . You'll + need thelibxml2 and +libxml2-devel packages. +- +Compile and install AOLserver +Compile and install AOLserver - +Prepare the distribution +Prepare the distribution. You need to be root. --nsadmin:~$ cd /usr/local/src/aolserver -nsadmin:/usr/local/src/aolserver$ ./conf-clean + +joeuser:~$ su -p +Password: ******** +root:~# mkdir -p /usr/local/aolserver +root:~# cd /usr/local/src/aolserver +root:/usr/local/src/aolserver# ./conf-clean cat: BUILD-MODULES: No such file or directory Done. -+ -- Put the name of the driver(s) that you want into - + Put the name of the driver(s) that you want into +conf-db . This can be -"postgresql" , -"oracle" , or the word -"both" if you want both drivers - installed. -conf-db . This can be +"postgresql" , +"oracle" , or the word +"both" if you want both drivers + installed. --nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db -+ +root:/usr/local/src/aolserver# echo "postgresql" > conf-db +conf-inst should contain the - location where AOLserver is to be installed. This defaults to -/usr/local/aolserver , so we - don't need to change it. +- conf-inst should contain the + location where AOLserver is to be installed. This defaults to +/usr/local/aolserver , so we + don't need to change it. -+ conf-make should contain the - name of the GNU Make command on your system. It defaults to -gmake . You may need to change - this tomake . - +- -nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make -conf-make should contain the + name of the GNU Make command on your system. It defaults to +gmake . You may need to change + this tomake . + -- If you're going to be installing the Postgresql driver, you'll - have to adjust the makefile first. This will hopefully be cleaned - up in future versions of this distribution. - ++root:/usr/local/src/aolserver# echo "make" > conf-make +-nsadmin:/usr/local/src/aolserver$ emacs pgdriver/makefile ++ If you're going to be installing the Postgresql driver, you'll + have to adjust the makefile first. This will hopefully be cleaned + up in future versions of this distribution. + -- Edit the lines containing PGLIB and PGINC so they look like this: - - -+ +root:/usr/local/src/aolserver# emacs pgdriver/makefile + ++ Edit the lines containing PGLIB and PGINC so they look like this: + + +PGINC=/usr/local/pgsql/include PGLIB=/usr/local/pgsql/lib -Compile and install AOLserver and modules --nsadmin:/usr/local/src/aolserver$ ./conf ++root:/usr/local/src/aolserver# ./conf -- This takes about 5 minutes. All of the results are logged to - files in - -/usr/local/src/aolserver/log . Make - sure to check these files to see if any errors occurred. -+ This takes about 5 minutes. All of the results are logged to + files in + + + +/usr/local/src/aolserver/log . Make + sure to check these files to see if any errors occurred. + ++ +Set File Permissions + ++ + In order to test AOLserver, we'll run it using the sample-config.tcl + file provided in the AOLserver distribution. We need to adjust + permissions a little since AOLserver needs to be able to write its + logs properly. + + ++root:/usr/local/src/aolserver# cd /usr/local/aolserver +root:/usr/local/aolserver# chown -R root.web log servers +root:/usr/local/aolserver# chmod -R g+w log servers +root:/usr/local/aolserver# ls -l + drwxr-sr-x 8 root staff 1024 Nov 12 01:35 . + drwxrwsr-x 12 root staff 1024 Nov 12 01:25 .. + drwxr-xr-x 2 root staff 1024 Nov 12 01:36 bin + drwxr-xr-x 2 root staff 1024 Jun 11 2001 include + drwxr-xr-x 3 root staff 1024 Nov 12 01:36 lib + drwxrwxr-x 2 root web 1024 Nov 12 01:45 log + drwxr-xr-x 3 root staff 1024 Nov 12 01:35 modules + -rw-r--r-- 1 root staff 7320 Mar 31 2001 sample-config.tcl + drwxrwxr-x 3 root web 1024 Nov 12 01:35 servers +- Test AOLserver +Test AOLserver -+ - You will now test to ensure AOLserver is running correctly. We'll - use the sample config file provided with AOLserver. This file - will attempt to guess your IP address and hostname. It will then - set up the server at port 8000 of that IP address. - --nsadmin:/usr/local/src/aolserver$ cd -nsadmin:~$ ./bin/nsd -t sample-config.tcl + Now, we'll run a quick test to ensure AOLserver is running + correctly. We'll use the sample config file provided with + AOLserver. This file will attempt to guess your IP address and + hostname. It will then start up the server at port 8000 of that + IP address. + + ++root:/usr/local/aolserver# ./bin/nsd -t sample-config.tcl -u nobody -g web +- As the AOLserver daemon starts up, you should see a few normal - warnings (listed below), which are safe to ignore. - -+ As the AOLserver daemon starts up, you should see a few normal + warnings (listed below), which are safe to ignore. + + + + Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. Warning: nsd.tcl: nscp not loaded -- user/password is not set. -- The first warning means that the server is missing files for - running +ssl , a necessary module - for encrypted HTTPS. See Scott Goodwin'sexcellent - documentation if you want to set up SSL. The second - warning means that the AOLserver control panel, a special module - for administering AOLserver, could not be loaded. If you're - interested in configuring nscp, please see theAOLserver - documentation . -+ The first warning means that the server is missing files for + running +ssl , a necessary module + for encrypted HTTPS. See Scott Goodwin'sexcellent + documentation if you want to set up SSL. The second + warning means that the AOLserver control panel, a special module + for administering AOLserver, could not be loaded. If you're + interested in configuring nscp, please see theAOLserver + documentation . + +- Test to see if AOLserver is working by starting - -Mozilla or -Lynx , and surfing over to your - web page: --nsadmin:~$ lynx localhost:8000 + Test to see if AOLserver is working by starting +Mozilla or +Lynx , and surfing over to your + web page: + + ++root:~# lynx localhost:8000 +- You should see a "Welcome to AOLserver" page. If this - doesn't work, try going to - http://127.0.0.1:8000/ . If this - still doesn't work, check out thesection below. - http://127.0.0.1:8000/ . If this + still doesn't work, check out thesection below. + + + - Shutdown the test server: --nsadmin:~$ killall nsd + Shutdown the test server: + + ++root:~# killall nsd +- The -killall command will kill - all processes with the namensd , - but clearly this is not a good tool to use for managing your - services in general. We cover this topic in thesection. - killall command will kill + all processes with the namensd , + but clearly this is not a good tool to use for managing your + services in general. We cover this topic in thesection. + + + - Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml,v diff -u -N -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 10 Aug 2002 19:53:50 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/credits.xml 30 Nov 2002 17:17:46 -0000 1.7 @@ -47,14 +47,14 @@ Several people have helped with this document, including Torben Brosten, Don Baccus, Roberto Mello, Talli Somekh, Dave Bauer, Jim Lynch, Jon Griffin, Daryl Biberdorf, Bjorn Thor Jonsson, Jade Rubick, - Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner and Malte - Sussdorff. + Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner, Malte + Sussdorff, Stan Kaufman and Pascal Scheffers.Troubleshooting the AOLserver Install +Troubleshooting the AOLserver Install -If you can't view the welcome page, it's likely - there's a problem with your server configuration. Start by - viewing your AOLserver log, which is in - -/usr/local/aolserver/log/server.log . - You should also try to find lines of the form:+ -+ + If you can't view the welcome page, it's likely there's a + problem with your server configuration. Start by viewing your + AOLserver log, which is in + +/usr/local/aolserver/log/server.log . + You should also try to find lines of the form: + +[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) [01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections -If you can find these lines, try entering the URL the server is - listening on. If you cannot find these lines, there must be an error - somewhere in the file. Search for lines beginning with the word - +Error instead of -Notice .- + +The + If you can find these lines, try entering the URL the server is + listening on. If you cannot find these lines, there must be an error + somewhere in the file. Search for lines beginning with the word +sample-config.tcl file grabs - your address and hostname from your OS settings.Error instead of +Notice . -+ + + The + +sample-config.tcl file grabs + your address and hostname from your OS settings. + +set hostname [ns_info hostname] set address [ns_info address] -If you get an error that nssock can't get the requested address, - you can set these manually: +- + +-#set hostname [ns_info hostname] -set hostname 127.0.0.1 + If you get an error that nssock can't get the requested address, you + can set these manually. If you type 0.0.0.0, AOLserver will try to + listen on all available addresses. + + +set hostname [ns_info hostname] #set address [ns_info address] -set address 127.0.0.1 +set address 0.0.0.0- If you get an error that nssock can't assign the requested port, - then that port may already be taken by another service. Try specifying - a different port in the config file. - - All questions and comments regarding - this guide should be posted on theOpenACS bboards . +All questions and comments regarding + this guide should be posted on theOpenACS bboards .($Id$) Next Steps - by Vinod Kurup + byVinod Kurup - Backup Strategy +Backup Strategy -Here are some tips from Don Baccus regarding backup strategy: +- -- The need for making backups should be self-explanatory. There are - several strategies you can use. My own strategy for minimizing the - odds that I'll lose all my data is quite simple: - + Here are some tips from Don Baccus regarding backup strategy: -- - The database is stored on a mirrored (RAID 1) disk. - - The machine has battery backup. - - -- Backups are made nightly onto a third disk on another controller - - FTP is used to copy the resulting backup to two separate remote - servers in two locations - - Rather than making remote copies, you might choose to dump to tape or - writeable CD media. Whatever strategy you use, it is important to - routinely check dumps to make sure they can be reloaded. The strategy - outlined above means that in the case of catastrophic failure, I'll - lose at most one day's data. + ++ + The database is stored on a mirrored (RAID 1) disk. + + The machine has battery backup. + + Backups are made nightly onto a third disk on another controller + + FTP is used to copy the resulting backup to two separate remote + servers in two locations + + + Rather than making remote copies, you might choose to dump to tape or + writeable CD media. Whatever strategy you use, it is important to + routinely check dumps to make sure they can be reloaded. The strategy + outlined above means that in the case of catastrophic failure, I'll + lose at most one day's data. + + + ++ + By mirroring disks and using a battery backup, preferably one that + can trigger an automatic and controlled shutdown of the system when + the battery runs low, you greatly lower the odds of ever having to + use your nightly backup. Despite this, it is important to take + backups seriously if the data stored at your site is valuable to you + or your users. + + - Set Up Nightly Oracle Exports +Set Up Nightly Oracle Exports - While you're working with Oracle, you should configure it to do - automatic exports. An export is a separate backup copy of the - database. This copy includes all of the database's state at the - time that the export was initiated. If your database is corrupted, - you can restore from one of these backups. You should do this step as - + While you're working with Oracle, you should configure it to do + automatic exports. An export is a separate backup copy of the + database. This copy includes all of the database's state at the + time that the export was initiated. If your database is corrupted, + you can restore from one of these backups. You should do this step as +root . -root . +- Download the backup script. Save the file export-oracle.txt as -/tmp/export-oracle.txt -export-oracle.txt as +/tmp/export-oracle.txt +- Login as root. The following commands will install the export script: - --nsadmin:~$ su - + Login as root. The following commands will install the export script: + + +joeuser:~$ su - Password: *********** root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle root:~# chmod 700 /usr/sbin/export-oracle @@ -85,27 +97,27 @@ be stored. We recommend the directory/ora8/m02/oracle-exports . -+ root:~# mkdir /ora8/m02/oracle-exports root:~# chown oracle.dba /ora8/m02/oracle-exports root:~# chmod 770 /ora8/m02/oracle-exports - Now edit - + Now edit +/usr/sbin/export-oracle and - change theSERVICE_NAME and -DATABASE_PASSWORD fields to - their correct values. If you want to use a directory other than -/ora8/m02/oracle-exports , you - also need to change the -exportdir setting. -/usr/sbin/export-oracle and + change theSERVICE_NAME and +DATABASE_PASSWORD fields to + their correct values. If you want to use a directory other than +/ora8/m02/oracle-exports , you + also need to change the +exportdir setting. +- Test the export procedure by running the command: - + Test the export procedure by running the command: + -+ root:~# /usr/sbin/export-oracle mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory @@ -145,379 +157,385 @@ Export terminated successfully without warnings. If you don't have any warnings, proceed to automate the - backups. + backups.- Automating backups is accomplished using the UNIX - + Automating backups is accomplished using the UNIX +crontab facility.crontab facility.- While still -root , run the - following command. You can replace the -EDITOR="emacs -nw" - portion with whatever editor your prefer, such as -EDITOR=vi . -+ While still root , run the + following command. You can replace the +EDITOR="emacs -nw" + portion with whatever editor your prefer, such as +EDITOR=vi . + +root:~# export EDITOR="emacs -nw" root:~# crontab -e -Now add the following line on a line by itself +Now add the following line on a line by itself -+ 0 23 * * * /usr/sbin/export-oracle - Save the file, exit the editor. Verify that the addition - succeeded by checking the output of the following command. + Save the file, exit the editor. Verify that the addition + succeeded by checking the output of the following command. -+ root:~# crontab -l | grep export-oracle 0 23 * * * /usr/sbin/export-oracle root:~# exit ; Logout -If you see the line, go ahead and log out. -If you see the line, go ahead and log out. +- Set up nightly Postgres exports +Set up nightly Postgres exports -- Dowload +this script - to/tmp . At the top of the script - are several variables that you'll need to customize: -+ Dowload -this script + to/tmp . At the top of the script + are several variables that you'll need to customize: +- -- bak - location where you want - local backups to be saved -+ ++ bak - location where you want + local backups to be saved +- servername - name of your server - (and database instance) -+ servername - name of your server + (and database instance) +- ftp_user - username on your ftp - account -+ ftp_user - username on your ftp + account +- ftp_password - password on your - ftp account -+ ftp_password - password on your + ftp account +- ftp_dir - path on the remote - server where your backups will be uploaded -+ ftp_dir - path on the remote + server where your backups will be uploaded +- ftp_server - your ftp server -+ ftp_server - your ftp server ++ -- Next, we'll save this file to our server's - + Next, we'll save this file to our server's +tcl directory so that it will be - loaded on startup. It will automatically be run every night at - midnight. Note that this script only backs up the database - not the - OpenACS scripts and file content. -tcl directory so that it will be + loaded on startup. It will automatically be run every night at + midnight. Note that this script only backs up the database - not the + OpenACS scripts and file content. +-nsadmin:~$ cp /tmp/acs-pgbackup-init.txt /web/birdnotes/tcl/acs-pgbackup-init.tcl -nsadmin:~$ restart-aolserver birdnotes ++joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/web/birdnotes/tcl/acs-pgbackup-init.tcl +joeuser:~$ restart-aolserver birdnotes -- That's it! The script will email you with each successful backup (or - if it fails, it will send you an email with the reason) - ++ That's it! The script will email you with each successful backup (or + if it fails, it will send you an email with the reason) + - Vacuum Postgres nightly -- The "vacuum" command must be run periodically to reclaim space. The - "vacuum analyze" form additionally collects statistics on the - disbursion of columns in the database, which the optimizer uses when - it calculates just how to execute queries. The availability of this - data can make a tremendous difference in the execution speed of - queries. This command can also be run from cron, but it probably makes - more sense to run this command as part of your nightly backup - procedure - if "vacuum" is going to screw up the database, you'd - prefer it to happen immediately after (not before!) you've made a - backup! The "vacuum" command is very reliable, but conservatism is - the key to good system management. So, if you're using the export - procedure described above, you don't need to do this extra step. - +Vacuum Postgres nightly ++ The "vacuum" command must be run periodically to reclaim space. The + "vacuum analyze" form additionally collects statistics on the + disbursion of columns in the database, which the optimizer uses when + it calculates just how to execute queries. The availability of this + data can make a tremendous difference in the execution speed of + queries. This command can also be run from cron, but it probably makes + more sense to run this command as part of your nightly backup + procedure - if "vacuum" is going to screw up the database, you'd + prefer it to happen immediately after (not before!) you've made a + backup! The "vacuum" command is very reliable, but conservatism is + the key to good system management. So, if you're using the export + procedure described above, you don't need to do this extra step. + -Edit your crontab: --nsadmin:~$ crontab -e +Edit your crontab: ++joeuser:~$ crontab -e -We'll set vacuum up to run nightly at 1 AM. Add the following - line: -+ We'll set vacuum up to run nightly at 1 AM. Add the following + line: +0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes - How to add a second server on a different port +How to add a second server on a different port -Starting another server is simply a matter of configuring another - aolserver instance, creating another database and pointing this - aolserver instance at a fresh copy of the OpenACS-4 code. We'll call - our new server +birdnotes-dev Starting another server is simply a matter of configuring another + aolserver instance, creating another database and pointing this + aolserver instance at a fresh copy of the OpenACS-4 code. We'll call + our new server -birdnotes-dev - +- Download another copy of +openacs4.tcl.txt /tmp .+ + You can either copy your current OpenACS installation: + --nsadmin:~$ cp /tmp/openacs4.tcl.txt ./ +birdnotes-dev .tcl -nsadmin:~$ chmod 660birdnotes-dev .tcl -nsadmin:~$ emacsbirdnotes-dev .tcl+joeuser:~$ cp -r web/birdnotes web/birdnotes-dev -Just like in -, - you'll need to set the server parameters appropriately. Be sure to - choose a different port than your original server and to set - server to -birdnotes-dev .+ Or Download the -OpenACS + 4 software into/tmp again. ++ +joeuser:~$ cd web +joeuser:~/web$ tar xzvf /tmp/openacs-4-5-release.tgz +joeuser:~/web$ mv openacs-4 birdnotes-dev +birdnotes-dev . Follow the instructions in -or . + + Download another copy of -openacs4.tcl.txt /tmp .+joeuser:~/web$ cp /tmp/openacs4.tcl.txt ./ -birdnotes-dev /nsd.tcl +joeuser:~/web$ chmod 600birdnotes-dev /nsd.tcl +joeuser:~/web$ emacsbirdnotes-dev /nsd.tcl+ Just like in +, + you'll need to set the server parameters appropriately. Be sure to + choose a different port than your original server and to set + server to +birdnotes-dev .- -nsadmin:~$ cd /web -nsadmin:~$ cp -r birdnotes birdnotes-dev + Create a new database instance called +birdnotes-dev . Follow the instructions in +or . - - Or Download the +OpenACS - 4 software into/tmp again. --nsadmin:~$ cd /web -nsadmin:/web$ tar xzvf /tmp/alpha2.tgz -nsadmin:/web$ mv openacs-4 birdnotes-dev -+ + Start your new server! + ++joeuser:~/web$ cd +joeuser:~/web$ /usr/local/aolserver/bin/nsd-postgres -t /home/joeuser/web/ -birdnotes-dev /nsd.tcl- -- Start your new server! - --nsadmin:/web$ cd -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ - -birdnotes-dev .tcl- Visit the site with a web browser (using the port that you set - above). You should see the OpenACS installer. Once you install - the OpenACS datamodel, you'll also need to add your new aolserver - instance to -/etc/inittab (or - daemontools) so it restarts automatically.+ Visit the site with a web browser (using the port that you set + above). You should see the OpenACS installer. Once you install + the OpenACS datamodel, you'll also need to add your new aolserver + instance to + +/etc/inittab (or + daemontools) so it restarts automatically.- Set up site-wide search -- OpenACS uses the +OpenFTS package to - implement site-wide-search. You'll need to have the Tcl development - libraries and headers installed. (Debian users: -apt-get install tcl8.3-dev ) -Set up site-wide search +- + +- - As + OpenACS uses theroot , download the - Search-OpenFTS driver. -OpenFTS package to + implement site-wide-search. As of this writing, the current version + is 0.3.2. There are good instructions included in the OpenFTS + instructions which I will repeat here. Be sure to look at those + instructions if you're installing a version later than 0.3.2; the + instructions may have changed. You'll need to have the Tcl + development libraries and headers installed. (Debian users: +apt-get install tcl8.3-dev ) --nsadmin:~$ su - + + ++ + As + +root , download the latest TCL + version of the Search-OpenFTS driver fromSourceForge + into/tmp . Extract the source + into/usr/local/src + ++joeuser:~$ su - Password: ********** -root:~# cd /tmp -root:/tmp# wget http://prdownloads.sourceforge.net/openfts/Search-OpenFTS-tcl-0.2.tar.gz root:~# cd /usr/local/src -root:/usr/local/src# tar xzf /tmp/Search-OpenFTS-tcl-0.2.tar.gz -root:/usr/local/src# chown -R nsadmin.web Search-OpenFTS-tcl-0.2 -root:/usr/local/src# exit -- Configure it. Note that you may need to set - +--with-tcl= (your Tcl library - location). For Debian, add this to the end of the -./configure command: ---with-tcl=/usr/lib/tcl8.3 -- -nsadmin:~$ cd /usr/local/src/Search-OpenFTS-tcl-0.2 -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver ---with-tcl= (your Tcl library + location). For Debian, add this to the end of the +./configure command: +--with-tcl=/usr/lib/tcl8.3 -- In order to compile on Debian, I had to edit my - + -Makefile.global . Add --I/usr/include/tcl8.3 to the - line where INC is defined, so it looks like this: --INC = ../include -I/usr/include/tcl8.3 ++root:/usr/local/src/Search-OpenFTS-tcl-0.3.2# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver +Then compile it: +- -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ make -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ cd aolserver -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ make -bin directory, and copy the TCL + files to your AOLservertcl + directory: -- Install it. You need to do this step as root since some of the - libraries will be installed alongside your TCL libraries and some - alongside your PostgreSQL libraries. - + --nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ su - -Password: *********** -root:~# cd /usr/local/src/Search-OpenFTS-tcl-0.2 -root:/usr/local/src/Search-OpenFTS-tcl-0.2# make install -root:/usr/local/src/Search-OpenFTS-tcl-0.2# exit -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cp nsfts.so /usr/local/aolserver/bin/ -+root:/usr/local/src/Search-OpenFTS-tcl-0.3.2# cd aolserver +root:/usr/local/src/Search-OpenFTS-tcl-0.3.2/aolserver# make +root:/usr/local/src/Search-OpenFTS-tcl-0.3.2/aolserver# cp nsfts.so /usr/local/aolserver/bin +root:/usr/local/src/Search-OpenFTS-tcl-0.3.2/aolserver# cd .. +- -- Add the following line to your aolserver config file (in our - example: - +/usr/local/aolserver/birdnotes.tcl ) - in the "ns_section ns/server/${server}/modules" section: -- + ++ Load the tsearch module SQL into your database and then compile + the openfts module in the Postgresql contrib directory. + + +root:/usr/local/src/Search-OpenFTS-tcl-0.3.2# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib +root:/usr/local/src/Search-OpenFTS-tcl-0.3.2# cd /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts +root:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts# make +root:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts# su postgres +postgres:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts$ make install +postgres:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts$ /usr/local/pgsql/bin/psql birdnotes -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql +postgres:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts$ /usr/local/pgsql/bin/psql birdnotes -f openfts.sql +postgres:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts$ exit +root:/usr/local/postgresql-7.2.3/contrib/pgsql_contrib_openfts# exit ++ ++ + Uncomment the following line in your aolserver config file (in our + example: + + +~/web/birdnotes/nsd.tcl ) + in the "ns_section ns/server/${server}/modules" section: + +ns_param nsfts ${bindir}/nsfts.so -- Load the openFTS code into your database: - ++ Open a browser and go to your server + (http://yourserver:port). Click on the "Package Manager" link in + the "Quick Links" section on the right side of the page. + -nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cd -nsadmin:~$ psql -f /web/ -birdnotes /packages/openfts-driver/sql/postgresql/load.sqlbirdnotes -nsadmin:~$ restart-aolserverbirdnotes + Click on the "Install packages" link and follow the instructions + to install the Note package and the OpenFTS Driver 4.2 package. + - Open a browser and go to your server - (http://yourserver:port). Click on the "Package Manager" link in - the "Quick Links" section on the right side of the page. - + Restart your server. - - Click on the "Install packages" link and follow the instructions - to install the Note package and the OpenFTS Driver 4.2 package. - +joeuser:~$ svc -t /service/ +birdnotes - Restart your server. + + Give the server a few minutes to restart and then go back to your + server's front page and click on "Site Map" from the "Quick + Links" + -nsadmin:~$ restart-aolserver -birdnotes + Create a "new sub folder" under "Main Site". Call the url + "openfts". + - Give the server a few minutes to restart and then go back to your - server's front page and click on "Site Map" from the "Quick - Links" - Click "mount" to mount the OpenFTS driver at the url + "openfts" (despite what the system says about these packages not + being meant to be mounted) + - Create a "new sub folder" under "Main Site". Call the url - "openfts". - + -- +Click "mount" to mount the OpenFTS driver at the url - "openfts" (despite what the system says about these packages not - being meant to be mounted) - openfts_tcl_src_path to +/usr/local/src/Search-OpenFTS-tcl-0.3.2 -Click on "Set parameters" for the OpenFTS instance - and make sure that openfts_tcl_src_path properly points to your - local copy of the Search package source code. If you've followed - these directions strictly, you shouldn't need to change it. - - Create another folder under "Main Site" at the url - "search". Create a "new application". Call the application - "Search" and choose the "Search" package from the drop-down list. - + Create another folder under "Main Site" at the url + "search". Create a "new application". Call the application + "Search" and choose the "Search" package from the drop-down list. + - Create a third folder under "Main Site" at the url - "notes". Create a "new application". Call the application "Notes" - and choose the "Note" package from the drop-down list. - + Create a third folder under "Main Site" at the url + "notes". Create a "new application". Call the application "Notes" + and choose the "Note" package from the drop-down list. + - Restart the server. - + Restart the server. + - Return to your home page. Near the bottom of the page, Click on - the "OpenFTS Driver" link. Then click on - "Administration". Finally, click on "Initialize OpenFTS - Engine". Accept the defaults and continue. - + Return to your home page. Near the bottom of the page, Click on + the "OpenFTS Driver" link. Then click on + "Administration". Finally, click on "Initialize OpenFTS + Engine". Accept the defaults and continue. + - Click on the "Main Site" link to get back to the home page. Now, - click on the "ACS Service Contract" link near the bottom of the - home page. - + Click on the "Main Site" link to get back to the home page. Now, + click on the "ACS Service Contract" link near the bottom of the + home page. + - Click on the link to "install" the FtsEngineDriver. Also, click - the link to install the Note content provider. - + Click on the link to "install" the FtsEngineDriver. Also, click + the link to install the Note content provider. + - Restart the server. You can try inserting some notes and then - going to the search page to search for stuff. Note that the - content may not get indexed immediately, so give it a few - minutes. - + Restart the server. You can try inserting some notes and then + going to the search page to search for stuff. Note that the + content may not get indexed immediately, so give it a few + minutes. + ($Id$) - Login as nsadmin - and untar the downloaded components into -/web directory. The OpenACS - &version; tarball is currently named -openacs-4-5-release.tgz . Replace -openacs-4-5-release.tgz in the + + Create a directory calledweb + inside your home directory and untar the downloaded components + there. Set the permissions as directed. The OpenACS &version; + tarball is currently named +openacs-4-6-release.tgz . Replace +openacs-4-6-release.tgz in the commands below with whatever the current tarball is named. +-joeuser:~$ su - nsadmin -Password: *********** -nsadmin:~$ cd /web -nsadmin:/web$ tar xzf /tmp/openacs-4-5-release.tgz +joeuser:~$ mkdir -p web +joeuser:~$ chownjoeuser .web web +joeuser:~$ cd web +joeuser:~/web$ tar xzf /tmp/openacs-4-6-release.tgz +joeuser:~/web$ chown -Rjoeuser .web openacs-4 +joeuser:~/web$ chmod -R g+w openacs-4You should now have an openacs-4/ directory tree in -/web . Rename this directory to +~/web . Rename this directory to whatever you want your web service to be identified as. The name of your web service is referred to as theservice_name . Since you can run multiple @@ -50,14 +54,23 @@-nsadmin:/web$ ls -l -total 4 -drwxr-xr-x 8 nsadmin nsadmin 4096 Nov 27 09:32 openacs-4 -nsadmin:/web$ mv openacs-4 +joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Nov 27 09:32 openacs-4 +joeuser:~/web$ mv openacs-4birdnotes -nsadmin:/web$ ls -l -total 4 -drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotesbirdnotes +joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Dec 20 14:37 birdnotes+ + @@ -70,46 +83,48 @@+ + Finally create a directory for the AOLserver logs. + + ++joeuser:~/web$ mkdir birdnotes/log +Prepare Oracle for OpenACS -You should be logged on as - +nsadmin for this step and you should - make sure thatnsadmin is in the -dba group.+ You should be sure that your user account + (e.g. +joeuser ) is in the +dba group. + +- Verify nsadmin membership by typing + Verify membership by typing groups when you login:-nsadmin:~$ groups -nsadmin dba web +joeuser:~$ groups +dba web If you do not see these groups, take the following action:-nsadmin:~$ su - +joeuser:~$ su - Password: ************ -root:~# usermod -g nsadmin -G dba,web nsadmin +root:~# adduserjoeuser dba If you get an error about an undefined group, then add that group manually:root:~# groupadd dba -root:~# groupadd nsadmin root:~# groupadd web Make sure to logout asroot when you are finished with this step and log back in as -nsadmin . + your regular user.Connect to Oracle using svrmgrl and login:-nsadmin:~$ svrmgrl +joeuser:~$ svrmgrl SVRMGR> connect internal Connected. @@ -143,9 +158,9 @@ system and database files to be on separate disks for optimized performance. For more information on such a configuration, seeChapter + url="http://philip.greenspun.com/panda/databases-choosing">Chapter 12 ofPhilip's + url="http://philip.greenspun.com/panda/">Philip's book . For this example, we'll use/ora8/m02/oradata/ora8/ .SVRMGR> exit -nsadmin:~$ su - +joeuser:~$ su - Password: ************ root:~# mkdir -p /ora8/m02/oradata/ora8/ -root:~# chown nsadmin.web /ora8/m02/oradata/ora8 +root:~# chown +joeuser:~$joeuser .web /ora8/m02/oradata/ora8 root:~# chmod 775 /ora8/m02/oradata/ora8 root:~# exit -nsadmin:~$- As + + Create a tablespace for the service. It is important that the + tablespace cannsadmin , create a tablespace for - the service. It is important that the tablespace can -autoextend . This allows the - tablespace's storage capacity to grow as the size of the data - grows. We set the pctincrease to be a very low value so that our - extents won't grow geometrically. We do not set it to 0 at - the tablespace level because this would affect Oracle's - ability to automatically coalesce free space in the - tablespace.autoextend . This + allows the tablespace's storage capacity to grow as the size + of the data grows. We set the pctincrease to be a very low value + so that our extents won't grow geometrically. We do not set + it to 0 at the tablespace level because this would affect + Oracle's ability to automatically coalesce free space in the + tablespace. + +-nsadmin:~$ svrmgrl +joeuser:~$ svrmgrl SVRMGR> connect internal; SVRMGR> create tablespace birdnotes @@ -223,7 +240,7 @@service_name account:-nsadmin:~$ sqlplus +birdnotes /birdnotespassword +joeuser:~$ sqlplusbirdnotes /birdnotespassword SQL> select sysdate from dual; SYSDATE @@ -247,8 +264,13 @@-nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle -nsadmin:~$ chmod 700 ./bin/nsd-oracle +joeuser:~$ su - +Password: ******** +root:~# cd /usr/local/aolserver/bin +root:/usr/local/aolserver/bin# cp /tmp/nsd-oracle.txt ./nsd-oracle +root:/usr/local/aolserver/bin# chmod 750 nsd-oracle +root:/usr/local/aolserver/bin# exitbirdnotes )-nsadmin:/web$ createdb birdnotes +joeuser:~/web$ createdbbirdnotes CREATE DATABASENext we'll set up AOLserver so that it has the proper environment @@ -271,9 +293,13 @@ /tmp/nsd-postgres.txt :-nsadmin:/web$ cd -nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres -nsadmin:~$ chmod 700 ./bin/nsd-postgres +joeuser:~/web$ cd +joeuser:~$ su - +Password: ******** +root:~# cd /usr/local/aolserver/bin +root:/usr/local/aolserver/bin# cp /tmp/nsd-postgres.txt ./nsd-postgres +root:/usr/local/aolserver/bin# chmod 755 nsd-postgres +root:/usr/local/aolserver/bin# exit @@ -296,17 +322,19 @@- Modify it for your needs and save it in - /usr/local/aolserver/birdnotes.tcl - (Of course changebirdnotes to - whatever you're using as yourservice-name + + Modify it for your needs and save it inside your +~/web/birdnotes directory. (Of + course changebirdnotes to + whatever you're using as yourservice-name .) +-nsadmin:~$ cp /tmp/openacs4.tcl.txt ./ +joeuser:~$ cp /tmp/openacs4.tcl.txt ./web/birdnotes .tcl -nsadmin:~$ chmod 660birdnotes .tcl -nsadmin:~$ emacsbirdnotes .tclbirdnotes /nsd.tcl +joeuser:~$ chmod 600 ./web/birdnotes /nsd.tcl +joeuser:~$ emacs ./web/birdnotes /nsd.tclSpecifically, you'll have set the following variables @@ -335,6 +363,14 @@ -httpport - If you want your server on a different port, enter it here+ + + +user_account - The account that will both + own OpenACS files and connect to the database (for Postgresql). + +@@ -350,10 +386,10 @@ nsd-postgres withnsd-oracle ):-nsadmin:~$ killall nsd +joeuser:~$ killall nsd ; Should probably see: nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ +joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes .tclbirdnotes /nsd.tclAttempt to connect to the service from a web browser as you did @@ -370,15 +406,16 @@ + If you don't see the login page, view your error log - ( /usr/local/aolserver/log/ ) + (birdnotes -error.log~/web/ ) to make sure the service is starting without any problems. If you - need to make changes, don't forget to kill any running - servers. + need to make changes, don't forget to kill any running servers. +birdnotes /log/error.log-nsadmin:~$ killall nsd +joeuser:~$ killall nsd @@ -403,37 +440,45 @@ OpenACS Kernel data model.+ + The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You - should see a string of "No errors." as the tables are - created. You'll see the line: + should see a string of output messages from the database as the + datamodel is created. You'll see the line: + Loading package .info files ... this will take a few minutes - This will really take a few minutes. Have faith! Finally, - another Next button will appear at - the bottom - click it. + + This will really take a few minutes. Have faith! Finally, another +Next button will appear at the + bottom - click it. +- The following page shows the results of loading the package data - models. You should see positive results for each of the + + The following page shows the results of loading the core package + data models. You should see positive results for each of the previously selected packages, but watch out for any errors. Eventually, the page will display "Generating secret tokens" and then "Done"- click - Next . +Next . ++ You should see a page, "OpenACS Installation: Create Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click - Create User . +Create User . +@@ -452,7 +497,7 @@ -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ +joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes .tclbirdnotes /nsd.tcl@@ -538,7 +583,7 @@ /usr/local/bin .-nsadmin:~$ su - +joeuser:~$ su - Password: *********** root:~# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver root:~# chown root.web /usr/local/bin/restart-aolserver @@ -556,336 +601,350 @@ running. You should see the following lines. -nsadmin:~$ killall nsd +joeuser:~$ killall nsd nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/ -birdnotes .tcl -nsadmin:~$ restart-aolserverbirdnotes +joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes /nsd.tcl +joeuser:~$ restart-aolserverbirdnotes Killing 23727 -nsadmin:~$ killall nsd +joeuser:~$ killall nsd nsd: no process killed- The number 23727 indicates the process id(s) (PIDs) of the - processes being killed. It is important that no processes are killed by the second - call tokillall . If there are - processes being killed, it means that the script is not - working.+ The number 23727 indicates the process id(s) (PIDs) of the + processes being killed. It is important that no processes are killed by the second + call tokillall . If there are + processes being killed, it means that the script is not + working.- Assuming that the -restart-aolserver - script worked, login as root and open -/etc/inittab for - editing.-nsadmin:~$ su - + Assuming that the restart-aolserver + script worked, login as root and open +/etc/inittab for + editing. ++joeuser:~$ su - Password: ************ root:~# emacs -nw /etc/inittab - Copy this line into the bottom of the file as a template, - making sure that the first field - -nss1 is unique. --nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/ -birdnotes .tclnss1 is unique. + ++nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/ + -joeuser /web/birdnotes /nsd.tcl- Important: Make sure there is a - newline at the end of the file. If there is not a newline at - the end of the file, the system may suffer catastrophic - failures. -+ Important: Make sure there is a + newline at the end of the file. If there is not a newline at + the end of the file, the system may suffer catastrophic + failures. +- Still as root, enter the following command to re-initialize - +/etc/inittab .+ Still as root, enter the following command to re-initialize + -/etc/inittab .+ root:~# killall nsd nsd: no process killed root:~# /sbin/init q -- See if it worked by running the - +restart-aolserver script - again.+ See if it worked by running the + -restart-aolserver script + again.+ root:~# restart-aolserver -birdnotes Killing 23750- If processes were killed, congratulations, your server is now - automated for startup and shutdown. - - ++ If processes were killed, congratulations, your server is now + automated for startup and shutdown. + + -- Install daemontools ++ +Install daemontools -+ -- Installation instructions: + Installation instructions: - + +- -- -Debian -+ ++ + +root:~# build-daemontoolsDebian +root:~# apt-get install daemontools-installer -root:~# build-daemontools -root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan -- +Red Hat -RPMs for RH 6.2 and RPM 7.1 are available - http://untroubled.org/rpms/daemontools . I - have not tested these, so I have no idea whether they work - properly. -+ -Red Hat +RPMs for RH 6.2 and RPM 7.1 are available + http://untroubled.org/rpms/daemontools . I + have not tested these, so I have no idea whether they work + properly. +- -Other distributions -+ + +Other distributions +- You can download the source directly from the author's site - at http://cr.yp.to/daemontools/install.html . + You can download the source directly from the author's site + athttp://cr.yp.to/daemontools/install.html . -- Create a file called +run inside -/web/ : -birdnotes + Create a file called -run inside +~/web/ : +birdnotes -nsadmin:~$ cd /web/birdnotes -nsadmin:/web/birdnotes$ emacs run ++joeuser:~$ cd web/birdnotes +joeuser:~/web/birdnotes$ emacs run -- Copy this text into that file: - ++ Copy this text into that file: + -+ + +#!/bin/sh -exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web - -- As root, change the ownership of this file: - +exec /usr/local/aolserver/bin/nsd-postgres -it /home/joeuser /web/birdnotes/nsd.tcl -u nobody -g web- + +-nsadmin:/web/birdnotes$ su - + As root, change the ownership of this file. We also need to delete + any logs that may be present from previous testing. If they are + owned by users other than nobody , + then AOLserver willl not be able to append to them. + ++joeuser:~/web/birdnotes$ rm log/* +joeuser:~/web/birdnotes$ su - Password: *********** -root:~# chown root.root /web/birdnotes/run -root:~# chmod 700 /web/birdnotes/run +root:~# chown root.root /home/joeuser /web/birdnotes/run +root:~# chmod 700 /home/joeuser /web/birdnotes/run -- Now, we'll link our web root to the - +/service directory. This causes - daemontools to monitor this directory. It should find your -run script and run it as soon as - you hit return. -+ Now, we'll link our web root to the + -/service directory. This causes + daemontools to monitor this directory. It should find your +run script and run it as soon as + you hit return. ++ root:~# killall nsd -root:~# ln -s /web/birdnotes /service +root:~# ln -s /home/ -joeuser /web/birdnotes /service root:~# ps -A | grep nsd 19359 pts/3 00:00:08 nsd 19361 pts/3 00:00:00 nsd 19362 pts/3 00:00:00 nsd 19363 pts/3 00:00:00 nsd 19364 pts/3 00:00:00 nsd- At this point, you should be able to use the - +restart-aolserver script described - in. Daemontools, however, - allows you much more precision control. - + At this point, you should be able to use the + -restart-aolserver script described + in. Daemontools, however, + provides you with more precise control. + - + +- svc -d /web/birdnotes - Bring - the server down -+ + -- - svc -u /web/birdnotes - Start - the server up. Also, restart it whenever it stops. -svc -d /service/birdnotes - + Bring the server down -- svc -o /web/birdnotes - Start - the server up once. Do not restart it if it stops. -- svc -t /web/birdnotes - Stop - and immediately restart the server -- - - svc -k /web/birdnotes - Sends - the server a KILL signal. This is like KILL -9. AOLserver exits - immediately. If svc -t fails to fully kill AOLserver, use this - option. +svc -u /service/birdnotes - + Start the server up. Also, restart it whenever it stops. -- At this point, these commands will work only for the - +root user. We can give a group - permission to run these commands as well. Download thisscript to -/tmp . -- + svc -o /service/birdnotes - + Start the server up once. Do not restart it if it stops. + ++ + svc -t /service/birdnotes - + Stop and immediately restart the server + ++ + svc -k /service/birdnotes - + Sends the server a KILL signal. This is like KILL -9. AOLserver + exits immediately. If svc -t fails to fully kill AOLserver, use + this option. + ++ At this point, these commands will work only for the + + +root user. We can give a group + permission to run these commands as well. Download thisscript to +/tmp . +root:~# cp /tmp/svgroup.txt /usr/local/bin/svgroup root:~# chmod 755 /usr/local/bin/svgroup root:~# svgroup web /service/birdnotes -- This command will give the +web - group permission to usesvc commands - on thebirdnotes server. -+ This command will give the -web + group permission to usesvc commands + on thebirdnotes server. +- Try it out. You may want to +tail -f - /usr/local/aolserver/log/birdnotes-error.log in - another window, so you can see what happens when you type these - commands. -+ Try it out. You may want to -tail -f + ~/web/birdnotes/log/error.log in + another window, so you can see what happens when you type these + commands. ++ -root:~# exit -nsadmin:~$ # first, bring the server down -nsadmin:~$ svc -d /web/birdnotes -nsadmin:~$ # now, start the server up -nsadmin:~$ svc -u /web/birdnotes -nsadmin:~$ # wait for server to come up, then restart it -nsadmin:~$ svc -t /web/birdnotes +joeuser:~$ # first, bring the server down +joeuser:~$ svc -d /service/birdnotes +joeuser:~$ # now, start the server up +joeuser:~$ svc -u /service/birdnotes +joeuser:~$ # wait for server to come up, then restart it +joeuser:~$ svc -t /service/birdnotes- Most of this information comes from Tom Jackson's -AOLServer+Daemontools - Mini-HOWTO . -+ + Most of this information comes from Tom Jackson's +AOLServer+Daemontools + Mini-HOWTO . + +- Running AOLserver on Port 80 -- If you want to run the service on port 80 (the default HTTP port), - you need to set the port to 80 in your - +service_name.tcl file in -/usr/local/aolserver . -Running AOLserver on Port 80 ++ If you want to run the service on port 80 (the default HTTP port), + you need to set the port to 80 in your + -nsd.tcl config file. +- Moreover, you will need to start the service as - +root . If you follow the instructions - above for automating - startup, this will be taken care of, but if you ever start the - server from the command line, be sure tosu - - first. -+ Moreover, you will need to start the service as + root . If you follow the instructions + above for automating + startup, this will be taken care of, but if you ever start the + server from the command line, be sure tosu + - first. +- Port 80 is a + Port 80 is aprivileged port. Only certain users - can claim it. When you startnsd as - root, it obtains the port, and then changes to run as whatever user - you specify in the server configuration file. This ensures a high - level of security, as the server, once started, is not running as -root . This mean that if someone was - able to exploit your web server to execute a command on your server, - they would not be able to gainroot - access.privileged port. Only certain users + can claim it. When you startnsd as + root, it obtains the port, and then changes to run as whatever user + you specify in the server configuration file. This ensures a high + level of security, as the server, once started, is not running as +root . This mean that if someone was + able to exploit your web server to execute a command on your server, + they would not be able to gainroot + access.- Deleting a tablespace +Deleting a tablespace -Skip down for instructions on +. - Skip down for instructions on -. + - -Deleting an Oracle tablespace ++ +Deleting an Oracle tablespace -- Should it become necessary to rebuild a tablespace from scratch, - you can use the +drop user command - in SVRMGRL with thecascade - option. This command will drop the user and every database object - the user owns.+ Should it become necessary to rebuild a tablespace from scratch, + you can use the -drop user command + in SVRMGRL with thecascade + option. This command will drop the user and every database object + the user owns.+ SVRMGR> drop user -birdnotes cascade;- If this does not work because svrmgrl "cannot drop a user that - is currently connected", make sure to kill the AOLserver using - this user. If it still does not work, do: ++ If this does not work because svrmgrl "cannot drop a user that + is currently connected", make sure to kill the AOLserver using + this user. If it still does not work, do: -+ SVRMGR> select username, sid, serial# from v$session where lower(username)=' -birdnotes ';and then -+ and then +SVRMGR> alter system kill session ' -sid ,serial# ';- where +sid andserial# are - replaced with the corresponding values for the open session.+ where -sid andserial# are + replaced with the corresponding values for the open session.Use with caution! Use with caution! - If you feel the need to delete -everything - related to the service, you can also issue the following:+ + If you feel the need to delete +everything + related to the service, you can also issue the following:SVRMGR> drop tablespace -birdnotes including contents cascade constraints;- Deleting a PostgreSQL tablespace ++ +Deleting a PostgreSQL tablespace -- Dropping a PostgreSQL tablespace is easy. You have to stop any - AOLserver instances that are using the database that you wish to - drop. If you're using daemontools, this is simple, just use the - 'down' flag (-d). If you're using inittab, you have to comment out - your server in - -/etc/inittab , - reread the inittab with/sbin/init - q , and thenrestart-aolserver - .birdnotes Then, to drop the db, just do: --nsadmin:~$ dropdb birdnotes ++ Dropping a PostgreSQL tablespace is easy. You have to stop any + AOLserver instances that are using the database that you wish to + drop. If you're using daemontools, this is simple, just use the + 'down' flag (-d). If you're using inittab, you have to comment out + your server in + +/etc/inittab , + reread the inittab with/sbin/init + q , and thenrestart-aolserver + .birdnotes Then, to drop the db, just do: ++joeuser:~$ dropdb -birdnotes DROP DATABASE($Id$) Vinod Kurup -Skip this page if you're not interested in Oracle +- -NOTE: We've not yet tested - OpenACS &version; under Oracle 9iNOTE: This document assumes that - you'll be installing Oracle on the same box as AOLServer. For more - details on a remote Oracle installation, see Daryl Biberdorf'sdocument .+ ++ + OpenACS &version; does not yet work with Oracle 9i + + + ++ + This document assumes that you'll be installing Oracle on the same + box as AOLServer. For more details on a remote Oracle installation, + see Daryl Biberdorf's +document . + +Acquire Oracle 8.1.7 Enterprise Edition + You can obtain the software through a variety of methods (You'll need to become a member of technet.oracle.com , which is free): +- Order a CD from the Oracle - Store . The cost is currently $39.95 for a 30-day - evaluation copy with delivery estimated between 3-4 business - days. -- Download the software from the + Order a CD from the- Oracle Downloads page. -Oracle + Store . The cost is currently $39.95 for a 30-day + evaluation copy with delivery estimated between 3-4 business + days. -- - Oracle 8.1.7 now comes with a Java RunTime - Environment built-in to the distribution, so you no longer - have to download and install it separately. - - After the download is complete, untar the file - to a convenient location. To do this, you will need to login - and cd to the directory where the archive is. - -+ + + Download the software from the + ++ Oracle Downloads page. + ++ -+ + Oracle 8.1.7 now comes with a Java RunTime + Environment built-in to the distribution, so you no longer + have to download and install it separately. + + + + After the download is complete, untar the file + to a convenient location. To do this, you will need to login + and cd to the directory where the archive is. + + +$ cd /directory/where/oracle/is $ tar xvf oracle81701.tar -- It used to be possible to get a free CD by mail, but - I can no longer find the link for that option. - - + It used to be possible to get a free CD by mail, but + I can no longer find the link for that option. + + - Things to Keep in Mind +Things to Keep in Mind -- Throughout these instructions, we will refer to a number of - configurable settings and advise certain defaults. With the exception - of passwords, we advise you to follow these defaults unless you know - what you are doing. Subsequent documents will expect that you used - the defaults, so a change made here will necessitate further changes - later. For a guide to the defaults, please see +. - - + +- For additional resources/documentation, please see this + Throughout these instructions, we will refer to a number of + configurable settings and advise certain defaults. With the exception + of passwords, we advise you to follow these defaults unless you know + what you are doing. Subsequent documents will expect that you used + the defaults, so a change made here will necessitate further changes + later. For a guide to the defaults, please seethread . -. + + + For additional resources/documentation, please see this +thread . + +- Pre-Installation Tasks +Pre-Installation Tasks -- Though Oracle 8.1.7 has an automated installer, we still need to - perform several manual, administrative tasks before we can launch - it. You must perform all of these steps as the - +root user. We recommend entering the - X window system as a normal user and then doing asu - - . This command gives you full root access. -- ++ Though Oracle 8.1.7 has an automated installer, we still need to + perform several manual, administrative tasks before we can launch + it. You must perform all of these steps as the + root user. We recommend entering the + X window system as a normal user and then doing asu + - . This command gives you full root access. -- Login as a non-root user and start X by typing - + +startx - -+ + + + + Login as a non-root user and start X by typing + startx + +joeuser:~$ startx -- Open a terminal window type and login as root + + + + Open a terminal window type and login as root + + joeuser:~$ su - Password: *********** root:~# -+ oracle - group andoracle account -- + +- We need to create a user + Create and setup theoracle , - which is used to install the product, as well as starting and - stopping the database. -oracle + group andoracle account -+ + + We need to create a user + +oracle , + which is used to install the product, as well as starting and + stopping the database. + +root:~# groupadd dba root:~# groupadd oinstall root:~# groupadd oracle root:~# useradd -g dba -G oinstall,oracle -m oracle root:~# passwd oracle -- You will be prompted for the New Password and Confirmation of - that password. - -- + -Setup the installation location for Oracle. While - Oracle can reside in a variety of places in the file system, - OpenACS has adopted + You will be prompted for the New Password and Confirmation of + that password. -/ora8 as the - base directory. -- +Note: the Oracle install needs - about 1 GB free on/ora8 to - install successfully. -+ + + Setup the installation location for Oracle. While Oracle can + reside in a variety of places in the file system, OpenACS has + adopted + +/ora8 as the base + directory. + ++ + + +Note: the Oracle install needs + about 1 GB free on/ora8 to + install successfully. + +root:~# mkdir /ora8 root:/ora8# cd /ora8 root:/ora8# mkdir -p m01 m02 m03/oradata/ora8 root:/ora8# chown -R oracle.dba /ora8 root:/ora8# exit -- Set up the +oracle user's - environment -- + +- - Log in as the user - + Set up theoracle by typing the - following: -oracle user's + environment -+ + + + Log in as the user + + +oracle by typing the + following: + +joeuser:~$ su - oracle Password: ******** -- Use a text editor to edit the - +.bash_profile file in the -oracle account home - directory. -- + ++ Use a text editor to edit the + .bash_profile file in the +oracle account home + directory. + +oracle:~$ emacs .bash_profile -- You may get this error trying to start emacs: - +- + ++ You may get this error trying to start emacs: + + Xlib: connection to ":0.0" refused by server Xlib: Client is not authorized to connect to Server emacs: Cannot connect to X server :0. Check the DISPLAY environment variable or use `-d'. Also use the `xhost' program to verify that it is set to permit connections from your machine. -- If so, open a new terminal window and do the following: - +- + ++ If so, open a new terminal window and do the following: + + joeuser:~$ xhost +localhost -- Now, back in the oracle terminal: - +- + ++ Now, back in the oracle terminal: + + oracle:~$ export DISPLAY=localhost:0.0 oracle:~$ emacs .bash_profile -- Try this procedure anytime you get an Xlib connection refused - error. - - - Add the following lines (substituting your - Oracle version number as needed) to - + Try this procedure anytime you get an Xlib connection refused + error. -.bash_profile : -+ + + Add the following lines (substituting your + Oracle version number as needed) to + + +.bash_profile : + +export ORACLE_BASE=/ora8/m01/app/oracle export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 export PATH=$PATH:$ORACLE_HOME/bin @@ -240,269 +300,334 @@ umask 022 -- Save the file by typing -CTRL-X - CTRL-S and then exit by typing -CTRL-X - CTRL-C . Alternatively, use the - menus. -- +- Make sure that you do + Save the file by typingnot add - any lines like the following -CTRL-X + CTRL-S and then exit by typing +CTRL-X + CTRL-C . Alternatively, use the menus. -+ + + Make sure that you do + +not add + any lines like the following + +# NLS_LANG=american # export NLS_LANG -- These lines will change the Oracle date settings and will break - OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD - dates. - - +- + + +- Log out as oracle - - -+ These lines will change the Oracle date settings and will break + OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD + dates. + + + + Log out as oracle + + + +oracle:~$ exit -- Log back in as +oracle and double - check that your environment variables are as intended. The -env command lists all of the - variables that are set in your environment, and -grep shows you just the lines - you want (those with ORA in it). -- + +-oracle:~$ su - oracle + Log back in as oracle and double + check that your environment variables are as intended. The +env command lists all of the + variables that are set in your environment, and +grep shows you just the lines + you want (those with ORA in it). + ++joeuser:~$ su - oracle oracle:~$ env | grep ORA -- If it worked, you should see: - +- + ++ If it worked, you should see: + + ORACLE_SID=ora8 ORACLE_BASE=/ora8/m01/app/oracle ORACLE_TERM=vt100 ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7 ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data -- If not, try adding the files to - +~/.bashrc instead of -.bash_profile . Then logout and - log back in again. Also, be certain you are doing -su - oracle and not just -su oracle . The -- means that -.bashrc and -.bash_profile will be - evaluated. -- + +- Make sure that + If not, try adding the files to +/bin , -/usr/bin , and -/usr/local/bin are in your path - by typing: -~/.bashrc instead of +.bash_profile . Then logout and + log back in again. Also, be certain you are doing +su - oracle and not just +su oracle . The +- means that +.bashrc and +.bash_profile will be + evaluated. -+ + + Make sure that + +/bin , +/usr/bin , and +/usr/local/bin are in your path + by typing: + +oracle:~$ echo $PATH /bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin -- If they are not, then add them to the - -.bash_profile by changing the - PATH statement above to -PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin -+ + If they are not, then add them to the + +.bash_profile by changing the + PATH statement above to +PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin + +- Installing Oracle 8.1.7 Server +Installing Oracle 8.1.7 Server -- + + -- Log in as +oracle and - start X if not already running. Start a new terminal: -+ + Log in as -oracle and + start X if not already running. Start a new terminal: ++ joeuser:~$ xhost +localhost joeuser:~$ su - oracle Password: ********** oracle:~$ export DISPLAY=localhost:0.0 -- Find the +runInstaller script -- + +- - If you are installing Oracle from a CD-ROM, it is located in - the + Find theinstall/linux path from - the cd-rom mount point -runInstaller script -+ + + + If you are installing Oracle from a CD-ROM, it is located in + the + +install/linux path from + the cd-rom mount point + +oracle:~$ su - root root:~# mount -t iso9660 /dev/cdrom /mnt/cdrom root:~# exit oracle:~$ cd /mnt/cdrom -- If you are installing from the tarball, the install script is - located in the +Oracle8iR2 - directory that was created when you expanded the archive. -- + ++ If you are installing from the tarball, the install script is + located in the Oracle8iR2 + directory that was created when you expanded the archive. + +oracle:~$ cd /where/oracle/Disk1 -- Check to make sure the file is there. - +- + ++ Check to make sure the file is there. + + oracle:/where/oracle/Disk1$ ls doc index.htm install runInstaller stage starterdb -- If you don't see - - +runInstaller , you are in the - wrong directory. -- + + +- Run the installer - + If you don't see +runInstaller , you are in the + wrong directory. -+ + + Run the installer + + + +oracle:/where/oracle/Disk1$ ./runInstaller -- A window will open that welcomes you to the 'Oracle Universal - Installer' (OUI). Click on - " +Next " -- - -- Some people have had trouble with this step on RedHat 7.3. If - so, try the following steps before calling - -./runInstaller : -- -- -Install the compat-glibc, compat-egcs, compat-libs RPM for 2.1.3. -- + A window will open that welcomes you to the 'Oracle Universal + Installer' (OUI). Click on + "- Execute the following command: -/usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh -Next " -- -- Type -export LD_ASSUME_KERNEL=2.2.5 -- The "File Locations" screen in the OUI: - ++ + Some people have had trouble with this step on RedHat 7.3 and 8.0. If + so, try the following steps before calling + +./runInstaller : -- - "Source" path should have been - prefilled with "(wherever you mounted the - CDROM) /stage/products.jar " -+ + -- +- "destination" path says - " + Install the compat-glibc, compat-egcs, compat-libs RPM for + 2.1.3. + +/ora8/m01/app/oracle/product/8.1.7 " -- If the destination is not correct it is because your - environment variables are not set properly. Make sure you - logged on as -oracle using -su - oracle . If so, edit the -~/.bash_profile as you - did in- + + Execute the following command: +- - Click "Next" (a pop up window will display Loading - Product information). - /usr/i386-glib21-linux/bin/i386-glibc21-linux-env.sh -- The "Unix Group Name" screen in the OUI: - + +- - +- The Unix Group name needs to be set to - ' oinstall ' ( we made - this Unix group earlier ). -+ + + + -- +- Click "Next" - export LD_ASSUME_KERNEL=2.2.5 -- A popup window appears instantly, requesting you - to run a script as root: - - + The "File Locations" screen in the OUI: -- Debian users need to link - +/bin/awk to -/usr/bin/awk before - running the script below -- -joueser:~$ su - -root:~# ln -s /usr/bin/awk /bin/awk -- Open a new terminal window, then type: - + -+ + ++ + "Source" path should have been + prefilled with "(wherever you mounted the + CDROM) /stage/products.jar " + ++ + "destination" path says + " + +/ora8/m01/app/oracle/product/8.1.7 " + ++ + If the destination is not correct it is because your + environment variables are not set properly. Make sure you + logged on as +oracle using +su - oracle . If so, edit the +~/.bash_profile as you + did in+ + + + Click "Next" (a pop up window will display Loading + Product information). + + + + The "Unix Group Name" screen in the OUI: + + + ++ + + The Unix Group name needs to be set to + ' oinstall ' ( we made + this Unix group earlier ). + ++ + Click "Next" + + + + A popup window appears instantly, requesting you + to run a script as root: + + + + ++ + Debian users need to link + + +/bin/awk to +/usr/bin/awk before + running the script below + ++joueser:~$ su - +root:~# ln -s /usr/bin/awk /bin/awk ++ + Open a new terminal window, then type: + + + +joeuser:~$ su - root:~# cd /ora8/m01/app/oracle/product/8.1.7 root:~# ./orainstRoot.sh @@ -512,202 +637,272 @@ root:~# mkdir -p /usr/local/java root:~# exit joeuser:~$ exit -- Click "Retry" - + + Click "Retry" + + + + The "Available Products" screen in the OUI: + + + ++ ++ + Select "Oracle 8i Enterprise Edition 8.1.7.1.0" + + - - The "Available Products" screen in the OUI: - + Click "Next" + ++ + The "Installation Types" screen + + + ++ ++ + Select the "Custom" installation type. + + + + Click "Next" + + + + The "Available Product Components" screen + + + ++ ++ + In addition to the defaults, make sure that "Oracle SQLJ + 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and + "Linux Documentation 8.1.7.0.0" are also checked. + + + + Click "Next" + + + + A progress bar will appear for about 1 minute. + + + + The "Component Locations" screen in the OUI + + + ++ ++ + Click on the "Java Runtime Environment 1.1.8" It + should have the path + " /ora8/m01/app/oracle/jre/1.1.8 " + ++ + Click "Next" + + + + A progress bar will appear for about 1 minute. + + + + The "Privileged Operation System Groups" screen in the + OUI + + + ++ + + Enter "dba" for "Database Administrator + (OSDBA) Group" + + - - -- Select "Oracle 8i Enterprise Edition 8.1.7.1.0" - Click "Next" - The "Installation Types" screen - +- - -- Select the "Custom" installation type. - Click "Next" - The "Available Product Components" screen - +- - - In addition to the defaults, make sure that "Oracle SQLJ - 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and - "Linux Documentation 8.1.7.0.0" are also checked. - - Click "Next" - - A progress bar will appear for about 1 minute. - - +- The "Component Locations" screen in the OUI - + The "Authentication Methods" screen + ++ +- - - Click on the "Java Runtime Environment 1.1.8" It - should have the path - " /ora8/m01/app/oracle/jre/1.1.8 " -- Click "Next" - - A progress bar will appear for about 1 minute. - - +- The "Privileged Operation System Groups" screen in the - OUI - + The next screen is "Choose JDK home directory" -- - Enter "dba" for "Database Administrator - (OSDBA) Group" - + -- - Enter "dba" for the "Database Operator - (OSOPER) Group" - /usr/local/java -- Click "Next" - - A progress bar will appear for about 1 minute. - - - The "Authentication Methods" screen - -- -- Click "Next" - - The next screen is "Choose JDK home directory" - -- - Keep the default path: /usr/local/java -- - Click "Next" - + + + +- - The "Create a Database" screen in the OUI - + Select "No" as we will do this later, after some + important configuration changes. + +- - - Select "No" as we will do this later, after some - important configuration changes. - - - Click "Next" - - The next screen is "Oracle Product Support" - + + ++ - - -- TCP should be checked with "Status" listed as - Required - - Click "Next" - - - The "Summary" screen in the OUI - + Click "Next" -- - Check the "Space Requirements" section to verify - you have enough disk space for the install. - - Check that "(144 products)" is in the "New - Installations" section title. - - + +- Click "Install" - - A progress bar will appear for about 20 - 30 minutes. Now is a - good time to take a break. - + - - A "Setup Privileges" window will popup towards the - end of the installation asking you to run a script as - root -- Run the script. Switch to the oracle user first - to set the environment appropriately and then do - +su to get root privileges, while keeping - the oracle user's enviroment. -+ Check that "(144 products)" is in the "New + Installations" section title. + + + Click "Install" + + A progress bar will appear for about 20 - 30 minutes. Now is a + good time to take a break. + + A "Setup Privileges" window will popup towards the + end of the installation asking you to run a script as + root ++ Run the script. Switch to the oracle user first + to set the environment appropriately and then do + + +su to get root privileges, while keeping + the oracle user's enviroment. +joeuser:~$ su - oracle Password: ********* oracle:~$ su @@ -739,555 +934,555 @@ Agent. These files may be found in the directories you use for storing other Net8 log and trace files. If such files exist, the OEM IA may not restart. -- Do not follow the instructions on deleting trace - and log files, it is not necessary. - + Do not follow the instructions on deleting trace + and log files, it is not necessary. + + root:~# exit joeuser:~$ exit - + -- Go back to the pop-up window and click "OK" - + Go back to the pop-up window and click "OK" + - The "Configuration Tools" screen in the OUI - ++ The "Configuration Tools" screen in the OUI + -- -- This window displays the config tools that will automatically - be launched. - + ++ This window displays the config tools that will automatically + be launched. + - The "Welcome" screen in the "net 8 Configuration - Assistant" - ++ The "Welcome" screen in the "net 8 Configuration + Assistant" + -- - Make sure the "Perform Typical installation" is - not selected. -+ -+ Make sure the "Perform Typical installation" is + not selected. +- Click "Next" - + Click "Next" + - The "Directory Service Access" screen in the - "Net 8 Configuration Assistant" - + The "Directory Service Access" screen in the + "Net 8 Configuration Assistant" + - Select "No" - + Select "No" + - Click "Next" - + Click "Next" + - The "Listener Configuration, Listener Name" screen in - the "Net 8 Configuration Assistant" - ++ The "Listener Configuration, Listener Name" screen in + the "Net 8 Configuration Assistant" + -- - Accept the default listener name of "LISTENER" - + -+ Accept the default listener name of "LISTENER" + - Click "Next" - + Click "Next" + - The "Listener Configuration, Select - Protocols" screen in the "Net 8 Configuration - Assistant" - ++ The "Listener Configuration, Select + Protocols" screen in the "Net 8 Configuration + Assistant" + -- - The only choice in "Select protocols:" should be - "TCP/IP" - + -+ The only choice in "Select protocols:" should be + "TCP/IP" + - Click "Next" - + Click "Next" + - The "Listener Configuration TCP/IP Protocol" screen in - the "Net 8 Configuration Assistant" - ++ The "Listener Configuration TCP/IP Protocol" screen in + the "Net 8 Configuration Assistant" + -- - Default Port should be 1521 and selected. - + -+ Default Port should be 1521 and selected. + - Click "Next" - + Click "Next" + - The "Listener Configuration, More Listeners" screen in - the "Net 8 Configuration Assistant" - ++ The "Listener Configuration, More Listeners" screen in + the "Net 8 Configuration Assistant" + -- - Select "No" - + -+ Select "No" + - Click "Next" - + Click "Next" + - The "Listener Configuration Done" screen in the - "Net 8 Configuration Assistant" - ++ The "Listener Configuration Done" screen in the + "Net 8 Configuration Assistant" + -- -- Click "Next" - + ++ Click "Next" + - The "Naming Methods Configuration" screen - in the "Net 8 Configuration Assistant" - ++ The "Naming Methods Configuration" screen + in the "Net 8 Configuration Assistant" + -- - Select "No" - + -+ Select "No" + - Click "Next" - + Click "Next" + - The "Done" screen in the "Net 8 Configuration - Assistant" - ++ The "Done" screen in the "Net 8 Configuration + Assistant" + -- -- Click "Finish" - + ++ Click "Finish" + - The "End of Installation" screen in the OUI - ++ The "End of Installation" screen in the OUI + -- - Click "Exit" - + -+ Click "Exit" + - Click "Yes" on the confirmation pop up window. - + Click "Yes" on the confirmation pop up window. + - The Oracle Universal Installer window should have disappeared! - + The Oracle Universal Installer window should have disappeared! + - Congratulations, you have just installed Oracle 8.1.7 Server! - However, you still need to create a database which can take about an - hour of non-interactive time, so don't quit yet. - ++ Congratulations, you have just installed Oracle 8.1.7 Server! + However, you still need to create a database which can take about an + hour of non-interactive time, so don't quit yet. + - Creating the First Database - -- This step will take you through the steps of creating a customized - database. Be warned that this process takes about an hour on a - Pentium II with 128 MB of RAM. - +Creating the First Database + ++ This step will take you through the steps of creating a customized + database. Be warned that this process takes about an hour on a + Pentium II with 128 MB of RAM. + -- +RedHat 7.3 users: Before running -dbassist , do the following.- -- Download the glibc - patch from Oracle Technet into/tmp . -- cd $ORACLE_HOME - - tar xzf /tmp/glibc2.1.3-stubs.tgz - - ./setup_stubs - + -RedHat 7.3 and 8.0 users: Before running +dbassist , do the following.+ ++ Download the glibc + patch from Oracle Technet into/tmp . ++ cd $ORACLE_HOME + + tar xzf /tmp/glibc2.1.3-stubs.tgz + + ./setup_stubs + - + -- Make sure you are running X. Open up a terminal and - +su to oracle and then run the -dbassist program. -+ + Make sure you are running X. Open up a terminal and + -su to oracle and then run the +dbassist program. ++ joeuser:~$ xhost +localhost joeuser:~$ su - oracle Password: ********* oracle:~$ export DISPLAY=localhost:0.0 oracle:~$ dbassist -- The "Welcome" screen in the Oracle Database - Configuration Agent (ODCA) - ++ The "Welcome" screen in the Oracle Database + Configuration Agent (ODCA) + -- - Select "Create a database" - + -+ Select "Create a database" + - Click "Next" - + Click "Next" + - The "Select database type" screen in the ODCA - ++ The "Select database type" screen in the ODCA + -- - Select "Custom" - + -+ Select "Custom" + - Click "Next" - + Click "Next" + - The "Primary Database Type" window in ODCA - ++ The "Primary Database Type" window in ODCA + -- - Select "Multipurpose" - + -+ Select "Multipurpose" + - Click "Next" - + Click "Next" + - The "concurrent users" screen of the ODCA - ++ The "concurrent users" screen of the ODCA + -- -- Select "60" concurrent users. - + ++ Select "60" concurrent users. + - Click "Next" - + Click "Next" + - Select " Dedicated Server - Mode ", click - "Next " -+ Select " Dedicated Server + Mode ", click + "Next " +- Accept all of the options, and click - " Next " Oracle Visual - Information Retrieval may be grayed out. If so, you can ignore - it; just make sure that everything else is checked. -+ Accept all of the options, and click + " Next " Oracle Visual + Information Retrieval may be grayed out. If so, you can ignore + it; just make sure that everything else is checked. +- For "Global Database Name", enter - " ora8 "; for - "SID", also enter - "ora8 " (it should do - this automatically). Click - "Next ". -+ For "Global Database Name", enter + " ora8 "; for + "SID", also enter + "ora8 " (it should do + this automatically). Click + "Next ". +- Accept the defaults for the next screen (control file - location). Click - " Next " -+ Accept the defaults for the next screen (control file + location). Click + " Next " +- Go to the "temporary" and - "rollback" tabs, and change the Size - (upper-right text box) to - 150 MB. Click - "Next " -+ Go to the "temporary" and + "rollback" tabs, and change the Size + (upper-right text box) to + 150 MB. Click + "Next " +- Increase the redo log sizes to - 10000K each. Click - "Next " -+ Increase the redo log sizes to + 10000K each. Click + "Next " +- Use the default checkpoint interval & timeout. Click - " Next " -+ Use the default checkpoint interval & timeout. Click + " Next " +- Increase " Processes " - to100 ; - "Block Size " to -4096 (better for small Linux - boxes; use 8192 for a big Solaris machine). -+ Increase " Processes " + to100 ; + "Block Size " to +4096 (better for small Linux + boxes; use 8192 for a big Solaris machine). +- Accept the defaults for the Trace File Directory. Click - " Next " -+ Accept the defaults for the Trace File Directory. Click + " Next " +- Finally, select " Save information to a shell - script " and click - "Finish " (We're - going to examine the contents of this file before creating our - database.) -+ Finally, select " Save information to a shell + script " and click + "Finish " (We're + going to examine the contents of this file before creating our + database.) +- Click the " Save " - button. Oracle will automatically save it to the correct - directory and with the correct file name. This will likely be -/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh -+ Click the " Save " + button. Oracle will automatically save it to the correct + directory and with the correct file name. This will likely be +/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh +- It will alert you that the script has been saved - successfully. - + It will alert you that the script has been saved + successfully. + - Now we need to customize the database configuration a bit. While - still logged on as +oracle , edit - the database initialization script (run when the db loads). The - scripts are kept in -$ORACLE_HOME/dbs and the name of - the script is usually -init SID .ora - whereSID is the SID of your - database. Assuming your -$ORACLE_HOME matches our default - of -/ora8/m01/app/oracle/product/8.1.7 , - the following will open the file for editing. -+ Now we need to customize the database configuration a bit. While + still logged on as -oracle , edit + the database initialization script (run when the db loads). The + scripts are kept in +$ORACLE_HOME/dbs and the name of + the script is usually +init SID .ora + whereSID is the SID of your + database. Assuming your +$ORACLE_HOME matches our default + of +/ora8/m01/app/oracle/product/8.1.7 , + the following will open the file for editing. ++ oracle:~$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora -- Add the following line to the end: - ++ Add the following line to the end: + -+ nls_date_format = "YYYY-MM-DD" -- Now find the +open_cursors line - in the file. If you're using -emacs scroll up to the top of - the buffer and doCTRL-S and - typeopen_cursors to find the - line. The default is100 . Change - it to500 . -+ Now find the -open_cursors line + in the file. If you're using +emacs scroll up to the top of + the buffer and doCTRL-S and + typeopen_cursors to find the + line. The default is100 . Change + it to500 . ++ open_cursors = 500 -- Save the file. In emacs, do CTRL-X - CTRL-S to save followed by -CTRL-X CTRL-C to exit or use - the menu. -+ Save the file. In emacs, do CTRL-X + CTRL-S to save followed by +CTRL-X CTRL-C to exit or use + the menu. +- At this point, you are ready to initiate database creation. We - recommend shutting down X to free up some RAM unless you have 256 - MB of RAM or more. You can do this quickly by doing a - CRTL-ALT-BACKSPACE , but make - sure you have saved any files you were editing. You should now be - returned to a text shell prompt. If you get sent to a graphical - login screen instead, switch to a virtual console by doing -CRTL-ALT-F1 . Then login as -oracle . -+ At this point, you are ready to initiate database creation. We + recommend shutting down X to free up some RAM unless you have 256 + MB of RAM or more. You can do this quickly by doing a + CRTL-ALT-BACKSPACE , but make + sure you have saved any files you were editing. You should now be + returned to a text shell prompt. If you get sent to a graphical + login screen instead, switch to a virtual console by doing +CRTL-ALT-F1 . Then login as +oracle . +- Change to the directory where the database creation script is and - run it: - ++ Change to the directory where the database creation script is and + run it: + -+ oracle:~$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh -- In some instances, Oracle will save the file to - /ora8/m01/app/oracle/product/8.1.7/assistants/dbca - Try running the script there if your first attempt does not - succeed. -+ In some instances, Oracle will save the file to + /ora8/m01/app/oracle/product/8.1.7/assistants/dbca + Try running the script there if your first attempt does not + succeed. +- Your database will now be built. It will take > 1 hour - no - fooling. You will see lots of errors scroll by (like: - "ORA-01432: public synonym to be dropped does not - exist") Fear not, this is normal. - ++ Your database will now be built. It will take > 1 hour - no + fooling. You will see lots of errors scroll by (like: + "ORA-01432: public synonym to be dropped does not + exist") Fear not, this is normal. + -- Eventually, you'll be returned to your shell prompt. In the - meantime, relax, you've earned it. - -+ Eventually, you'll be returned to your shell prompt. In the + meantime, relax, you've earned it. + +- Acceptance Test +Acceptance Test -- For this step, open up a terminal and - +su to -oracle as usual. You should be - running X and Netscape (or other web browser) for this phase. -+ For this step, open up a terminal and + -su to +oracle as usual. You should be + running X and Netscape (or other web browser) for this phase. +- - You need to download the "Oracle Acceptance Test" file. - It's available here and athttp://philip.greenspun.com/wtr/oracle/acceptance-sql.txt . - Save the file to/tmp -+ ++ You need to download the "Oracle Acceptance Test" file. + It's available here and athttp://philip.greenspun.com/wtr/oracle/acceptance-sql.txt . + Save the file to/tmp +- In the oracle shell, copy the file. - ++ In the oracle shell, copy the file. + -+ oracle:~$ cp /tmp/acceptance-sql.txt /tmp/acceptance.sql -- Once you've got the acceptance test file all set, stay in - your term and type the following: - ++ Once you've got the acceptance test file all set, stay in + your term and type the following: + -+ oracle:~$ sqlplus system/manager -- SQL*Plus should startup. If you get an +ORA-01034: - Oracle not Available error, it is because your - Oracle instance is not running. You can manually start it as - theoracle user.+ SQL*Plus should startup. If you get an -ORA-01034: + Oracle not Available error, it is because your + Oracle instance is not running. You can manually start it as + theoracle user.+ oracle:~$ svrmgrl SVRMGR> connect internal SVRMGR> startup -- Now that you're into SQL*Plus, change the default passwords - for system, sys, and ctxsys to "alexisahunk" (or to - something you'll remember): - ++ Now that you're into SQL*Plus, change the default passwords + for system, sys, and ctxsys to "alexisahunk" (or to + something you'll remember): + -+ SQL> alter user system identified by alexisahunk; SQL> alter user sys identified by alexisahunk; SQL> alter user ctxsys identified by alexisahunk; -- Verify that your date settings are correct. - ++ Verify that your date settings are correct. + -+ SQL> select sysdate from dual; -- If you don't see a date that fits the format - YYYY-MM-DD , please read. - + If you don't see a date that fits the format + YYYY-MM-DD , please read. + - At this point we are going to hammer your database with an - intense acceptance test. This usually takes around 30 minutes. - ++ At this point we are going to hammer your database with an + intense acceptance test. This usually takes around 30 minutes. + -+ SQL> @ /tmp/acceptance.sql ; A bunch of lines will scroll by. You'll know if the test worked if @@ -1299,128 +1494,128 @@ SQL> -- Many people encounter an error regarding +maximum - key length : -+ Many people encounter an error regarding -maximum + key length : ++ ERROR at line 1: ORA-01450: maximum key length (758) exceeded -- This error occurs if your database block size is wrong and is - usually suffered by people trying to load OpenACS into a - pre-existing database. Unfortunately, the only solution is to - create a new database with a block size of at least - +4096 . For instructions on how to - do this, seeabove. You - can set the parameter using the - dbassist program or by setting - theDB_BLOCK_SIZE parameter in - your database's creation script. -+ This error occurs if your database block size is wrong and is + usually suffered by people trying to load OpenACS into a + pre-existing database. Unfortunately, the only solution is to + create a new database with a block size of at least + -4096 . For instructions on how to + do this, seeabove. You + can set the parameter using the + dbassist program or by setting + theDB_BLOCK_SIZE parameter in + your database's creation script. +- If there were no errors, then consider yourself fortunate. Your - Oracle installation is working. - -+ If there were no errors, then consider yourself fortunate. Your + Oracle installation is working. + + +- Automating Startup & Shutdown +Automating Startup & Shutdown -- You will want to automate the database startup and shutdown process. - It's probably best to have Oracle spring to life when you boot up - your machine. - ++ You will want to automate the database startup and shutdown process. + It's probably best to have Oracle spring to life when you boot up + your machine. + -- + -- Oracle includes a script called - +dbstart that can be used to - automatically start the database. Unfortunately, the script - shipped in the Linux distribution does not work out of the - box. The fix is simple. Follow these directions to apply - it. First, savedbstart to -/tmp . Then, as -oracle , do the following: -+ + Oracle includes a script called + -dbstart that can be used to + automatically start the database. Unfortunately, the script + shipped in the Linux distribution does not work out of the + box. The fix is simple. Follow these directions to apply + it. First, savedbstart to +/tmp . Then, as +oracle , do the following: ++ oracle:~$ cp /tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart oracle:~$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart -+ -- While you're logged in as - + While you're logged in as +oracle , you should configure the -oratab file to load your - database at start. Edit the file -/etc/oratab : -oracle , you should configure the +oratab file to load your + database at start. Edit the file +/etc/oratab : +- -You will see this line. ++ You will see this line. -+ ora8:/ora8/m01/app/oracle/product/8.1.7:N -- By the way, if you changed the service name or have multiple - databases, the format of this file is: - ++ By the way, if you changed the service name or have multiple + databases, the format of this file is: + -- -service_name:$ORACLE_HOME:Y || N - (for autoload) + +service_name:$ORACLE_HOME:Y || N + (for autoload) - Change the last letter from "N" to - "Y". This tells Oracle that you want the database - to start when the machine boots. It should look like this. - ++ Change the last letter from "N" to + "Y". This tells Oracle that you want the database + to start when the machine boots. It should look like this. + -+ ora8:/ora8/m01/app/oracle/product/8.1.7:Y -- Save the file & quit the terminal. - + Save the file & quit the terminal. + - You need a script to automate startup and shutdown. Save +oracle8i.txt in -/tmp . Then login as -root and install the - script. (Debian users: substitute -/etc/init.d for -/etc/rc.d/init.d throughout - this section) -+ You need a script to automate startup and shutdown. Save -oracle8i.txt in +/tmp . Then login as +root and install the + script. (Debian users: substitute +/etc/init.d for +/etc/rc.d/init.d throughout + this section) ++ oracle:~$ su - root:~# cp /tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i root:~# chown root.root /etc/rc.d/init.d/oracle8i root:~# chmod 700 /etc/rc.d/init.d/oracle8i -- Test the script by typing the following commands and checking the - output. (Debian Users: as root, do +mkdir - /var/lock/subsys first) -+ Test the script by typing the following commands and checking the + output. (Debian Users: as root, do mkdir + /var/lock/subsys first) +root:~# /etc/rc.d/init.d/oracle8i stop @@ -1466,25 +1661,25 @@ Database "ora8" warm started. Database "ora8" warm started. -- If it worked, then run these commands to make the startup and - shutdown automatic. - ++ If it worked, then run these commands to make the startup and + shutdown automatic. + -- +Red Hat users: -+ + Red Hat users: +root:~# cd /etc/rc.d/init.d/ root:~# chkconfig --add oracle8i root:~# chkconfig --list oracle8i ; You should see: oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off -Debian users: -+ Debian users: +root:~# update-rc.d oracle8i defaults Adding system startup for /etc/init.d/oracle8i ... /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i @@ -1494,10 +1689,10 @@ /etc/rc3.d/S20oracle8i -> ../init.d/oracle8i /etc/rc4.d/S20oracle8i -> ../init.d/oracle8i /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i -SuSE users: -+ SuSE users: +root:~# cd /etc/rc.d/init.d root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i @@ -1538,44 +1733,44 @@ Executing /sbin/conf.d/SuSEconfig.ypclient... Processing index files of all manpages... Finished. -- You also need some scripts to automate startup and shutdown of - the Oracle8i listener. The listener is a name server that allows - your Oracle programs to talk to local and remote databases using - a standard naming convention. It is required for Intermedia Text - and full site search. - ++ You also need some scripts to automate startup and shutdown of + the Oracle8i listener. The listener is a name server that allows + your Oracle programs to talk to local and remote databases using + a standard naming convention. It is required for Intermedia Text + and full site search. + -- Download these three scripts into - +/tmp -+ Download these three scripts into + -/tmp +- -- startlsnr.txt -+ ++ startlsnr.txt +- stoplsnr.txt -+ stoplsnr.txt +- listener8i.txt -+ listener8i.txt +- Now issue the following commands (still as - +root ). -+ Now issue the following commands (still as + -root ). ++ root:~# su - oracle oracle:~$ cp /tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr oracle:~$ cp /tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr @@ -1586,12 +1781,12 @@ root:~# cd /etc/rc.d/init.d root:/etc/rc.d/init.d# chmod 700 listener8i -- Test the listener automation by running the following commands - and checking the output. - ++ Test the listener automation by running the following commands + and checking the output. + -+ root:/etc/rc.d/init.d# ./listener8i stop Oracle 8i listener start/stop Shutting down Listener for 8i: @@ -1635,18 +1830,18 @@ ora8 has 1 service handler(s) The command completed successfully -- This test will verify that the listener is operating - normally. Login into the database using the listener naming - convention. - ++ This test will verify that the listener is operating + normally. Login into the database using the listener naming + convention. + -- +sqlplus -username/password/@SID + -sqlplus +username/password/@SID + root:~# su - oracle oracle:~$ sqlplus system/alexisahunk@ora8 @@ -1660,25 +1855,25 @@ oracle:~$ exit root:~# -- -RedHat users: -- Now run -chkconfig on the -listener8i script. -+ + RedHat users: ++ Now run +chkconfig on the +listener8i script. +root:~# cd /etc/rc.d/init.d/ root:/etc/rc.d/init.d# chkconfig --add listener8i root:/etc/rc.d/init.d# chkconfig --list listener8i listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off -Debian users: -- Now run -update-rc.d on the -listener8i script. -+ Debian users: ++ Now run +update-rc.d on the +listener8i script. +root:~# update-rc.d listener8i defaults 21 19 Adding system startup for /etc/init.d/listener8i ... /etc/rc0.d/K19listener8i -> ../init.d/listener8i @@ -1688,93 +1883,93 @@ /etc/rc3.d/S21listener8i -> ../init.d/listener8i /etc/rc4.d/S21listener8i -> ../init.d/listener8i /etc/rc5.d/S21listener8i -> ../init.d/listener8i -- Test the automation - ++ Test the automation + -- As a final test, reboot your computer and make sure Oracle comes - up. You can do this by typing - ++ As a final test, reboot your computer and make sure Oracle comes + up. You can do this by typing + -+ root:~# /sbin/shutdown -r -t 0 now -- Log back in and ensure that Oracle started automatically. - ++ Log back in and ensure that Oracle started automatically. + -+ joeuser:~$ su - oracle oracle:~$ sqlplus system/alexisahunk@ora8 SQL> exit -- Congratulations, your installation of Oracle 8.1.7 is - complete. - ++ Congratulations, your installation of Oracle 8.1.7 is + complete. + - Troubleshooting Oracle Dates +Troubleshooting Oracle Dates -- Oracle has an internal representation for storing the data based on - the number of seconds elapsed since some date. However, for the - purposes of inputing dates into Oracle and getting them back out, - Oracle needs to be told to use a specific date format. By default, it - uses an Oracle-specific format which isn't copacetic. You want - Oracle to use the ANSI-compliant date format which is of form - +'YYYY-MM-DD' . -+ Oracle has an internal representation for storing the data based on + the number of seconds elapsed since some date. However, for the + purposes of inputing dates into Oracle and getting them back out, + Oracle needs to be told to use a specific date format. By default, it + uses an Oracle-specific format which isn't copacetic. You want + Oracle to use the ANSI-compliant date format which is of form + -'YYYY-MM-DD' . +- To fix this, you should include the following line in - +$ORACLE_HOME/dbs/init SID .ora - or for the default case, -$ORACLE_HOME/dbs/initora8.ora -+ To fix this, you should include the following line in + -$ORACLE_HOME/dbs/init SID .ora + or for the default case, +$ORACLE_HOME/dbs/initora8.ora ++ nls_date_format = "YYYY-MM-DD" -- You test whether this solved the problem by firing up - +sqlplus and typing: -+ You test whether this solved the problem by firing up + -sqlplus and typing: ++ SQL> select sysdate from dual; -- You should see back a date like - +2000-06-02 . If some of the date is - chopped off, i.e. like2000-06-0 , - everything is still fine. The problem here is that -sqlplus is simply truncating the - output. You can fix this by typing: -+ You should see back a date like + -2000-06-02 . If some of the date is + chopped off, i.e. like2000-06-0 , + everything is still fine. The problem here is that +sqlplus is simply truncating the + output. You can fix this by typing: ++ SQL> column sysdate format a15 SQL> select sysdate from dual; -- If the date does not conform to this format, double-check that you - included the necessary line in the init scripts. If it still - isn't working, make sure that you have restarted the database - since adding the line: - ++ If the date does not conform to this format, double-check that you + included the necessary line in the init scripts. If it still + isn't working, make sure that you have restarted the database + since adding the line: + --nsadmin:~$ svrmgrl + +joeuser:~$ svrmgrl SVRMGR> connect internal Connected. SVRMGR> shutdown @@ -1784,132 +1979,132 @@ SVRMGR> startup ORACLE instance started. -- If you're sure that you have restarted the database since adding - the line, check your initialization scripts. Make sure that the - following line is not included: - ++ If you're sure that you have restarted the database since adding + the line, check your initialization scripts. Make sure that the + following line is not included: + -+ export nls_lang = american -- Setting this environment variable will override the date - setting. Either delete this line and login again or add the following - entry to your login scripts +after the -nls_lang line: -+ Setting this environment variable will override the date + setting. Either delete this line and login again or add the following + entry to your login scripts -after the +nls_lang line: ++ export nls_date_format = 'YYYY-MM-DD' -- Log back in again. If adding the - +nls_date_format line doesn't - help, you can ask for advice in ourOpenACS forum . -+ Log back in again. If adding the + nls_date_format line doesn't + help, you can ask for advice in ourOpenACS forum . +- Useful Procedures +Useful Procedures -- + + -- Dropping a tablespace - ++ ++ Dropping a tablespace + -- -- Run sqlplus as the dba: - ++ + Run sqlplus as the dba: + -+ oracle:~$ sqlplus system/changeme -- To drop a user and all of the tables and data owned by that - user: - ++ To drop a user and all of the tables and data owned by that + user: + -+ SQL> drop user -oracle_user_name cascade;- To drop the tablespace: This will delete everything in the - tablespace overriding any referential integrity - constraints. Run this command only if you want to clean out - your database entirely. - -+ + To drop the tablespace: This will delete everything in the + tablespace overriding any referential integrity + constraints. Run this command only if you want to clean out + your database entirely. + +SQL> drop tablespace -table_space_name including contents cascade constraints;- For more information on Oracle, please consult the +documentation . -+ For more information on Oracle, please consult the documentation . +- Defaults +Defaults -We used the following defaults while installing Oracle. +We used the following defaults while installing Oracle. -- - - +-
- +Variable -Value -Reason -+ ++ + -+
+ - -Variable +Value +Reason +-
- -ORACLE_HOME -/ora8/m01/app/oracle/product/8.1.7 -This is the default Oracle installation directory. --
- -ORACLE_SERVICE -ora8 -The service name is a domain-qualified identifier for - your Oracle server. --
- -ORACLE_SID -ora8 -This is an identifier for your Oracle server. --
+ +ORACLE_OWNER -oracle -The user who owns all of the oracle files. -+
+ +ORACLE_HOME +/ora8/m01/app/oracle/product/8.1.7 +This is the default Oracle installation directory. ++
+ +ORACLE_SERVICE +ora8 +The service name is a domain-qualified identifier for + your Oracle server. ++
+ +ORACLE_SID +ora8 +This is an identifier for your Oracle server. ++
-ORACLE_OWNER +oracle +The user who owns all of the oracle files. +-
- -ORACLE_GROUP -dba -The special oracle group. Users in the dba group are - authorized to do a -connect - internal within -svrmgrl to gain full system - access to the Oracle system.+
+ +ORACLE_GROUP +dba +The special oracle group. Users in the dba group are + authorized to do a +connect + internal within +svrmgrl to gain full system + access to the Oracle system.($Id$) + This was written for ACS and has @@ -89,17 +90,25 @@not yet - been updated for OpenACS. (Note: AOLServer is no longer - supporting Windows - it may be possible to run AOLServer under -Cygwin , but I haven't - seen any success reports yet). Another alternative is to use John - Sequeira'sOasis VM , which is basically a fully working OpenACS &version; system that you load intoVMware . +-
recent kernel Currently version 2.2.19 or - greater is the standard requirement. Some people are using 2.4.x - (2.4.16) kernels. +recent kernel + ++ + Version 2.2.22 or greater is the standard requirement. I used + version 2.4.19 for this guide. + + -
@@ -113,19 +122,10 @@bash -Bash is the standard Linux shell. - We assume you are using bash for these instructions. If you're - not using bash, then you will need to substitute your shell's - conventions for setting environment variables when appropriate. + bash ++ + Bash is the standard Linux shell and we assume you are using + bash for these instructions. If not, you will need to + substitute your shell's conventions for setting environment + variables when appropriate. + -
- -perl (and perl-suid) -- A few parts of the ACS require -perl to work correctly. - (Debian users:apt-get install - perl-suid )|
@@ -162,88 +198,158 @@GNU Make (3.76.1 or better) - PostgreSQL and AOLServer require gmake to compile. Note that - on some linux distributions, GNU Make is simply named + PostgreSQL and AOLserver require gmake to compile. Note that + on most linux distributions, GNU Make is simply named make and there is nogmake , whereas on BSD distributions,make and @@ -145,12 +145,48 @@|
+libxml2 - OpenACS &version; stores queries in XML files, so libxml2 is used to - parse these files. (Debian users: apt-get - install libxml2-dev ) + + OpenACS &version; stores queries in XML files, so libxml2 is + used to parse these files. (Debian users: +apt-get install libxml2-dev ) ++
+ +daemontools ++ + If you decide to follow our recommendations, you'll need + daemontools installed. We'll explain where to get it when you + need it. + + ++
+ +docbook-xml, docbook-xsl, libxslt, xsltproc ++ + Only needed if you plan to write or edit OpenACS + documentation. (docbook-xml v4.2, docbook-xsl v1.56, libxslt + 1.0.21, xsltproc 1.0.21) + + ++
+a MTA (Mail Transfer Agent) ++ + An MTA is needed for OpenACS to send notifications or handle + incoming mail. Qmail seems to be the most popular choice in + the OpenACS community. Other options include Postfix, Exim + and Sendmail. + + ++ We'll compile stuff in /usr/local/src +- PostgreSQL will go into /usr/local/pgsql + + PostgreSQL will go into +/usr/local/pgsql +- AOLServer will go into /usr/local/aolserver + + AOLServer will go into +/usr/local/aolserver +- The web root will go into /web + + The web root will go into your home directory + (e.g./home/ ) +joeuser /web+ None of these locations are set in stone - they're simply the values that we've chosen. You are free to install your software in other locations, but you'll need to adjust the instructions in this document to point to those locations. + ++ + Note that previous versions of this document recommended using + + +/web for the web root and running + AOLserver as thensadmin user. For + security and compatibility reasons, this is no longer recommended. + ++ + This guide will use joeuser as a + normal user. Substitute your own username wherever you see +joeuser . + +- Linux Install Guides -- Here's a list of some helpful documentation for various OS's - +Linux Install Guides ++ Here's a list of some helpful documentation for various OS's + -- +- Painless Debian - GNU/Linux by Stephen van Egmond -+ ++ Painless Debian + GNU/Linux by Stephen van Egmond +Official - Debian Guide - RedHat Official + Debian Guide -Mandrake SuSE - RedHat + + ++ + Mandrake + ++ + SuSE + +- -Security Information -- Once you get your OS installed, it's imperative that you secure your - installation. As Jon Griffin repeatedly warns us, "No distribution is - secure out of the box." Again, this topic is too big to cover properly - here, so see these links. - +Security Information +- -- - Jon Griffin's notes -- Linux Administrators Security Guide -- Installation - of a Secure Webserver -- +- Others? - + - Securing and Optimizing Linux - version 2.0 + + + + ++ + Jon + Griffin's notes + ++ + Linux Administrators + Security Guide + ++ + Installation + of a Secure Webserver + ++ + Others? + + ($Id$) ($Id$) ACS Events @@ -31,9 +31,9 @@+ - @@ -48,6 +48,7 @@ + Index: openacs-4/packages/acs-events/sql/oracle/upgrade/upgrade-0.1d-0.2d.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-events/sql/oracle/upgrade/upgrade-0.1d-0.2d.sql,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-events/sql/oracle/upgrade/upgrade-0.1d-0.2d.sql 6 Oct 2002 23:43:38 -0000 1.1 +++ openacs-4/packages/acs-events/sql/oracle/upgrade/upgrade-0.1d-0.2d.sql 30 Nov 2002 17:18:37 -0000 1.2 @@ -1,4 +1,6 @@ --- RBM: All this to replace one function - 2002-10-06 +-- @author Vinod Kurup (vinod@kurup.com) +-- @creation-date 2002-10-27 +-- from a bug fix by Deds Castillo create or replace package acs_event as @@ -401,21 +403,13 @@ begin -- get the initial offsets select start_date, end_date into v_one_start_date, v_one_end_date - from time_intervals, timespans, acs_events - where time_intervals.interval_id = timespans.interval_id - and timespans.timespan_id = acs_events.timespan_id - and event_id= recurrence_timespan_edit.event_id; + from time_intervals, timespans, acs_events + where time_intervals.interval_id = timespans.interval_id and + timespans.timespan_id = acs_events.timespan_id and + event_id= recurrence_timespan_edit.event_id; - -- RBM: Converted inneficient query to INNER JOINs (2002-10-06) - -- (select * from time_intervals where interval_id in (select interval_id from timespans where timespan_id in (select timespan_id from acs_events where recurrence_id = (select recurrence_id from acs_events where event_id = recurrence_timespan_edit.event_id)))) - - FOR v_timespan in - SELECT ti.* - FROM time_intervals ti, timespans t, acs_events ae - WHERE ti.interval_id = t.interval_id - AND t.timespan_id = ae.timespan_id - AND ae.event_id = recurrence_timespan_edit.event_id - + for v_timespan in + (select * from time_intervals where interval_id in (select interval_id from timespans where timespan_id in (select timespan_id from acs_events where recurrence_id = (select recurrence_id from acs_events where event_id = recurrence_timespan_edit.event_id)))) LOOP time_interval.edit(v_timespan.interval_id, v_timespan.start_date + (start_date - v_one_start_date), v_timespan.end_date + (end_date - v_one_end_date)); END LOOP; Index: openacs-4/packages/acs-events/sql/postgresql/upgrade/upgrade-0.1d-0.2d.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-events/sql/postgresql/upgrade/upgrade-0.1d-0.2d.sql,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-events/sql/postgresql/upgrade/upgrade-0.1d-0.2d.sql 6 Oct 2002 23:43:39 -0000 1.2 +++ openacs-4/packages/acs-events/sql/postgresql/upgrade/upgrade-0.1d-0.2d.sql 30 Nov 2002 17:18:48 -0000 1.3 @@ -52,3 +52,34 @@ return p_event_id; END; ' language 'plpgsql'; + + +-- to_interval() now returns 'timespan' not 'interval' + +create or replace function to_interval ( + -- + -- Convert an integer to the specified interval + -- + -- Utility function so we do not have to remember how to escape + -- double quotes when we typecast an integer to an interval + -- + -- @author jowell@jsabino.com + -- + -- @param interval_number Integer to convert to interval + -- @param interval_units Interval units + -- + -- @return interval equivalent of interval_number, in interval_units units + -- + integer, + varchar +) +returns timespan as ' +declare + interval__number alias for $1; + interval__units alias for $2; +begin + + -- We should probably do unit checking at some point + return ('''''''' || interval__number || '' '' || interval__units || '''''''')::timespan; + +end;' language 'plpgsql'; Index: openacs-4/packages/acs-kernel/acs-kernel.info =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-kernel/acs-kernel.info,v diff -u -N -r1.18 -r1.19 --- openacs-4/packages/acs-kernel/acs-kernel.info 24 Oct 2002 21:05:10 -0000 1.18 +++ openacs-4/packages/acs-kernel/acs-kernel.info 30 Nov 2002 17:18:57 -0000 1.19 @@ -7,17 +7,17 @@ t t -+ oracle postgresql Don Baccus Routines and data models providing the foundation for OpenACS-based Web services. -2002-10-24 +2002-10-27 OpenACS -+ @@ -82,6 +82,7 @@ + @@ -137,6 +138,7 @@ + @@ -149,45 +151,45 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + t t -+ oracle postgresql John Prevost Vinod Kurup +John Prevost General messaging system, mark II -2002-05-15 +2002-10-27 OpenACS Provides generic message services, with email sending. -+ @@ -33,12 +33,14 @@ + + Index: openacs-4/packages/acs-mail/sql/oracle/upgrade/upgrade-4.5-4.6.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-mail/sql/oracle/upgrade/upgrade-4.5-4.6.sql,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-mail/sql/oracle/upgrade/upgrade-4.5-4.6.sql 30 Nov 2002 17:19:52 -0000 1.2 @@ -0,0 +1,6 @@ +-- @author Vinod Kurup vinod@kurup.com +-- @creation-date 2002-10-08 + +update acs_object_types +set table_name = 'ACS_MESSAGES_QUEUE_MESSAGES' +where lower(object_type) = 'acs_mail_queue_message'; Index: openacs-4/packages/acs-mail/sql/postgresql/upgrade/upgrade-4.5-4.6.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-mail/sql/postgresql/upgrade/upgrade-4.5-4.6.sql,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-mail/sql/postgresql/upgrade/upgrade-4.5-4.6.sql 30 Nov 2002 17:20:09 -0000 1.2 @@ -0,0 +1,6 @@ +-- @author Vinod Kurup vinod@kurup.com +-- @creation-date 2002-10-08 + +update acs_object_types +set table_name = 'acs_mail_queue_messages' +where lower(object_type) = 'acs_mail_queue_message'; Index: openacs-4/packages/acs-person/acs-person.info =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-person/Attic/acs-person.info,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-person/acs-person.info 26 Sep 2002 03:22:03 -0000 1.2 +++ openacs-4/packages/acs-person/acs-person.info 30 Nov 2002 17:20:25 -0000 1.3 @@ -9,7 +9,6 @@ - oracle postgresql Jon Griffin Index: openacs-4/packages/acs-person/sql/oracle/acs-person-sc-create.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-person/sql/oracle/Attic/acs-person-sc-create.sql,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-person/sql/oracle/acs-person-sc-create.sql 26 Sep 2002 03:32:07 -0000 1.1 +++ openacs-4/packages/acs-person/sql/oracle/acs-person-sc-create.sql 30 Nov 2002 17:20:43 -0000 1.2 @@ -6,15 +6,15 @@ select acs_sc_impl_alias__new( 'FtsContentProvider', -- impl_contract_name - 'contact', -- impl_name + 'acs_person', -- impl_name 'datasource', -- impl_operation_name 'acs_persons__datasource', -- impl_alias 'TCL' -- impl_pl ); -select acs_sc_impl_alias__new( +select acs_sc_impl_alias.new( 'FtsContentProvider', -- impl_contract_name - 'contact', -- impl_name + 'acs_person', -- impl_name 'url', -- impl_operation_name 'acs_persons__url', -- impl_alias 'TCL' -- impl_pl @@ -24,21 +24,21 @@ create function acs_persons__itrg () returns opaque as ' begin - perform search_observer__enqueue(new.contact_id,''INSERT''); + perform search_observer__enqueue(new.acs_person_id,''INSERT''); return new; end;' language 'plpgsql'; create function acs_persons__dtrg () returns opaque as ' begin - perform search_observer__enqueue(old.contact_id,''DELETE''); + perform search_observer__enqueue(old.acs_person_id,''DELETE''); return old; end;' language 'plpgsql'; create function acs_persons__utrg () returns opaque as ' begin - perform search_observer__enqueue(old.contact_id,''UPDATE''); + perform search_observer__enqueue(old.acs_person_id,''UPDATE''); return old; end;' language 'plpgsql'; Index: openacs-4/packages/acs-person/sql/postgresql/acs-person-sc-create.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-person/sql/postgresql/Attic/acs-person-sc-create.sql,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-person/sql/postgresql/acs-person-sc-create.sql 24 Sep 2002 05:24:47 -0000 1.1 +++ openacs-4/packages/acs-person/sql/postgresql/acs-person-sc-create.sql 30 Nov 2002 17:21:00 -0000 1.2 @@ -6,15 +6,15 @@ select acs_sc_impl_alias__new( 'FtsContentProvider', -- impl_contract_name - 'contact', -- impl_name + 'acs_person', -- impl_name 'datasource', -- impl_operation_name 'acs_persons__datasource', -- impl_alias 'TCL' -- impl_pl ); select acs_sc_impl_alias__new( 'FtsContentProvider', -- impl_contract_name - 'contact', -- impl_name + 'acs_person', -- impl_name 'url', -- impl_operation_name 'acs_persons__url', -- impl_alias 'TCL' -- impl_pl @@ -24,21 +24,21 @@ create function acs_persons__itrg () returns opaque as ' begin - perform search_observer__enqueue(new.contact_id,''INSERT''); + perform search_observer__enqueue(new.acs_person_id,''INSERT''); return new; end;' language 'plpgsql'; create function acs_persons__dtrg () returns opaque as ' begin - perform search_observer__enqueue(old.contact_id,''DELETE''); + perform search_observer__enqueue(old.acs_person_id,''DELETE''); return old; end;' language 'plpgsql'; create function acs_persons__utrg () returns opaque as ' begin - perform search_observer__enqueue(old.contact_id,''UPDATE''); + perform search_observer__enqueue(old.acs_person_id,''UPDATE''); return old; end;' language 'plpgsql'; @@ -51,8 +51,3 @@ create trigger acs_persons__utrg after update on acs_persons for each row execute procedure acs_persons__utrg (); - - - - - Index: openacs-4/packages/acs-service-contract/acs-service-contract.info =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/acs-service-contract.info,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-service-contract/acs-service-contract.info 17 Aug 2002 17:42:45 -0000 1.8 +++ openacs-4/packages/acs-service-contract/acs-service-contract.info 30 Nov 2002 17:21:13 -0000 1.9 @@ -7,18 +7,18 @@t t -+ oracle postgresql Kapil Thangavelu Neophytos Demetriou +Kapil Thangavelu Allows different packages to communicate via defined contracts -2002-08-17 +2002-10-27 OpenACS -+ @@ -37,6 +37,7 @@ + @@ -51,6 +52,7 @@ + @@ -61,6 +63,8 @@ + + Index: openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5-4.5.1.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5-4.5.1.sql,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5-4.5.1.sql 20 Aug 2002 21:05:04 -0000 1.2 +++ openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5-4.5.1.sql 30 Nov 2002 17:21:23 -0000 1.3 @@ -221,7 +221,7 @@ show errors -- UPGRADE ISSUE 2 --- acs_sc_binding.exists_p was broken on Oracle if you installed +-- acs_sc_binding.exists_p was broken on Oracle if you -- tested a binding for which the implementation was installed, but the -- contract wasn't. @@ -336,3 +336,4 @@ end acs_sc_binding; / show errors + Index: openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5.1-4.6.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5.1-4.6.sql,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5.1-4.6.sql 30 Nov 2002 17:21:23 -0000 1.2 @@ -0,0 +1,19 @@ +-- packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5.1-4.6.sql +-- +-- @author Vinod Kurup (vinod@kurup.com) +-- @creation_date 2002-10-08 +-- +-- $Id: upgrade-4.5.1-4.6.sql,v 1.2 2002/11/30 17:21:23 jeffd Exp $ + +-- UPGRADE ISSUE #1 +-- add timestamp datatype + +declare + v_msg_type_id acs_sc_msg_types.msg_type_id%TYPE; +begin + if acs_sc_msg_type.get_id('timestamp') is null then + v_msg_type_id := acs_sc_msg_type.new('timestamp',''); + end if; +end; +/ +show errors Index: openacs-4/packages/acs-service-contract/sql/postgresql/upgrade/upgrade-4.5.1-4.6.sql =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-service-contract/sql/postgresql/upgrade/upgrade-4.5.1-4.6.sql,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-service-contract/sql/postgresql/upgrade/upgrade-4.5.1-4.6.sql 30 Nov 2002 17:21:34 -0000 1.2 @@ -0,0 +1,47 @@ +-- packages/acs-service-contract/sql/oracle/upgrade/upgrade-4.5-4.5.1.sql +-- +-- @author Vinod Kurup (vinod@kurup.com) +-- @creation_date 2002-08-14 +-- +-- $Id: upgrade-4.5.1-4.6.sql,v 1.2 2002/11/30 17:21:34 jeffd Exp $ + +-- UPGRADE ISSUE #1 +-- add more verbose error message + +create or replace function acs_sc_binding__new(integer,integer) +returns integer as ' +declare + p_contract_id alias for $1; + p_impl_id alias for $2; + v_contract_name varchar; + v_impl_name varchar; + v_count integer; +begin + + v_contract_name := acs_sc_contract__get_name(p_contract_id); + v_impl_name := acs_sc_impl__get_name(p_impl_id); + + select count(*) into v_count + from acs_sc_operations + where contract_id = p_contract_id + and operation_name not in (select impl_operation_name + from acs_sc_impl_aliases + where impl_contract_name = v_contract_name + and impl_id = p_impl_id); + + if v_count > 0 then + raise exception ''Binding of % to % failed since certain operations are not implemented.'', v_contract_name, v_impl_name; + end if; + + insert into acs_sc_bindings ( + contract_id, + impl_id + ) values ( + p_contract_id, + p_impl_id + ); + + return 0; + +end;' language 'plpgsql'; + Index: openacs-4/packages/acs-subsite/acs-subsite.info =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-subsite/acs-subsite.info,v diff -u -N -r1.37 -r1.38 --- openacs-4/packages/acs-subsite/acs-subsite.info 24 Oct 2002 21:34:04 -0000 1.37 +++ openacs-4/packages/acs-subsite/acs-subsite.info 30 Nov 2002 17:21:53 -0000 1.38 @@ -590,8 +590,6 @@ - - @@ -646,7 +644,7 @@ - +