The art of backup recasted

Let's address this issue once more with the same principles but with different manners. First we will create a local site pod. Then we will backup it to restore it back with precleaning. Finally, we will clone a new site from an existing one. The sample site will be based on a drupal core. It could be as well a joomla, postnuke or xoops core.

To create the site locally, we suppose that it is defined in sifnet_config.php pointed by sifnetconfigfile. The fundamental importance of defining the target site properly, particularly when the sif commands are run with the -f, -v and -x options, is indicated here. If the implications of wrongly defining the target site are by now not yet clear, do loop here.

The running environment, the web server and the database server are in place. The latest version of sifbuilder has been downloaded to a local folder.

Site creation

The following creates the site as defined in sib_drupal47_sif_sif.xml (try to understand why -f -x options are useful and even then do not use them).

> php sifcmd.php sip_build_site --sifpacksdir=../sifbuilder_local/packages
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd501_at_localhost
--siburi=./sibs/sib_drupal47_sif_sif.xml  --dev  -x -f

The sip_build_site is the sif command for the installation of modules or the creation of a complete site. sip_build_site is shorcut by 'b'.

--sifpacksdir indicates where the site packages (core, modules and themes) are downloaded. By storing them outside the sifbuilder folder, updating new versions of sifbuilder will not remove them.

--sifnetconfigfile points to the file hosting the classes describing the target sites referenced by sifnetsite. The sample sifnet_config.php is included in the sifbuilder root folder. It should always be adapted to the local configuration before starting using sifbuilder.

--sifnetsite refers to the class in the sifnetconfigfile with properties the site configuration options typically set during the installation of a new content management site. They coincide with the elements in the sifSiteParams.xml file in the sifbuilder root. Having these options on file permits to refer to each site configuration by name. Wrong setting
of those options may erase a whole system. No need to look for a demonstration.

The --dev option makes installation packages related to development cores or modules be considered during the site generation process

-x may be added to the command to remove the site root and empty the site database before starting the installation. Do that only if you have the possibility of and know how to restore your working environment.

-f may be used to force the execution of the command in non-interactive mode. It can be used and will be used if you are a programmer when you know to be in control of what you are doing.

Site backup

The site may then be backup by:

> php sifcmd.php backup_pod
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd501_at_localhost -f

It is possible to specify the backup file with the --siburi option. if it is not indicated, the tar file is created and timestamped in the folder defined by backup_dir_name in the sifConfigParams, by default siftmp/tmpUpload in the sifbuilder directory. In this case, the backup file is bck_pod_200707120020_sifbuilder_drupal.zip and it contains three files:

The creation of the sql dump is based on standard calls to the database, such as SHOW FIELDS FROM table in mysql, provided by the abstract metabase interface. Since the information received is not exhaustive, there will most probably be some difference between the correct statement and the dumped one. For example,

CREATE TABLE `pn501__admin_module` (
  `pn_amid` int(11) NOT NULL auto_increment,
  `pn_mid` int(11) NOT NULL default '0',
  `pn_cid` int(11) NOT NULL default '0',
  PRIMARY KEY  (`pn_amid`),
  KEY `mid_cid` (`pn_mid`,`pn_cid`),
  KEY `mid` (`pn_mid`)
)

is generated as by sifbuilder:

CREATE TABLE IF NOT EXISTS `pn501__admin_module` (
  `pn_amid` int(11) NOT NULL  auto_increment ,
  `pn_mid` int(11) NOT NULL  default '0',
  `pn_cid` int(11) NOT NULL  default '0',
 PRIMARY KEY (`pn_amid`),
 KEY `pn_mid` (`pn_mid`)
);

Other differences may appear and therefore this technology may sometimes need be complemented with manual intervention or other more targeted tool. In fact, this -that- is the real reason why backup in sifbuilder is an art and not a science.

Site restore

When a site has been backup, the site may then be restored by :

> php sifcmd.php restore_pod
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd501_at_localhost -f -x

The backup restores the sbd501_at_localhost site with the -x option having cleaned the pod before the restore.

Since the site identification is the same (sbd501_at_localhost) the restored site resides normally on the same server than the site of departure.

Summarizing,

1. We have created the local sbd501_at_localhost site as defined in ../sifbuilder_local/sifnet_config.php and declared in sib_drupal47_sif_sif.xml .
2. Then, we have created a timestamped backup zip including the site definition file, the file system tar and the site database sql dump.
3. Then, we have removed the newly created site -by grace of the dangerous -x option in the restore statement-.
4. Finally, the site has been restored because the same site definition has been specified in sifnetsite and because, since no backup uri has been specified, the most recently created backup file has been taken as source.

Clonage of a site

A substantially different operation is the creation of a new site, with the same structure (core, modules, themes) and contents than an existing one but with different configuration (database or database prefix and credentials). This scenario is applicable with there is a need to create a test site mirroring a production site on the same host.

> php sifcmd.php sip_build_site --sifpacksdir=../sifbuilder_local/packages
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd501_at_localhost
--siburi=./sibs/sib_drupal47_sif_sif.xml  --dev  -x -f

If the sbd501_at_localhost was available or has been created as descrbed above, it can be cloned with the following (do it without the -f and -x options first).

> php sifcmd.php clone_pod
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetbcksite=sbd501_at_localhost --sifnetsite=sbd502_at_localhost
drupal47_core_drupal -f -x

In this case, the sifnetbcksite refers to an existing site. sifbuilder will take care to create a backup from it. Then, it will restore the backup file system and database sql dump taking into account the specifications in sifnetsite , normally different from the source site.

By now, sifbuilder -though the site definition specified in the source sifnetbcksite and the target sifnetsite site -has created a new tree in the file system and a new database, eventually with a different db prefix.

However, most wcm have a configuration file on the file system that, at this point, still refers to the original site. Importantly, all the operations until now have been blindly done, in the ignorance of the core being served. However, the generation of the configuration file on the site file tree is part of the installation process of the core, as described here, and sifbuilder must be made aware of the core installation package that should address that task. The core sip is thus included in the command so that the sif function clone_pod calls the sip configuration function of the core sip.

A different scenario appears when a site has to be migrated to a new host and eventually a new operating system. In this case, it is necessary to generate the backup, move the backup to the target host and do the restore there. This is done specifying the siburi in the backup and restore commands.

> php sifcmd.php backup_pod
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd501_at_localhost
--siburi=bck_pod__sbd501_at_localhost.zip -f

> php sifcmd.php restore_pod
--sifnetconfigfile=../sifbuilder_local/sifnet_config.php
--sifnetsite=sbd502_at_localhost
--siburi=bck_pod__sbd501_at_localhost.zip -x -f

Other cores

These actions are usable mutatis mutandis for joonla, postnuke or xoops cores and sites. The correspondence is shown in the table below.

During this recasting, a major event has taken place. A new siteParam has seen the light. The db_prefix_sep. Cloning sites implies unprefixing and prefixing tables. For this, it is necessary to know the syntax of table names. Most cores use the underscore as prefix separator. joomla does not. In sifbuilder 1_8_9 that parameter defaults to underscore in the unprefix and prefix functions in SifMdb. The builder is sceptical about historical and quantitative reasons and, if does not arise a good reason for that, chances are that it will be changed to null.