Server backup and restore

1. Backup using BackupServer.exe

• Backup using the program “BackupServer.exe” is based on creating backups on the server and subsequently downloading them to a client computer over the internet or an internal network.
• Using the program “BackupServer.exe”, the following can be backed up:
  • IIS server settings,
  • databases (MSSQL, Firebird),
  • the NET Genium directory.
• Sample program files are available in every NET Genium installation in the directory “Backup\BackupServer”.

Usage:

BackupServer.exe [/config][/task][/decrypt][/restore]

• Optional parameters:
  • /config – creates a sample configuration file “BackupServer.exe.config” in the current location,
  • /task – creates the scheduled task “NET Genium\BackupServer” with daily execution,
  • /decrypt – decrypts all ZIP archives in the “Files” directory; see section Backup restore,
  • /restore – restores files from backups stored in the “Files” directory to the target location; see section Backup restore.
• The program also supports the file parameter, which can be used to specify a particular (encrypted) file. In this case, the specified file is decrypted.

Example usage:

BackupServer.exe file.zip

1.1. Server side – creating a backup on the server

• Store the program “BackupServer.exe”, including all libraries and files, for example in the directory “C:\Services\BackupServer\”. The created backups are also stored in this directory.
• The program uses the configuration file “BackupServer.exe.config”, which contains encryption settings, a list of databases and directories to be backed up, and other options.

Example configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>

    <add key="key1" value="abcdefgh" />
    <add key="key2" value="hgfedcba" />

    <add key="database" value="db1" />
    <add key="database" value="(local)\SQLEXPRESS|db2" />
    <add key="database" value="(local)\SQLEXPRESS|*" />
    <add key="database" value="C:\Firebird\DB3.FDB" />
    <add key="excludedatabase" value="(local)\SQLEXPRESS|db4" />
    <add key="excludedatabase" value="C:\Firebird\Test\*.fdb" />

    <add key="directory" value="C:\inetpub\wwwroot" />
    <add key="directory" value="C:\Services" />
    <add key="includefile" value="C:\Services\Custom\settings.json" />

    <add key="excludedirectory" value="C:\Services\BackupServer\Files" />
    <add key="excludedirectory" value="C:\Services\BackupServer\Temp" />
    <add key="excludefile" value="C:\Services\PaymentService\*.log" />

    <add key="runfile" value="C:\Services\Update\Update.exe" />

    <add key="fullbackupinterval" value="7" />
    <add key="multiplethreads" value="true" />
    <add key="copy2directory" value="D:\BackupCopy" />

    <add key="logServiceConnectionString" value="driver=firebird;datasource=localhost;user=SYSDBA;password=masterkey;database=C:\Firebird\netgenium.fdb;charset=WIN1250;collation=WIN_CZ_CI_AI" />

  </appSettings>
</configuration>

The configuration file allows you to specify:

• backup encryption – parameters “key1” and “key2” (if specified, the created files are encrypted after the backup is completed and later decrypted on the client),

• databases to be backed up – parameter “database”:
  • MSSQL databases: syntax “instance_name|database_name”,
  • all MSSQL databases on an instance: syntax “instance_name|*”,
  • Firebird databases: full path to the database file,
  • multiple Firebird databases in one directory: full path to the directory ending with “*.fdb”,
  • a Firebird database specified only by file name is looked up in “X:\Firebird\” on the same drive from which “BackupServer.exe” is running,

• databases excluded from backup – parameter “excludedatabase”:
  • MSSQL databases use the same syntax as the “database” parameter,
  • Firebird databases can be specified by full path or by a “*.fdb” mask,

• directories to be backed up – parameters “directory” or “includedirectory”,

• individual files to be backed up – parameter “includefile”:
  • wildcard patterns such as “*.extension” can also be used,

• directories excluded from backup – parameter “excludedirectory”,

• files excluded from backup – parameter “excludefile”:
  • wildcard patterns such as “*.extension” can be used,

• programs to be executed after the backup is created (but before encryption) – parameter “runfile”,

• interval for creating a full backup in days – parameter “fullbackupinterval”. If the parameter is not specified, the default interval of 1 month is used,

• parallel database backup – parameter “multiplethreads”:
  • if the parameter is missing or set to “true”, databases are backed up in threads,
  • the value “false” forces databases to be backed up sequentially,

• copying newly created archives to another directory – parameter “copy2directory”:
  • each archive is copied to the target directory with up to 10 attempts 10 seconds apart,

• automatic logging of the “BackupServer” service to the “ng_sluzbawindows” table (interval 1 day) – parameter “logServiceConnectionString”.
  • For backward compatibility, the “connectionString” parameter can also be used.

• IIS server settings are backed up automatically.

• Backups are typically triggered by a scheduled task in Windows. To create a backup, it is sufficient to run “BackupServer.exe” without parameters.
• A scheduled task can also be created using the “/task” parameter. The program creates the “NET Genium” folder in Task Scheduler, adds the “BackupServer” task, sets daily execution 5 minutes after midnight on the following day, and configures it to run with highest privileges. After creation, the task account must be changed to an account that has access to the backed-up databases and files.

Backup process

• Creation of the “Files” and “Temp” directories if they do not already exist.

• Cleaning of the “Temp” directory, which is used to temporarily store:
  • backups of IIS settings (including application pools and websites),
  • database backups.

• Performing the backup into the “Temp” directory:
  • IIS: “applicationHost.config”,
  • IIS application pools: “apppools.xml”,
  • IIS websites: “sites.xml”,
  • Windows scheduled tasks: “scheduledtasks.xml”,
  • Indexing Service catalogs: “catalogs.IS”,
  • databases: “database_name.bak” (MSSQL) or “database_name.fbk” (Firebird).

• IIS settings are backed up only on Windows Server. The program first copies “%windir%\System32\inetsrv\config\applicationHost.config” to “Temp\applicationHost.config” and creates the helper file “Temp\applicationHost.bat.txt” with the command for manually restoring this file.

• If the tool “%windir%\System32\inetsrv\AppCmd.exe” exists, the program runs:
  • “%windir%\System32\inetsrv\AppCmd.exe list apppool /config /xml” – the output is saved to “Temp\apppools.xml”,
  • “%windir%\System32\inetsrv\AppCmd.exe list site /config /xml” – the output is saved to “Temp\sites.xml”.

• If the tool “%windir%\System32\schtasks.exe” exists, the program runs “%windir%\System32\schtasks.exe /query /xml” and saves the output to “Temp\scheduledtasks.xml”.

• The program also attempts to back up Indexing Service catalogs to “Temp\catalogs.IS”. If Indexing Service is not available on the system, this part is silently skipped.

• The files from the “Temp” directory are then included in the created ZIP archive together with the backed-up directories and files defined in the configuration. If the configuration does not contain any database or any backed-up directory, the program exits after creating the temporary server-settings backup files and no ZIP archive is created.

• Before backing up each database, the program deletes records older than 1 month from the tables “stables_stats”, “sviewpages_stats”, “squerybuilder_stats”, “sngef_stats”, and “sngscript_stats”, if those tables exist in the database.

• Database backup:
  • MSSQL databases are backed up using the “BACKUP DATABASE” command with Windows authentication (“Trusted_Connection=true”),
  • Firebird databases are backed up using “gbak.exe”, which the program searches for in “C:\Program Files\Firebird” and “C:\Program Files (x86)\Firebird”,
  • before a Firebird database is backed up, “SET STATISTICS” is executed for all indexes,
  • backing up a single Firebird database has a 4-hour timeout,
  • databases are backed up in parallel using at most 5 threads; databases larger than 1 GB are effectively started separately after previous threads finish.

• The “Temp” and “Files” directories of “BackupServer.exe” are excluded from backup automatically even if they are not listed in the configuration.

• The program automatically skips:
  • “catalog.wci” directories,
  • directories containing “\Logs\”,
  • directories containing “\Temp\”,
  • “*.bak” and “*.fbk” backups located in a “Backup” directory,
  • regular files larger than 1 GB.

• Determining whether a full or incremental backup will be created:
  • A full backup is created if:
    • the “Files” directory is empty (no previous backups exist),
    • backups exist in the “Files” directory but no full backup marked with “-x” exists,
    • the full-backup interval has elapsed and the weekend restriction for large full backups is not active.
  • The full-backup interval is calculated from the date of the last full backup marked with “-x”:
    • if “fullbackupinterval” is greater than 0, the next full backup is allowed only when the new backup date is later than the last full backup date + “fullbackupinterval” days,
    • if “fullbackupinterval” is missing or 0, the interval is 1 month and the next full backup is allowed only when the new backup date is later than the last full backup date + 1 month.
  • In this decision, the new backup date is the day before the program is run, because backup files are named using “DateTime.Now.AddDays(-1)”.
  • If the full-backup interval has not elapsed yet, an incremental backup is created.
  • If the full-backup interval has elapsed and the total size of the last full backup is up to 10 GB, a full backup is created.
  • If the full-backup interval has elapsed but the total size of the last full backup exceeds 10 GB, a full backup is created only when the program is run on Saturday or Sunday; on other days, an incremental backup is created.
  • An incremental backup is created whenever a full backup is not performed. Incremental backups include files with the archive attribute or files whose modification date is on or after the day following the last backup.

• Storing the full backup:
  • Full backups are stored in the format “yyyy-mm-dd-x.zip”. If the backup is split into multiple files, the additional parts receive a sequence number according to the unique file name rules, for example “yyyy-mm-dd-x (2).zip”.
  • The weekend restriction for full backups larger than 10 GB is evaluated only after the full-backup interval has elapsed.

• Optional cleanup of older backups:
  • If a full backup is being created and at the same time:
    • “fullbackupinterval” is less than 30 days, or
    • (size of the last full backup × 1.5) exceeds the available disk space,
  • all backups older than 1 week (both full and incremental) are deleted.

• Creating a new backup in the “Files” directory:
  • ZIP archives are created from the contents of the “Temp” directory and all directories defined in the configuration,
  • the backup is split into multiple ZIP files with a maximum size of 1 GB per file,
  • individual incremental backup files are named “yyyy-mm-dd.zip”, or “yyyy-mm-dd (2).zip”, “yyyy-mm-dd (3).zip”, and so on,
  • the date in the backup name corresponds to the day before the program was run.

• Databases larger than 1 GB:
  • if a database backup is larger than 1 GB, it is not included in the main ZIP archive but is stored in a separate ZIP archive in the “Files” directory as “yyyy-mm-dd-db-database_name.zip”,
  • the corresponding database file is then removed from the “Temp” directory.

• Creating the files “FileList.txt” and “log.txt” in the “Files” directory:
  • “FileList.txt” contains a list of all available backup files in the “Files” directory (ZIP archives and any older standalone “.bak” or “.fbk” files),
  • each created ZIP archive also contains the files “Directories.txt”, “Files.txt”, and “Errors.txt”,
    • “Directories.txt” contains the list of directories found during backup,
    • “Files.txt” contains the list of files found during backup,
    • “Errors.txt” contains paths where reading or backup failed,
  • “log.txt” contains a log entry about the backup process (for example “2014-01-01 05:00:00 OK”).

• The program also creates helper logs in the program directory:
  • “BackupServer.log” – the main process log,
  • “BackupServer-last-job.log” – the last currently running operation,
  • “DriveInfo.log” – used, free, and total disk space,
  • “Customer.log”, “Developer.log”, “Tester.log”, “Errors.log”, “Log.aspx.log”, “LogToDatabase.log”, “LogToDisk.log”, and “RunScript.log” – diagnostic lists derived from the backed-up NET Geniums.

• After a file has been successfully added to an archive, the program removes the archive attribute from that file if its last modification time has not changed in the meantime.

• Executing programs defined by the “runfile” parameter:
  • programs are started after the main ZIP archive is created; they are launched one by one and can then continue running in parallel,
  • if an item points to “Update.exe” and the current hour is later than 6, the program is not executed,
  • “BackupServer.exe” waits for the executed programs to finish for up to 4 hours and then waits 1 additional minute.

• Encrypting newly created files in the “Files” directory if “key1” and “key2” are specified in the configuration.

• If the “copy2directory” parameter is specified, newly created ZIP archives are also copied to the specified directory after creation or encryption.

• Deleting backups older than 1 week (both full and incremental) if a full backup has just been created or if the backup date is older than the date of the last full backup.

• For the client component to function, the “Files” directory must be remotely accessible. This can be achieved by adding a virtual directory to IIS under the NET Genium application.

• On first run, the program creates a “Web.config” file in the “Files” directory. This file allows only the “HEAD” and “GET” methods for downloading backups, sets the request limit to 4 GB, and registers the “application/octet-stream” MIME type for “.bak” and “.fbk” files.

• Name the virtual directory, for example, “backupserver298” and set its physical path to “C:\Services\BackupServer\Files\”.

• Configure read permissions for this directory so that backups can be downloaded from client machines.

1.2. Client side – downloading backups to the client

• The client component is responsible for downloading backups from the server.

• In the “Client” subdirectory of the “BackupServer” directory, locate the program “BackupServerService.exe”.

• Run “BackupServerService.exe” to create the shortcuts “BackupServerService – console.lnk” and “BackupServerService – user.lnk”.

• Run “BackupServerService – user.lnk” and click the “Install” button in the dialog. This installs the “BackupServerService” service, which starts automatically after system startup.

• The service checks for available backups every 10 minutes.

• The service uses the configuration file “BackupServerService.exe.config”.

Example configuration file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>

    <add key="url" value="https://www.netgenium.com/backupserver298" />

    <add key="smtpServer" value="localhost" />
    <add key="smtpUserName" value="" />
    <add key="smtpPassword" value="" />

    <add key="errorFrom" value="backupserverservice@netgenium.com" />
    <add key="errorTo" value="support@netgenium.com" />

    <add key="key1" value="abcdefgh" />
    <add key="key2" value="hgfedcba" />

    <add key="logServiceConnectionString" value="driver=firebird;datasource=localhost;user=SYSDBA;password=masterkey;database=C:\Firebird\netgenium.fdb;charset=WIN1250;collation=WIN_CZ_CI_AI" />

  </appSettings>
</configuration>

The configuration file must specify:

• the URL from which backups will be downloaded – parameter “url” (in the example, “backupserver298” is a virtual directory created in IIS),
  • it is recommended to restrict access by IP address so that only designated client machines can access the directory,
• the SMTP server and credentials for sending email notifications – parameters “smtpServer”, “smtpUserName”, and “smtpPassword”,
• the sender email address for error notifications – parameter “errorFrom”,
• the recipient email address for error notifications – parameter “errorTo”,
• decryption keys for backups – optional parameters “key1” and “key2” (must match the keys on the server; if not specified, downloaded backups are not decrypted),
• automatic logging of the “BackupServerService” service to the “ng_sluzbawindows” table (interval 1 day) – parameter “logServiceConnectionString”.

Backup download information

• Backups are stored in the “Files” directory at the location where “BackupServerService.exe” is installed.
• If “key1” and “key2” are specified in the configuration, all ZIP archives and database files are decrypted after download.
• During each download, the age of full backups is checked. If multiple full backups are present in the “Files” directory, the first full backup and all older full backups are automatically deleted.

2. Backup restore

• A backup can be restored on a client computer by running “BackupServer.exe” with the “/restore” parameter.
• The program offers the following options:
  • Restore all databases and server settings
  • Restore all files
  • Restore all files except file attachments
  • Restore file attachments only
  • Restore file list only (test)
• Note: If the restore is performed directly on the server, the files must first be decrypted by running “BackupServer.exe /decrypt”, because server-side backups are stored in encrypted form.

2.1. Restore all databases and server settings

• This option creates a “Restore” directory containing backups of all databases and server settings from the most recent backup.
  • Database backups can then be restored in bulk using the program “SqlBackup.exe” with the restoreall option.
  • IIS settings can be restored by copying the file “applicationHost.config” to the directory “Windows\System32\inetsrv\config\”. For this purpose, a batch file “applicationHost.bat.txt” is provided in the “Restore” directory.
  • If the file “applicationHost.config” is not available, IIS settings can be partially restored by importing the files “sites.xml” and “apppools.xml”.
  • Restored server settings can also include “scheduledtasks.xml” and “catalogs.IS” if they were created during backup.
• This option restores only archives with the newest backup date. Older incremental backups are not used for restoring databases and server settings.
• With this option, only database backups from the “Temp” directory and server settings files are restored from ZIP archives. Regular application files are not restored.

2.1.1. Manual restore of IIS settings

• Restore IIS settings manually from Command Prompt or PowerShell running as administrator.

• If you are restoring the entire “applicationHost.config” file, first stop IIS, back up the current configuration, and then copy the restored file to the IIS configuration directory:

iisreset /stop
copy "%windir%\System32\inetsrv\config\applicationHost.config" "%windir%\System32\inetsrv\config\applicationHost.config.before-restore"
copy "C:\Services\BackupServer\Restore\applicationHost.config" "%windir%\System32\inetsrv\config\applicationHost.config"
iisreset /start

• If you are restoring only application pools and websites from “apppools.xml” and “sites.xml”, import the application pools first and the websites afterward. Websites may reference application pools that must already exist in IIS before the websites are imported.

• Import in PowerShell:

Get-Content "C:\Services\BackupServer\Restore\apppools.xml" | & "$env:windir\System32\inetsrv\AppCmd.exe" add apppool /in
Get-Content "C:\Services\BackupServer\Restore\sites.xml" | & "$env:windir\System32\inetsrv\AppCmd.exe" add site /in

• Import in Command Prompt:

"%windir%\System32\inetsrv\AppCmd.exe" add apppool /in < "C:\Services\BackupServer\Restore\apppools.xml"
"%windir%\System32\inetsrv\AppCmd.exe" add site /in < "C:\Services\BackupServer\Restore\sites.xml"

• Importing with “AppCmd.exe” adds new objects. If an application pool or website with the same name already exists in IIS, the import fails. In that case, rename or delete the existing object first, or import only the missing parts of the configuration.

• If “BackupServer.exe” was run on a server with encrypted backups, first run “BackupServer.exe /decrypt” and then “BackupServer.exe /restore” with the Restore all databases and server settings option. This extracts “applicationHost.config”, “apppools.xml”, and “sites.xml” to the “Restore” directory.

2.2. Restore all files

• This option restores the complete directory structure, including all files, from all available backups – starting with the most recent full backup and including all subsequent incremental backups.
• The program prompts whether the directory structure should be restored:
  • to the original location (matching the server location), or
  • to another selected directory from which the files can later be moved as needed.
• When restoring all files, database backups from the “Temp” directory and the server settings files “applicationHost.config”, “applicationHost.bat.txt”, “apppools.xml”, “sites.xml”, “scheduledtasks.xml”, and “catalogs.IS” are not restored. Those belong to the “Restore all databases and server settings” option.
• After extracting the archives, the program reads “Directories.txt” and “Files.txt” from the restored backup:
  • creates directories that are missing in the target location,
  • writes warnings for files listed in “Files.txt” that could not be restored,
  • deletes files that were extracted during restore but are not listed in the resulting “Files.txt”.
• Deleting unused files is skipped if “Files.txt” does not match any restored file. This prevents unintended deletion when the file list is incomplete or incorrect.

2.3. Restore all files except file attachments

• Restoring all files can be time-consuming. In emergency situations, the restore process can therefore be split into two phases:
  • in the first phase, restore only the directory structure without file attachments (that is, without all “Files” directories), allowing applications and services to be started,
  • in the second phase, restore the file attachments themselves.
• With this option, the program skips all files stored directly in “Files” directories or in their subdirectories. The files “Directories.txt”, “Files.txt”, and “Errors.txt” are restored for the subsequent validation and second restore phase.

2.4. Restore file attachments only

• Restoring file attachments separately is intended primarily as the second phase of a restore process after applications and services have been brought back online.
• When splitting the restore into two phases:
  • the first phase restores the directory structure without file attachments (without “Files” directories),
  • the second phase restores the file attachments.
• This option restores files in “Files” directories and their subdirectories. It also restores the control files “Directories.txt”, “Files.txt”, and “Errors.txt”.

2.5. Restore file list only (test)

• This option is used for a test pass through the archives without actually extracting files.
• The program writes to “Restore.log” the list of paths that would be processed during a regular restore.
• In this mode, the restore is evaluated against the original paths only logically; files are not created or overwritten.