[BlueOnyx:13070] Re: How to script...

[Michael Stauber]

Hi James,

> Hey guys – I’d like to do a tiny bit of automation, and I expect one of
> you can tell me how.  Here’s what I would like to do for an existing site:
> 
> -          Create an associated non-administrative user account.
> 
> -          Create a forwarder to an external email address.
> 
> Alternatively:
> 
> -          If the user already exists, simply change existing forwarder
> to specified address.
> 
> 
> Seems like it should be pretty simple, but I don’t know the ins and outs
> of what BlueOnyx needs to keep track of where...

It's not overly complicated, but yes: There is a certain learning curve.

How I would program this also depends on if this ought to be a web
application, or a command line tool. If it's from within AdmServ and
handled by a GUI page, it needs to be coded in PHP.

If it's supposed to be a command line tool, then it's better done in Perl.

It's also good to look at existing examples of code that deals with user
management or email management.

For some PHP examples:

/usr/sausalito/ui/web/base/user/personalEmail.php
/usr/sausalito/ui/web/base/user/personalEmailHandler.php
/usr/sausalito/ui/web/base/user/userMod.php
/usr/sausalito/ui/web/base/user/userModHandler.php

For a Perl example dealing with user related queries:

/usr/sausalito/handlers/base/user/handle_user.pl

However, Perl handlers of BlueOnyx are a bad example. By default a
handler can only be executed by AdmServ.

Constructors on the other hand can be executed by user "root". The
difference between a handler and a constructor is this:

Handler:
$cce->connectfd();

Constructor:
$cce->connectuds();

All the GUI data is stored in the CODB database. You can use the GUI and
can run a "tail -f /var/log/messages" to see the database transactions
that your GUI modifications perform. Then you can play with these
queries via "/usr/sausalito/bin/cceclient", which is a command line tool
to manipulate CODB.

When starting "cceclient", type "help" to see the available commands.

Examples:

[root at 5108r user]# /usr/sausalito/bin/cceclient
100 CSCP/0.80
200 READY
help
ADMIN suspend | resume : suspend or resume write operations
AUTH <username> <passwd> : Authenticate as a user
AUTHKEY <username> <sessionid> : Attempt to resume a session
BEGIN : Begin a transaction
BYE [SUCCESS | FAIL | DEFER] : Disconnect immediately, indicating exit
status
CLASSES : List all classes
CREATE <class> [<key>=<value> ...] : Create a new instance of the
specified class
DESTROY <oid> : Destroy the specified object
ENDKEY : Expire the current sessionid now
FIND <class> [<key>=<value> ...] : Find instances of the specified
class, matching given criteria
GET <oid>[.<namespace>] : Get a list of key=value pairs for the
specified object
HELP : Show help about all commands currently available
NAMES <oid> | <class> : List available namespaces for an object or class
SET <oid>[.<namespace>] [<key>=<value> ...] : Set all listed keys to
listed values in the specified object
WHOAMI : Get the object id of the currently logged in user

So that's the help text.

find User name = "mstauber"
201 OK

Reports back with "OK" and no results. So that user doesn't exist on
that box,

find User name = "admin"
104 OBJECT 8
201 OK

OK, user "admin" exists and his info is in CODB object #8. Let us take a
look at it:

get 8
102 DATA NAMESPACE = ""
102 DATA fullName =
"\357\277\275\357\277\275\357\277\275\333\277\357\277\275"
102 DATA capabilities = ""
102 DATA ftpDisabled = "0"
102 DATA capLevels = ""
102 DATA CLASSVER = "1.0"
102 DATA crypt_password = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
102 DATA sortName = ""
102 DATA CLASS = "User"
102 DATA systemAdministrator = "1"
102 DATA emailDisabled = "0"
102 DATA md5_password = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
102 DATA shell = ""
102 DATA volume = "/home"
102 DATA description = ""
102 DATA desc_readonly = "0"
102 DATA uiRights = ""
102 DATA name = "admin"
102 DATA password = ""
102 DATA site = ""
102 DATA stylePreference = "BlueOnyx"
102 DATA OID = "8"
102 DATA enabled = "1"
102 DATA ui_enabled = "1"
102 DATA localePreference = "en_US"
102 DATA noFileCheck = "0"
201 OK

And Object can also have subclasses. The "User" object for example has
the sub-class "Email". Let us take a look at that for user "admin":

get 8 . Email
102 DATA aliases = ""
102 DATA forwardEnable = "0"
102 DATA NAMESPACE = "Email"
102 DATA vacationMsg = "Test: \366\344\374\326\304\334\337"
102 DATA CLASSVER = "1.1"
102 DATA forwardSave = "0"
102 DATA forwardEmail = ""
102 DATA vacationMsgStart = "1332247620"
102 DATA vacationMsgStop = "1332247620"
102 DATA vacationOn = "0"
201 OK

That user has a vacation message set. But "vacationOn" is "0", so
vacation messages are not enabled. "forwardEnable" is "0", too. So no
email forwarding enabled. To change that, we could do a SET transaction:

set 8 . Email forwardEnable = "1" forwardEmail = "username at otheremmail.com"

That would turn forwarding on and would set the forwarding address to
"username at otheremmail.com".

We can also use "CREATE" to create new objects.

Both from PHP (within AdmServ and if logged into the GUI as "admin") and
from Perl (if running the script as "root" from the command line) we
have the full might of CODB at our finger tips and can use "FIND",
"FINDX", "GET", "SET", "CREATE" and "DESTROY" to find and to manipulate
CODB database objects.

A transaction to the database will trigger all the corresponding
functions that would usually happen when you use the regular GUI to
create, update or delete a users info. So using "DESTROY" on a "USER"
object would delete the users account from the system, would remove his
home directory, email aliases and would restart Sendmail so that the
usertable and aliasses are rehashed. If you "DESTROY" A "Vsite" object,
then that will delete all users of the site, their emails, the
webspaces, DNS entries (if auto-created), email aliases and what not. In
the end the corresponding services (Apache, Sendmail, Proftpd, Bind
nameserver) would get restarted as well.

Lastly, the CMU shell tools also provide a limited set of capabilities
to create, delete and modify sites and users from the command line:

For that see:

/usr/sbin/cadduser
/usr/sbin/caddvsite
/usr/sbin/cdeluser
/usr/sbin/cdelvsite
/usr/sbin/clistuser
/usr/sbin/clistvsite
/usr/sbin/cmoduser
/usr/sbin/cmodvsite

Call any of them with the "--help" parameter to see the usage examples
and available command line options.

-- 
With best regards

Michael Stauber