David King

Xythos officially supports Linux, Solaris, and Windows, but I got their Enterprise Documentation Suite it to run under FreeBSD without much trouble at all. Most of these instructions are applicable to any other type of install. I assume that you have both Java and Postgres already installed, although you can substitute your favourite RDBMS

Installation

Installing Xythos is a matter of setting up two databases (xythos and files) in your favourite RDBMS, unzipping xythos-W.X.Y.Z.zip into a directory, downloading a JDBC driver, running an installer, and and starting Xythos. I used Postgres 8.1 for the database, which I already had installed (note that Xythos will want you to have done initdb with --no-locale or --locale=C). First, as your postgres user,

    createuser -S -D -R xythos

    createdb -E unicode -O xythos xythos
    createdb -E unicode -O xythos files

    createlang plpgsql xythos
    createlang plpgsql files
  

    alter user xythos with password 'xythos_password';
  

Xythos uses two databases, one for its Global Schema, which is where it puts all of its configuration information, and one for its Document Store, which is where it puts all of its files initially (although we'll change this later), and all of the metadata associated with those files. You can have multiple Document Stores, but we're only going to set up one.

We're almost ready do to the install, but first go get Postgres' JDBC driver for your version of Postgres.

Then as root I did

    mkdir -p /usr/local/xythos
    cd /usr/local/xythos
    unzip ~/xythos5.0.24.1.zip # of course, substitute your version and the location of your ZIP file here
  

    ln -s server-* server
    ln -s wfs-* wfs
  

So now run the installer.

    cd /usr/local/xythos/wfs
    java -jar installxythos.jar
  

Then the installer (in step 3) wants to know about how I'm going to set up my servlet container. First I'm going to do an install of the default embedded Tomcat, then I'm going to move that into my own Tomcat instance that's managed by my operating system packaging system (FreeBSD Ports) so that it can receive automatic updates. So for now when it asks "Would you like to configure the shipped servlet container now?", I say Yes.

      Configure Bundled Servlet Container

    1 - Set JDK Home
        [/usr/local/jdk1.5.0]
    2 - Set Admin web application username
        [admin]
    3 - Set Admin web application realm
        [WFSAdmin@ketralnis.com]
    4 - Set Admin web application password
    5 - Set HTTP port
        [8080]
    6 - Toggle auto-reload of changes from other servers or API programs
        [disabled]
    7 - Set maximum Java heap size (mb)
        [default]
    8 - Discard servlet container changes and return
    9 - Save servlet container changes and return

Tomcat, the servlet engine that's embedded with Xythos, uses a "Shutdown port," which is used to indicate to Tomcat that it should shut down. This listens on the Localhost address. I had to change the shutdown port in my /usr/local/xythos/server/conf/server.xml because I already had a Tomcat instance running on this machine. Unless you want to run two copies of Tomcat, you can skip this step.

You can start your new Xythos server by running /usr/local/xythos/server/bin/startup.sh if you want quick feedback, but I'm going to set up an init.d script. In my case, it goes in /usr/local/etc/rc.d, but on RedHat Linux it will go in /etc/init.d, and will require a chkconfig --add wfs; chkconfig wfs on. If you're using another operating system you'll need to find out how to start Xythos with with the system

So here's the script that I'll use. I've left some Linux-specific stuff in there that doesn't hurt FreeBSD so that you can reuse it on Linux. You might have to add things like an LD_PRELOAD_PATH if you're running the Verity filters or something.
#!/bin/sh # chkconfig: 345 86 15 # description: Tomcat servlet engine # processname: tomcat prog="Tomcat" PATH=/sbin:/bin:/usr/bin:/usr/sbin export JAVA_HOME=/usr/local/java export CATALINA_HOME=/usr/local/xythos/server RETVAL=0 start() { echo -n "Starting $prog: " # Server must run as root in order to bind to privileged ports (you can remove this check if you don't want to run it as root and don't want to bind to a low port) if [ `whoami` != "root" ]; then echo echo $0 start must be run as root to bind to privileged ports. exit -1 fi # start the show.. "$CATALINA_HOME/bin/startup.sh" RETVAL=$? } stop() { echo -n "Stopping $prog: " $CATALINA_HOME/bin/shutdown.sh RETVAL=$? } restart() { stop sleep 2 start } # See how we were called. case "$1" in start) start ;; stop) stop ;; restart) restart ;; *) echo $"Usage: $0 {start|stop|restart}" RETVAL=1 esac exit $RETVAL
You'll want to do a chmod u+x wfs. You can now run it with ./wfs start.

So how ever you've started it, you should now have a running instance of Xythos.

Probably the first thing that you'll want to do is move your files into an external document store. Pull up the Xythos Admin (http://xythosserver:port/xythosadmin/ and log in with whatever admin username you used (by default admin) and whatever password you gave in the installer. Go to Server Administration, then Storage, then External Storage Locations. Under "Unix Storage Locations", type the name of the directory where you want your files to go; make sure it's writeable by the Tomcat user. Click "Add external storage location", then go to "Document Stores" and then under "Storage Settings for '1'" change the Storage Location to your new external document store. Scroll down and hit "Save Changes", then scroll back down and click "Migrate Data Now". Now your external document store is set up.

Now let's move our Xythos logs somewhere sane in Server Administration > Logging. I assume that you can figure this one out.

LDAP/OpenDirectory

So now the basic installation stuff is done, let's start working some magic. First, I want to authenticate against LDAP. Shut down Xythos, and run the installer (cd /usr/local/xythos/wfs && java -jar installxythos.jar). For me, enabling LDAP is option 8. It will ask you if you're sure, say yes if you are. Exit the installer.

Start Xythos up again. Pull up the Xythos Admin, and go to Server Administration, then User Model. The User Model Wizard will come up and ask what type of LDAP you want (Active Directory or Other). In my case, I want OpenDirectory, which is "Other LDAP Implementation (not Active Directory)". Click "next". Here are my settings:

• Directory Server Host: myopendirectoryserver.mydomain.com
• Directory Server Port: 389
• Connect Using SSL: No
• Application User Distinguished name: uid=diradmin,cn=users,dc=mydomain,dc=com
• Application Password: *******
• Default User Domain DN: cn=users,dc=mydomain,dc=com

Since OpenDirectory's LDAP isn't like everyone else's, we need to change some object class stuff. Go to "Object Classes" under "User Model" and change these:

• Object Class Attribute Name: objectClass
• User Object Class: inetorgperson
• Group Object Class: posixGroup

Now you'll need to go to "User & Group Attributes". Change these settings under "Required User Attributes and Settings" and "Optional User Attributes and Settings"

• Username: uid
• Display Name: cn
• Email Address: EMailAddress

And Save Changes

Note! Xythos does not currently support OpenDirectory's LDAP groups. I hear they are working on it, but for now if you want groups you'll have to either add your own multi-value attribute containing the full DN of each member to each group (easily scripted) and tell Xythos to use that attribute, or just use Xythos groups. I'm going the latter until they add support for OpenDirectory groups.

I want my users to see a friendlier name than my domain when they are logging in, so you can skip this step if you don't care Under User Model, go to Directory Service Domains, and click on the Properties icon next to your domain, and change "Domain Name", and "Domain Description" to something nicer looking.

You should now be able to verify that LDAP is working by going to "USERS & GROUPS" > "User Admin" and hitting "Find" with the default wildcards in the search fields. If LDAP is working, your users should show up. Don't log in as one of them until you get a user template that you like.

User templates

I use New User Templates, and I assume here that you've set them up before

Decide where you want your home directories, and use the admin to create that directory. I use /users. I set its owner to nobody and its quota and bandwidth to be unlimited. I like its permissions to be that "Users with accounts" can read it.

I like to set up a user template with the following properties:

• Default Template: Yes
• Home Directory Parent Path: /users
• Time Zone: (your time zone, or that of the majority of your users)
• Directory Template:Create new directory template

If you're satisfied, save that and try to log in as a user. When I was doing the install for this walk-through, it worked first try, but that's the first time it's all worked first try, so your mileage may vary :)

Moving Xythos into a new application server

I already have Tomcat installed from FreeBSD ports, and that Tomcat automatically gets upgrades and security updates. In its current state, the Tomcat that comes embedded with Xythos won't receive these updates. In addition, the servlets running under my Tomcat and the Xythos Tomcat are running in separate JVMs, occupying enormous amounts of memory. So I'm going to move Xythos into the other Tomcat instance. This isn't for the faint of heart!

So here's a list of what I did, I'll come back in here in a day or two and actually say what they mean. Email me if you want me to do it sooner.

1. copied /usr/local/xythos/*/webapps to /usr/local/www/xythos
2. copied entire chunks of server.xml into new server.xml
3. turned off /scanner
4. changed path="" to path="/xythos"
5. Should have renamed ROOT but that's okay
6. copied /usr/local/xythos/common to /usr/local/www/xythos/common
7. used the EAR file (describe) to get required JARs, put them in /usr/local/www/xythos/common
8. copied /usr/local/xythos/custom to /usr/local/www/xythos (custom/lib contains the JDBC driver, custom contains any customisations)
9. did a vimdiff on catalina.properties to determine classpath differences
10. added classpath stuff
11. copied /usr/local/xythos/xythos.properties to /usr/local/www/xythos
12. set new permissions on /usr/local/www/xythos
13. <Realm className="org.apache.catalina.realm.MemoryRealm"
14. Added /xythos to my outgoing/incoming WebDAV URLs