Monday Feb 28, 2011

GlassFish 3.1: Automatic Domain Backup

In a prior post I wrote about the commands we reintroduced in GlassFish 3.1 which allows administrators to manually backup and restore a GlassFish domain.    There is more to it than that.   We also introduced support for scheduled automatic backups of a domain.   This new feature is only available in Oracle GlassFish Server.   For those who are not familiar with Oracle GlassFish Server this is our commercial distribution of the GlassFish Server Open Source Edition. Oracle GlassFish Server is backed by support from Oracle and is distributed with GlassFish Server Control which is a collection of additional features which enhance the functionality of Oracle GlassFish Server.

Here is a short summary of how it works.    It is pretty simple.   You basically create a new object called a Backup Configuration (this named object describes the type of backup you want to perform).   You associate the Backup Configuration with a named Schedule.    Multiple Backup Configurations can exists (some enabled, some not) and they can point to the same schedule or different schedules.

The Backup Config has the following attributes:

  • Name
  • Schedule
  • Enabled (Boolean)
  • Backup Location
  • Recycle Limit
  • Live Backup (Boolean)
  • Backup Type (Full or Config Only)

The Name is the name of the Backup Configuration and you can create as many of these as you like.   Each Backup Configuration must be associated with an existing schedule.    The product ships with three pre-defined schedules: daily, weekly and monthly but you can create more or modify the existing schedules.  A Backup Configuration is enabled by default but you can change the Enabled attribute to temporarily turn off a scheduled backup.   If you do not specify a backup location the backups (in the form of zip files) are maintained in the domain directory (backups subdirectory).    The recycle limit allows you to control the number of prior backups to maintain.   The default is 25.   When that number is reached older backups are deleted as new ones are added.     The live backup option allows the backup to be performed on the DAS without suspending it (more on that in a future posting).    Finally you can control whether a full backup is performed, which is the entire domain directory (sans existing backup files), or just the domain's configuration.

A good practice might be to perform a full backup of the domain once or twice a month and perform configuration only backups daily.

Here's a quick example using the asadmin CLI to create these two automatic backups.   You can also perform the same operation using the GlassFish Console which I will demonstrate in a different blog entry.

First I'll list the existing schedules:

% asadmin list-schedules --long
daily          0       0       0     \*            \*             \*      \*     
weekly         0       0       0     Sun          \*             \*      \*     
monthly        0       0       0     \*            1             \*      \* 
Command list-schedules executed successfully.

So as you can see there are three existing schedules.    The daily schedule defines an event which occurs every day at midnight.  The weekly defines an event to occur every Sunday at midnight and the monthly schedule defines an event to occur on the first day of the month also at midnight. 

I'll create a new backup config to perform our monthly full backup of the domain directory:

% asadmin create-backup-config --schedule monthly --backupdir /tmp/das-backups --recyclelimit 12 d1-full
Command create-backup-config executed successfully.

The above command creates a backup config which is associated with the monthly schedule.  The backups which are created are stored in /tmp/das-backups and I'm using the recyclelimt option to control the number of backups I will maintain (twelve in this case).

The next command:

     % asadmin create-backup-config --schedule daily --backupdir /tmp/das-backups --recyclelimit 30 --configonly d1-config 
     Command create-backup-config executed successfully

creates another backup config which kicks off a backup daily.   This backup config will only backup the contents of the config directory for the domain.    Since this backup config is associated with the daily schedule the backup will occur every day.

It is worth noting that multiple backup configs can reference the same schedule.    They will both get executed at the same time although the order in which they will be executed is not defined.

If you want to see the details of a specific backup config you can use the new list-backup-configs subcommand:

% asadmin list-backup-configs --long d1-config
Name of Backup Config   :d1-config
Auto Backup Enabled     :true
Schedule                :daily
Recycle Limit           :30
Config Only backup      :true
Active Backup Enabled   :false
Backup Directory        :/tmp/das-backups
Last Backup Attempt     :Mon Feb 28 14:05:55 PST 2011
Last Successful Backup  :Mon Feb 28 14:05:55 PST 2011

Schedule Details:
daily  0       0       0     \*            \*             \*      \*     
Command list-backup-configs executed successfully.

The backups will be performed as long as the Domain Administration Server (DAS) is running. When the event is scheduled to occur the DAS will suspend the domain temporarily.   When the domain is suspended any command which would cause the DAS to modify the domain directory is blocked (other commands such as list-clusters are allowed).   This allows the backup to be safely performed.   Once complete the DAS is resumed so that all operations are allowed.

You can use the list-backups command to list available backups.   In this example I'll look at the backups available in the /tmp/backups directory:

% asadmin list-backups --backupdir /tmp/das-backups
CONFIG     USER   BACKUP DATE                   FILENAME                       
d1-config  kasso  Thu Feb 24 00:00:00 PST 2011  
d1-config  kasso  Fri Feb 25 00:00:00 PST 2011  
d1-config  kasso  Sat Feb 26 00:00:00 PST 2011  
d1-config  kasso  Sun Feb 27 00:00:00 PST 2011  
d1-config  kasso  Mon Feb 28 00:00:02 PST 2011  
d1-full    kasso  Wed Feb 23 10:49:47 PST 2011  
Command list-backups executed successfully.

If you wanted to restore the lastest backup of the domain you would stop the domain and then use the restore-domain command:

% asadmin stop-domain
Waiting for the domain to stop ......
Command stop-domain executed successfully.
% asadmin restore-domain --backupdir /tmp/das-backups --backupconfig d1-full domain1
Restored the domain (domain1) to /work/ogs/glassfish3/glassfish/domains/domain1
Command restore-domain executed successfully.

This replaces the contents of the domain directory with the contents of the full backup of the domain. For additional details about creating backup configurations and schedules see the Oracle GlassFish Server 3.1 Administration Guide.

Wednesday Feb 16, 2011

GlassFish 3.1: Backup and recovery commands have been restored

For those familiar with earlier versions of GlassFish you may recall a couple of commands that could be used to backup and restore the DAS:

  •  backup-domain
  •  restore-domain
  •  list-backups

While these commands were available in 2.x they did not make it into v3 or 3.0.1.   They are back in 3.1. 

The backup-domain command will create a zip file that contains the contents of the domains/<domain> directory.   This includes configuration and deployed applications.   This zip file could be used to restore the DAS, retrieve a prior configuration or migrate the DAS to a different system.

The restore-domain command reversed the behavior of backup-domain.   It essentially takes the zip file and restores it to the domain directory.   Pretty simple stuff.   Some details about how the prior versions of these commands worked is captured in the DAS Recovery One Pager.

In 3.1 we made some improvements over the prior implementation.   For example in 2.x the backup file name was called:  where NNNNN is a number (e.g. 00001).  This number is incremented for each backup.   For 3.1 we have changed the backup name to For example:  This makes it easier to manage these files for those cases where you move them to an alternate location away from the domain directory.

Prior to 3.1 the backup would be stored in the domain directory where the backup was created.  It was not possible to specify an alternate location for the backup.   In 3.1 we have added a new --backupdir option to backup-domain so now it is trivial to store the backups outside of the domain directory:

    asadmin backup-domain --backupdir /net/backuphost/domain1 domain1
    Backed up domain1 at Wed Feb 16 15:13:46 PST 2011.
    Command backup-domain executed successfully.

The restore-domain command now allows you to restore to a domain where the name of the domain does not match the domain the backup originated from.    The default behavior is to not allow this to occur but the behavior can be overridden with the --force option.   If the --force option is used the domain name used to create the backup will be used.

Finally we also improved the output of the list-backups command:

    asadmin list-backups
    CONFIG  USER   BACKUP DATE                   FILENAME
            kasso  Wed Feb 16 15:22:18 PST 2011
            kasso  Wed Feb 16 15:22:20 PST 2011
            kasso  Wed Feb 16 15:22:22 PST 2011
            kasso  Wed Feb 16 15:23:06 PST 2011
    Command list-backups executed successfully.

With the --long option more details about the backup can be displayed:

    asadmin list-backups --long
    Description               : domain1 backup created on 2011_02_16 by user kasso
    GlassFish Version         : Oracle GlassFish Server 3.1 (build 43)
    Backup User               : kasso
    Backup Date               : Wed Feb 16 15:22:18 PST 2011
    Domain Name               : domain1
    Backup Type               : full
    Backup Config Name        :  
    Backup Filename (origin)  : /work/ogs/glassfish3/glassfish/domains/domain1/backups/
    Domain Directory          : /work/ogs/glassfish3/glassfish/domains/domain1

The ability to create and managed domain backups for your DAS has been restored in the GlassFish Server Open Source Edition.   The commands with the new enhancements our available now in promoted builds of GlassFish 3.1.


Chris Kasso-Oracle


« February 2011