Hey gang,
I've been doing my best to figure out SiteGroups and write a document
explaining it's usage but I haven't gotten it to work.
I'm sure it's just me but could someone please tell me if they've
succesfully implemented SiteGroups. If yes, then I really need your
help. I've attached the current version of the SiteGroups document. I can
also provide a step-by-step report of my efforts to implement SiteGroups,
in order to determine what I'm doing wrong.
Upon solving my oversite, I will rewrite the document and refer to
you as The Great One. :)
Ron
<!-- $Id: basicdevel.sgml,v 1.6 2000/04/11 01:46:24 rparker Exp $ -->
<chapter id="basicdevel">
<title>Basic Development</title>
<simpara>TODO: write me</simpara>
<sect1>
<title>Hosts and Styles</title>
<simpara>
TODO: write me
</simpara>
</sect1>
<sect1>
<title>SiteGroup, Virtual Database Environment</title>
<simpara>
The SiteGroup tool separates Midgard's single MySQL database into multiple
virtual databases and manages administrative privileges. For example, there
are 10 distinct user-level Hosts in an installation. Two of these, vmuc.com
and vmucentertainment.com, are owned by Henry, but he has no connection
with the other eight. Henri must have read and write privileges over the
database records for his two Hosts, while being denied access to the other
Hosts. Because many Midgard Host records can belong to one SiteGroup (SG),
Henri is able to access both his Hosts.
</simpara>
<simpara>
When logging into a Midgard administration interface, users specify the
level of access and the SG records they're requesting by providing
their username, a delimiter, and SG name, i.e. henri+vmug.com.[1] The
delimiters indicate the level of access that the user is requesting.
Specifying the "+" delimiter in "herni+vmug.com" tells Midgard to search
for a normal user named henri, while the "!" indicates superuser and "*"
represents root. If the vmuc.com and vmucentertainment.com records belong
to SG vmug.com and henri is a member of vmug.com then logging in as
henri+vmug.com, will grant access to the database records for both those
Hosts.
</simpara>
<simpara>
In addition to segregating records into virtual databases, SGs protects
records which are readable for all users. In the default installation,
shared records include the administration interface and the vmuc.com Host.
These records are distinguished by assigning their ownership to SG 0 (SG0)
which permits read-only access and enables their availability during all
authenticated sessions. Consider the Midgard Administration site, while
many administrative users authenticate with write privileges, they can't be
allowed to edit the shared administration site records. By marking records
as belonging to SG0, you eliminate the opportunity to alter the records
while they are made readable to all users. Additionally, when upgrades to
the shared interface are made, they immediately become available to every
client.
</simpara>
<simpara>
Sitegroups also reduces the number of persistant database connections. When
storing Hosts in distinct databases, each Apache handler process opens a
persistant connection to every database. It is not unusual to have 20-30
handler processes active per host. Which when multiplied by the number of
clients, surpasses the default MySQL configuration for 100 connections.
</simpara>
<sect2>
<title>Configuration, Administration of SiteGroups</title>
<simpara>
To build a SiteGroup-aware Midgard, you must reconfigure and recompile
all the Midgard packages. This also applies when moving from a
SiteGroup-aware installation to a non-SiteGroup installation. To include
SiteGroups, you must specifiy "--with-sitegroups" during the
configuration of libmidgard. The configure programs for mod_midgard and
midgard-php will probe libmidgard to see if SiteGroups are enabled and
respond accordingly.
</simpara>
<simpara>
After rebuilding Midgard, you must update the database to include the new
"sitegroup" table and the new "sitegroup" columns within the existing
tables. The file sitegroup.sql, which is part of the midgard-lib package,
performs these additions. From a command prompt, issue the following:
</simpara>
<programlisting>
mysql -u midgard -p midgard < sitegroups.sql
</programlisting>
<simpara>
After adding the "sitegroup" table and columns to the Midgard database,
the new table is empty and the fields for every record are set to 0. So,
all records in the database default to the shared, read-only SG0. Because
there's is no easy way to migrate existing records into the new SiteGroup
environment, we recommend you begin by applying SiteGroups to new records.
</simpara>
<simpara>
Until the administration interface is updated to include SiteGroup
functionality, slated for 1.4, the creation of new SiteGroups must be
done manually. We'll build "sitegroupname.com" from the MySQL command
line tool by issueing:
</simpara>
<programlisting>
INSERT INTO sitegroup (name) VALUES('sitegroupname.com');
</programlisting>
<simpara>
A query of the SiteGroup table shows sitegroupname.com as an entrty. From
the mysql command line tool, issue:
</simpara>
<programlisting>
select * from sitegroup;
</programlisting>
<simpara>
+----+--------------------------+------------+
| id | name | admingroup |
+----+-----------------------+---------------+
| 1 | sitegroupname.com | 3 |
+----+-----------------------+---------------+
</simpara>
<simpara>
After adding sitegroupname.com to the "sitegroup" table, we build the
new Host, Group and Person records which will be associated with
sitegroupname.com. It's important to realize that associating a new host
with an existing SiteGroup requires you to log into sitegroupname.com as
root. This is done by, logging into the administration site as
'rootusername*sitegroupname.com'. After logging in, create:
</simpara>
<itemizedlist>
<listitem>
<simpara>
a new host "sitegroupname.com"
</simpara>
</listitem>
<listitem>
<simpara>
the new Admin group, "sitegroupname.com" reduces confusion
</simpara>
</listitem>
<listitem>
<simpara>
a new person, "Henri"
</simpara>
</listitem>
</itemizedlist>
<!--add him to the group-->
<simpara>
After logging into the administration site as the root user for
sitegroupname.com and creating the new host, admin group, and person,
records, you'll need to edit the person record by selecting "User account"
and assigning a login name and password. For simplicity, we assign and use
the username "admin" throughout this document. Afterwards, your person
will be able to log into the administration site as
"admin+sitegroupname.com" and authenticate by using Henri's password.
Henri has administrative privileges for all the records which belong to
sitegroup.com.
</simpara>
<simpara>
While logged in as 'rootusername*sitegroupname.com' you'll need to create
New toplevel topic within the Content administration interface and then
set the Owner to "sitegroupname.com." Ownership of the "Default style for
sitegroupname.com" and the Host records must all be set to
sitegroupname.com. Failed attempts at writing to records for users are
likely a result of incorrect ownership of these files.
</simpara>
</sect2>
<sect2>
<title>Using SiteGroups</title>
<simpara>
There are basically two types of users, normal and root, with several
authentication options which are specified through the use of delimiters
and the inclusion or exclusion of a SiteGroup name. The delimiters
indicate the user level that's being requested and what host records to
make available during the session. The "admin*sitegroupname.com" or
"admin*" conventions are used with one of three delimiters. The "*"
delimiter indicates a request for root administrative priveleges and
access to all SiteGroups, while "!" indicates administrative priveleges
within the supplied SiteGroup name and finally "+" which is used to
request access to the host that the user is a member of.
</simpara>
<simpara>
Normal users:
</simpara>
<itemizedlist>
<listitem>
<simpara>
Normal user sessions are initiated with the
"username+sitegroupname" convention. These sessions include
read priveleges to SG0 records which includes the
Administration and vmuc.com sites.
<simpara>
<simpara>
Because Henry is as a member of the vmuc.com administrator
group and the vmuc.com records belong in SiteGroup vmug.com,
when he logs in with "admin+vmug.com" he has write priveleges
for the vmuc.com records while being restricted to viewing SG0
and vmuc.com records.
</listitem>
</itemizedlist>
<simpara>
Root Administrators:
</simpara>
<itemizedlist>
<listitem>
<simpara>
Root sessions require either the "*" or "!" delimiters when
accessing records which are optionally followed by a
sitegroupname. If a sitegroupname isn't indicated, the host
SiteGroup is picked; for SG0 sites this puts the root user in
SG0 for the duration of the session. When enabling SiteGroups
on an existing Midgard database, all the records within the
database are assigned to SG0 by default. So, "admin*" with the
Midgard root passwd builds a session where every record in the
database is viewable.
</simpara>
</listitem>
<listitem>
<simpara>
Only root users, members of SG0, can remain in SG0 while
logged in. Any valid user can log into the Administration site;
however, they are restricted to reading documents which are
owned by the SiteGroup they signed in under, and can only
commit edits to the files they own.
</simpara>
</listitem>
</itemizedlist>
<simpara>
Summary of delimiters:
</simpara>
<itemizedlist>
<listitem>
<simpara>
'*' means full access, and you'll see all records of all
sitegroups, even when logging in as rootuser#sitegroupname.
</simpara>
</listitem>
<listitem>
<simpara>
'!' means you want to log in as an admin user for the given
sitegroup. Your view will be restricted to SG0 records and
records of the given sitegroup. Modification of records will
be limited to the sitegroup.
</simpara>
</listitem>
<listitem>
<simpara>
'$' I am root and I want a user view
</simpara>
</listitem>
<listitem>
<simpara>
'+' means you want to be a normal user in the given sitegroup.
You will not be able to change anything since you are not an
actual member of any owner group within that sitegroup.
</simpara>
</listitem>
</itemizedlist>
<simpara>
Notes:
In our example, the "g" in vmug.com is simply a naming convention to
distinguish the host name from the SG name.
</simpara>
<!--> > > '*' I am root and want a full view of the system
> > > '!' I am root and want an admin view
> > > '$' I am root and I want a user view
> > > '+' I am an admin/user
-->
</sect2>
</sect1>
<sect1>
<title>PHP basics</title>
<simpara>
TODO: write me
</simpara>
</sect1>
<sect1>
<title>Midgard functions</title>
<simpara>
TODO: write me
</simpara>
</sect1>
<sect1>
<title>Syntax additions</title>
<simpara>
Midgard adds a new language construct to PHP which allows you to
include the value of a variable in HTML with the use of
an <literal>?> echo $var; <?</literal> construct. You can
now simply use
<literal>&(variablename);</literal>
directly in HTML. Note the absence of the "$".
Object variables that would normally be
accessed in PHP code as <literal>$object->field</literal>
can be inserted as &(object.field);.
</simpara>
<simpara>
The way the value is inserted can be specified by adding a
modifier after the variable name: &(variable:modifier);.
The modifiers are:
</simpara>
<table>
<title>Inline variable display modifiers</title>
<tgroup cols="2">
<thead>
<row>
<entry>Modifier</entry>
<entry>effect</entry>
</row>
</thead>
<tbody>
<row>
<entry>h</entry>
<entry>add value as HTML. This will escape " to
&quot;, & to &amp;, < to &lt;,
> to &gt;.
Everything between [< and >] is
added verbatim with the [< and >] dropped. PHP
code embedded in such a section is executed.
</entry>
</row>
<row>
<entry>p</entry>
<entry>add value as PHP (HTML embedding allowed). This
will escape " to &quot;, & to &amp;,
< to &lt;, > to &gt;.
Everything between [< and >] is
added verbatim with the [< and >] dropped. PHP
code embedded in such a section is executed.
</entry>
</row>
<row>
<entry>H</entry>
<entry>add value as HTML. Everything is included
verbatim.</entry>
</row>
<row>
<entry>f</entry>
<entry>
add value as formatted text. The plain text input is
formatted as HTML on the fly. Lines starting with
"-" will be transformed to unnumbered lists,
<p> will be added between paragraphs delimited by
an empty line.
Everything between [< and >] is
added verbatim with the [< and >] dropped. PHP
code embedded in such a section is executed.
</entry>
</row>
<row>
<entry>F</entry>
<entry>
add value as formatted text. The plain text input is
formatted as HTML on the fly. Lines starting with
"-" will be transformed to unnumbered lists,
<p> will be added between paragraphs delimited
by an empty line. Additionally, lines after an empty
line with less than 10 words that do not end in a
period are formatted as <h2>
Everything between [< and >] is
added verbatim with the [< and >] dropped. PHP
code embedded in such a section is executed.
</entry>
</row>
<row>
<entry>u</entry>
<entry>
add the value urlencoded, replacing non-safe URI
characters with their %code equivalents.
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1>
<title>Example site</title>
<simpara>
TODO: write me
</simpara>
</sect1>
</chapter>
<!--NOTES, delete from this point
> B/ (don't kick me ;) what is the secret recipee to transform a user member
> of say SG1 (not sg0) in a root user for this group ? it's really not very
> clear in the release notes. also i read somewhere u changed the suffixes for
> login of such users...
There's root users and admin users. Root users are admin of all groups.
Root users must be in SG0 and the record that nakes them member of group 0
must also be in SG0.
For a user to be admin user of SG1 the user must be in SG1, the membership
and group record must be in SG1, and the group must be marked as
admingroup in the sitegroup table entry for the sitegroup.
<!-- EEH
The secret recipe: create a group 'admins' (no special name but convenient) in
the sitegroup,
set the 'admingroup' field of the sitegroup to the id of this group, and make
the user member
of this group 'admin'. Presto.
-->
<simpara>
Since populating a SiteGroup is much like populating a database, we
suggest filling it from scratch instead of moving content over from
other sitegroups whenever possible.
</simpara>
<!--This is out of place and has already been covered but..<simpara>
SiteGroups allow certain users to be super-user[s], or root
users, which grants them full read-write access to all sitegroups. These
users must be members of SG 0 and their member records must be in SG 0.
</simpara>-->
-->
--
This is The Midgard Project's mailing list. For more information,
please visit the project's web site at http://www.midgard-project.org
To unsubscribe the list, send an empty email message to address
[EMAIL PROTECTED]
