Please login or register to participate.
Wiki Page

Upgrade 3.x Community Appliance


This how-to describes how to upgrade your appliance from an old 3.x version to a new one. has an automatic forward migration of content that will take your content and upgrade it so that everything in the new version works properly with it.

All of this guide will focus on working with the webmin appliance management interface. This is a web based management interface to be used for managing the Computer where server is installed.

Go to Webmin interface

Navigate to https://<your sitehost OR IP address>:10000

You will have to accept the https warning that your browser will show because the administration interface is protected with HTTPS but the certificate is self-signed. This is normal. Once the login screen appears, login with the root user whose password you set up during the CD install.


Once you login, you will see the appliance status dashboard screen.


Do NOT upgrade the Webmin interface even if the link to do so is visible and present for you on the dashboard. This link will be removed in the future. Only install upgrades exactly as shown below. Clicking the link will product unpredictable results.

Navigate to System -> Software Packages

This is the web based software package manager that is provided with the Web based appliance management interface. This is where you will find and install new upgrades on to the system.



Check if an upgrade is available

Change Upgrade Mode to Normal and choose Yes for Only show which packages would be updated.


This will show you a simulation of what would happen if you actually performed the upgrade, you'll get to see what all packages will be installed. If "cynin" is one of them, there's a version update available for you! If you look closer you will see what version and interation of the package will be installed.


Wait! Let's take a manual backup of the data file first

Navigate to Others -> File Manager. This is a Java applet which will let you see and manage the full directory structure and files on your server.


Navigate to /home/cynin/buildout/var/filestorage as shown, and select the Data.fs file and press the Save button. This will let you download the Data.fs file from your server. This is the main Data file for your installation. It's the most important file on the system and if you need to manually restore your site on a new computer this is the only file you will need.


This is important! You must backup your Data.fs file prior to installing the upgrade. The upgrade installation will attempt an automatic backup as well, but if this fails for any reason, or something goes drastically wrong, you can use the thus downloaded Data.fs file for fully resurrecting your site.

Back to the Software Packages screen. Let's install for real, this time

Go back to System -> Software Packages and choose Normal upgrade mode and this time, choose No for "Only show" radio button and press the Upgrade now button.



The update will start to download and you can sit back and watch the progress.


There will be a lot of scroll and there will be a lot of syntax errors, warnings and other oddities shown.
This is normal. Yes, I know, this is weird. :)

But really it's not that bad. Plus the extra verbose log lets us help you if / when there's a problem.
In case you're worrying, or you need to troubleshoot problems by comparing with what the "normal" case is, consult this output dump for reference installation.

If you're more comfortable with the linux command line console you can do this upgrade by typing out the usual at the # prompt:
apt-get update && apt-get upgrade


After an agonizingly long wait, you should see the above screen telling you the package was installed successfully. This is good. Now you get to test if your upgrade was received and all is fine. Do this by navigating to your normal site URL, which will remain the same http://<your sitehost or IP address/ and verifying that the upgrade did indeed "take". :)

Comments (42)
rstewart Nov 12, 2009 06:26 PM
This worked great. Thanks for the instructions. I fixed a couple typos as well (I left a not in the change log with specifics).
dhiraj Nov 12, 2009 06:36 PM
Awesome work, thanks! And yes, I've got to get someone to proof-read the absolute crap I sometimes type, especially in the wee hours. :)

Please feel free to edit when you see places where you can contribute, just put a changelog note, there's no need to even add a regular comment. We can always find out what the changes were, using the version diffing.
rstewart Nov 12, 2009 06:40 PM
The two errors I found were very minor, which is better than I can say for my work in the wee hours of the morning.

If you ever have specific proof-reading needs, let me know.
h0rr0r Nov 13, 2009 11:37 AM
I can't seem to go to my Webmin page. Is there anything that I need to run or install first?
dhiraj Nov 13, 2009 01:18 PM
Well no it should have not changed at all. What happened exactly? Tell us more about your situation. You were on 3.0.4? And you upgraded to 3.0.5? And CyninWebmin doesn't "come up" - does that mean that you're getting a Could not connect to server, or are you getting a 404 not found, or some error is coming?

How did you upgrade? Like above, or you did it via apt-get update && apt-get upgrade?

Also did you click the ugprade webmin button by mistake?

Are you sure you're typing https and not http ?
Correct URL: https://<sitedomain or IP address>:10000
holey_foot Nov 13, 2009 02:32 PM
The instructions were perfect and the upgrade went well. Only problem now is that the Spaces I had created prior to the upgrade do not display. The folders are still there and the content accessible; however, they don't display in the Spaces area.
dhiraj Nov 13, 2009 02:40 PM
Please post a screenshot of this, if you can. (Just add a new image in the Sandbox and put the link here).

There could be several reasons / problems why this could/would happen and a screenshot will tell us exactly what you're seeing.

Are you logged out and halfway-partially through the Anonymous setup guide, by any chance? Just a thought. :)
dhiraj Nov 13, 2009 05:09 PM
It's looking like the search catalog index is out-of-sync.

Test this: Go to one of the Spaces that's not appearing in the navigation UI and edit and save it, no need to change anything there if you don't want to. Navigate one more time (to anywhere) and see if the Space shows up. If the edited Space now shows up, you've found the problem.

Login with the admin user (no, not siteadmin) and go to this URL:
http://<yoursitedomain or IP Address>:8080/cynin/portal_catalog/manage_catalogAdvanced and press the Clear and Rebuild button.

This re-indexes all items in your site, and will take a *long* time if you've got a lot of items. Wait.
When it get's done, hit Ctrl + F5 on your site home and it should show all the missing stuff.
holey_foot Nov 13, 2009 05:51 PM
Perfect, that fixed it! Thanks.
siteadmin Nov 13, 2009 06:05 PM
Cool. Hmm... this is normally automatically done by the reinstall of the site policy. You are seeing v3.0.5 in the bottom in the footer, right? What version did you upgrade from? Was it older than 3.0.4?

Is anybody else having this problem?
h0rr0r Nov 14, 2009 04:01 AM
I am now in 3.0.4 and I wish to upgrade to 3.0.5. When I type https://<mysitename>:10000 I get the message unable to connect to server.
h0rr0r Nov 14, 2009 08:06 PM
I am getting this message now when I tried to upgrade Cynin.

Site Error

An error was encountered while publishing this resource.

Resource not found
Sorry, the requested resource does not exist.

Check the URL and try again.

Resource: csi:10000 GET

Troubleshooting Suggestions

    * The URL may be incorrect.
    * The parameters passed to this resource may be incorrect.
    * A resource that this resource relies on may be encountering an error.

For more detailed information about the error, please refer to the error log.

If the error persists please contact the site maintainer. Thank you for your patience.
dhiraj Nov 14, 2009 08:10 PM
Hmmm....? It looks like something went wrong with the cyninwebmin installation. Did you click the upgrade webmin button on the dashboard at any after you logged in, by mistake?

Anyways, go to the command line console for your appliance and login with the root user, and try this:

apt-get update
apt-get purge webmin
apt-get purge cyninwebmin
apt-get install cyninwebmin
h0rr0r Nov 15, 2009 04:24 AM
When I reach the apt-get purge cyninwebmin it says that it couldn't find cyninwebmin application. Anyway, when I tried apt-get install cyninwebmin, it says that it couldn't locate the cyninwebmin. Do I have to enable something at the repository?
dhiraj Nov 15, 2009 07:27 AM
Hmm.... this is strange! It *is* looking like the Cynapse updates repository is disabled if cyninwebmin cannot be found at all.
Try this on command line console with root logged in:
cd /etc/apt
nano sources.list

This opens up the command-line editor for the apt sources. Check if has a # prepended before it. Sometimes, especially during the system installation from the CD, if the apt repository cannot be contacted, it gets automatically disabled by the system.
If you find the # on the line, remove it (del key), press Ctrl + X, press y and press enter to save and exit.

Next you do the apt-get update again and try to apt-get install cyninwebmin again.
h0rr0r Nov 15, 2009 09:10 AM
I coudn't find that line in my sources list. Can I just add it in?
dhiraj Nov 15, 2009 09:13 AM
No. There's something wrong here about my assumptions.
Are you using the ISO CD to install or are you doing buildout?
Please paste the contents of the file into a comment here, or add it as a file in sandbox area and put a link to it, here.

You cannot *not* have that entry at all in your sources.list if you installed from the CD.
h0rr0r Nov 15, 2009 09:21 AM
Oh... I did not installed it from the ISO CD file last time. I used the snapshot file that I downloaded last time.
h0rr0r Nov 15, 2009 09:26 AM
# deb cdrom:[Ubuntu-Server 9.04 _Jaunty Jackalope_ - Release i386 (20090421.1)]/ jaunty main restricted

# deb cdrom:[Ubuntu-Server 9.04 _Jaunty Jackalope_ - Release i386 (20090421.1)]/ jaunty main restricted
# See for how to upgrade to
# newer versions of the distribution.

deb jaunty main restricted
deb-src jaunty main restricted

## Major bug fix updates produced after the final release of the
## distribution.
deb jaunty-updates main restricted
deb-src jaunty-updates main restricted

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team. Also, please note that software in universe WILL NOT receive any
## review or updates from the Ubuntu security team.
deb jaunty universe
deb-src jaunty universe
deb jaunty-updates universe
deb-src jaunty-updates universe

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubuntu
## team, and may not be under a free licence. Please satisfy yourself as to
## your rights to use the software. Also, please note that software in
## multiverse WILL NOT receive any review or updates from the Ubuntu
## security team.
deb jaunty multiverse
deb-src jaunty multiverse
deb jaunty-updates multiverse
deb-src jaunty-updates multiverse

## Uncomment the following two lines to add software from the 'backports'
## repository.
## N.B. software from this repository may not have been tested as
## extensively as that contained in the main release, although it includes
## newer versions of some applications which may provide useful features.

# deb cdrom:[Ubuntu-Server 9.04 _Jaunty Jackalope_ - Release i386 (20090$
# See for how to upgrade to
# newer versions of the distribution.

deb jaunty main restricted
deb-src jaunty main restricted

## Major bug fix updates produced after the final release of the
## distribution.
deb jaunty-updates main restricted
deb-src jaunty-updates main restric$

## N.B. software from this repository is ENTIRELY UNSUPPORTED by the Ubu$
## team. Also, please note that software in universe WILL NOT receive any
## review or updates from the Ubuntu security team.
deb jaunty universe
## Also, please note that software in backports WILL NOT receive any review
## or updates from the Ubuntu security team.
# deb jaunty-backports main restricted universe multiverse
# deb-src jaunty-backports main restricted universe multiverse

## Uncomment the following two lines to add software from Canonical's
## 'partner' repository.
## This software is not part of Ubuntu, but is offered by Canonical and the
## respective vendors as a service to Ubuntu users.
deb jaunty partner
deb-src jaunty partner

deb jaunty-security main restricted
deb-src jaunty-security main restricted
deb jaunty-security universe
deb-src jaunty-security universe
deb jaunty-security multiverse
deb-src jaunty-security multiverse

h0rr0r Nov 15, 2009 09:26 AM
That's the content of my sources.list file.
dhiraj Nov 15, 2009 10:56 AM
Well no, then auto-upgrade using webmin cannot work for you. You're going to have to follow manual upgrade procudure:

Download the new source snapshot, extract it in a new folder, and copy the Data.fs from your existing current buildout into the same location (var/filestorage) in your new buildout - make the folder chain if it doesn't exist already. Take care to stop your existing buildout so that users cannot add data to it to while you're upgrading.

Do your buildout again in the location, and then re-install ubify.policy product from portal_quickinstaller screen, this will automatically migrate all your existing data and you can use this new location from then on.
h0rr0r Nov 15, 2009 03:00 PM
What do you mean by make the folder chain?
dhiraj Nov 15, 2009 03:05 PM
Well, when you first checkout or unzip the source snapshot, it won't have a var folder and a filestorage folder under that - these are created by the bootstrap/buildout when you first run it.

So when you try to put the Data.fs I thought you might get confused as to where to put it. Looks like I went the other way and confused you more, instead of helping you out. :)
h0rr0r Nov 15, 2009 03:23 PM
Ok. Thanks alot! Anyway, when after I upgrade it to 3.0.5 does it comes with the Webmin?
dhiraj Nov 15, 2009 03:38 PM

Short Answer: If you're a developer or need to have buildout for adding/testing other products -> do a buildout from source snapshot, like you're doing. No Webmin. No auto-upgrades.

If you're not interested in any of the above, then you're better off installing from the CD as you get peace-of-mind, automatic upgrades and much less headaches. ============================

Long Answer:
Webmin is for administering the appliance CD that we package. What you're using is the snapshot source which only has the buildout. This is intended for the developer audience who are already comfortable with the command line way.

The apt-get repository based upgrading of is currently only available for installations that have been installed from the ISO CD (through Webmin or command line, the operation is the same). If you try it on any other OS, the results are completely unpredictable as we ourselves have not attempted this yet.

If you're interested in just Webmin itself, it is available for all linux distros, just google it. Note that getting Webmin on your OS does not mean that you'll be able to upgrade that way, you need to have the updates repository installed, and that is definitely not recommended for any other OS than the one we're packaging on the CD. Note that even if you're running Debian 5, adding the apt-get repo URL directly on an existing Debian 5 box and apt-get installing it *may* have unpredictable results, we're making assumptions because we're adding all the required packages in the CD installation. In short, we've not tested with this scenario either.

Even in buildout source scenario, your data migration forward path will be retained, you'll just manually have to backup your Data.fs file, manually copy it over to the new buildout that you'll make for the new source tree, do the buildout and then use the new one if everything's working fine.
h0rr0r Nov 20, 2009 08:08 AM
I have installed an ISO version into another server and I have another server that is being installed using the snapshot. Can copy the Data.fs from the snapshot server and put it into the ISO server?
dhiraj Nov 20, 2009 09:06 AM
Yes, it will work.

On the source server:
1. Make sure to shutdown the instance (./bin/instance stop) before you start copying the Data.fs file.

On the target server:
0. Shut down the daemon first (/etc/init.d/cynin stop) and then delete or move all files out from the /home/cynin/buildout/var/filestorage directory.
1. After you copy the Data.fs file to /home/cynin/buildout/var/filestorage remember to check the ownership on the file. It *must* belong to userid cynin, groupid anything you want, usually root. chown command is your friend. :)
2. Start the daemon (/etc/init.d/cynin start) after you copy the file, look in /home/cynin/buildout/var/log/instance.log for problems with startup - there will usually be a lot of Translation catalog errors reported when you move a Data.fs file, this is *normal*. Just make sure the instance started up fine from the log.
3. At this point your Cynin instance should already be up and running fine. If you encounter problems with out-of-sync stuff like Spaces not appearing, try clearing and rebuilding portal_catalog in the Advanced tab in ZMI. Another problem solver is reinstalling the ubify.policy product.
4. Another point to note is that complete state is maintained in the Data.fs file, all users, passwords, content, configuration, *everything* is in it.
5. Backup before. Backup after. Backup often.

Do let us know how it went. :)
h0rr0r Nov 20, 2009 10:56 AM
I tried using the webmin to copy the Data.fs file to the target server but it just couldn't replace the file in there.
dhiraj Nov 20, 2009 11:30 AM
Hmm.... did you shutdown the daemon instance first? Secondly, you should move or delete all the existing files in var/filestorage folder on the target server and then put the new file in.

When you say "couldn't replace the file" -> What happens, exactly? If there's an error, what's the error?
h0rr0r Nov 23, 2009 05:45 AM
Well, I did stop the daemon, and I deleted the Data.fs file in the target server. When I tried using the Webmin to upload the backup Data.fs from the old server, the Webmin File Manager does not show the file that I uploaded even after I refreshed it a few times.

Anyway, I managed to transfer the file using the command prompt. Now my Spaces doesn't show up even after I tried doing the clearing and rebuilding the portal_catalog. Is there any other way to do it? We managed to login using the old ID's so I guess the Data.fs file is ok.
dhiraj Nov 23, 2009 08:10 AM
When you say "old logins" you mean the logins that you had prior to replacing the Data.fs file, in the old system? If so, then your Data.fs file has simply not gotten transferred, or something else is wrong.

As I was saying earlier, *all* state is maintained within the Data.fs file, if you replace it, you will no longer be able to login with "old" logins (unless they're existing in the new Data.fs file as well).

If you're comfortable with the command line, then you should probably use the command line methods to move the Data.fs around. I need to see the situation or you to give us more details for me to be able to add more ideas on what could be wrong.

From what you're saying, it's looking like the new Data.fs file has simply not gotten loaded at all!
h0rr0r Nov 30, 2009 08:59 AM
Ok. I think I got the ownership of the files wrong. I got it working now. Anyway, why before I copy the Data.fs file to the target server, the cynin is running at this URL http://<IP Address of Server> but after I copy over the Data.fs, the URL changes to http://<IP Address of Server>:8080/cynin

How could I change it back to just the IP address without the ports and the folder name behind?
dhiraj Nov 30, 2009 10:14 AM buildout will typically run at port 8080. What you need to do is run a reverse proxy in front of it, like if you see in the ISO CD we're having an Apache HTTPD VirtualHost site that proxies to the buildout at 8080.
h0rr0r Nov 30, 2009 10:28 AM
How do I go about it? How can I create one just like yours?
dhiraj Nov 30, 2009 11:35 AM
Yes, in fact if you take the file from /etc/apache2/conf.d from the machine created from ISO CD and add it in the same place in your target machine it should work straight off.
h0rr0r Nov 30, 2009 11:47 AM
When I replace the Data.fs file, does that file being replaced also? I don't quite understand here. What I am doing here right now is that I have build a server using ISO CD and when I copy over the Data.fs file, the URL changes to the one that need to key in the ports.
dhiraj Nov 30, 2009 12:05 PM
Let's call the server you built using the ISO cd as "source" and the new server you're building using buildout as "target".

You have to delete or move out *all* the files in /home/cynin/buildout/var/filestorage first on target, and *then* copy over the Data.fs file from source.

Copy the cynin file from .... /etc/apache2/conf.d/cynin on the source server to the the same place on the target and restart your apache2 server (/etc/init.d/apache2 restart). If you don't have apache2 on the target, install it using apt-get or whatever you prefer.
h0rr0r Nov 30, 2009 12:23 PM
Hi Dhiraj,

Actually, I have a server (source) build from the snapshot which is 3.0.4 and right now I have another server which I installed using the ISO CD (target) which is 3.0.5.

On my source server, I used to key in URL http://<IP Address of source>/csi in order for me to access the cynin webpage.

On the target server, before I copy the Data.fs, I could use my Firefox to browse to the cynin page by just keying in http://<IP Address of target> to make sure everything is all right.

Right now, I want to transfer the Data.fs from source to target. I stop the instance. I did delete all the files in /home/cynin/buildout/var/filestorage and I copy in the Data.fs from source server to target server. Changed the owner of the Data.fs to cynin. Start back the instance.

Now when I use my Firefox again, when I key in the URL http://<IP Address or target> I will get a Site Error Message like below.
Site Error

An error was encountered while publishing this resource.

Resource not found
Sorry, the requested resource does not exist.

Check the URL and try again.

Resource: cynin GET

Troubleshooting Suggestions

    * The URL may be incorrect.
    * The parameters passed to this resource may be incorrect.
    * A resource that this resource relies on may be encountering an error.

For more detailed information about the error, please refer to the error log.

If the error persists please contact the site maintainer. Thank you for your patience.

But on the other hand, when I key in the URL of http://<IP Address of target>:8080/csi I could see the page already. What I need right now is that I don't want to key in the port number and also the /csi thingy just like when I newly installed from ISO CD.

dhiraj Nov 30, 2009 12:46 PM
Taking a Data.fs file from a 3.0.5 to a 3.0.4 will definitely cause unpredictable results, but this not the main cause of your problem.

It looks like you setup the 3.0.4 target with a different sitename than cynin, as per your description it looks like target had a site named "csi".

For the site name change, you will have to change your existing rewrite URLs in your apache or whatever you were using as reverse proxy. You can easily determine this by CDing to /etc/apache2/sites-available and seeing what files are there using the ls and the cat commands.

You should make a new buildout at any path, using svn tag for 3.0.5 and use that as target instead of the current 3.0.4 buildout that you have. If you made your current target using svn checkout, then you can use the "svn sw" command to update the source, try svn help sw if you don't know how to do this.

"svn info" at your target's buildout root will tell you if you have made it using checkout or give you a message like "not a working copy" or something similar.

The new checkout url for 3.0.5 is so use this to svn switch to the new source code base - this is *very* important for the migration to complete properly.
h0rr0r Nov 30, 2009 03:10 PM
Hmmmm..... I tried to look into the /etc/apache2/sites-available/cynin.conf file. I edited these 2 lines.
RewriteCond %{HTTP_HOST} ^(.+)
    RewriteRule ^(.*)/(.+)\.ics(.*)$ http://<Server IP Address>:8080/csi/VirtualHostBase/http/%1:80/cynin/VirtualHostRoot/$1/@@icalendar.ics [L,P]
    RewriteCond %{HTTP_HOST} ^(.+)
    RewriteRule ^(.*) http://<Server IP Address>:8080/csi/VirtualHostBase/http/%1:80/cynin/VirtualHostRoot/$1 [L,P]

And it works! I can just key in the URL http://<Server IP Address> and it will direct me to the page but the URL will change automatically to http://<Server IP Address>:8080/csi.

That is ok with me as long as my users don't have to key in the port and also that /csi thingy.

Anyway, right now when we go to main page, it says that I do not have priviledges to see the page unless I login. Is that public access page? How do I share it to user without login?
bindella May 07, 2010 04:18 PM
I know that I should not klick on the "Upgrade Webmin Now", but what about the next "Install Update Now" to upgrade the "LDAP Users and Groups" fix?
Since I,m useing LDAP it could be usefull?