Running MAGS

In order to run mags with a previously defined set of options and paths (see above), you simply call it with the MAGS Option File as the only parameter or use the Web GUI to start a backup manually.

MAGS runs until all its child processes have finished and it ends with the highest return code any of its child processes (STORAGE PROTECT incremental backups) had, so a return code of, say, 12 means, that at least one of the potentially hundreds of STORAGE PROTECT clients started by MAGS finished with a return code of 12 but none of the jobs finished with a higher return code.

When scheduling MAGS using STORAGE PROTECT client schedulers, keep this behaviour in mind. Also remember that certain pre/post scheduling you may have had to do in your specific environment before using MAGS (i.e. “net use” of all UNC paths about to be backed up before actually running STORAGE PROTECT on certain NetApp constellations – or triggering/deleting snapshots etc.) will most likely apply to a MAGS command schedule, too.

Note

Depending on how your proxy server and file servers are set up, there may be inherently challenging path names for STORAGE PROTECT to backup. Despite MAGS and STORAGE PROTECT each running entirely as Unicode applications, the interface between the two is STORAGE PROTECT’s dsmc.exe which is ultimately interpreting input not as Unicode but in a Windows console context which in turn depends on configurable codepages. Considering that the same is true for file servers and clients creating directories and files on them, it is obvious that there are myriad different ways to interpret any string of bytes representing a path or file name as characters. MAGS tries to transfer paths as raw data to and from STORAGE PROTECT, which works most of the time. If it doesn’t work, STORAGE PROTECT will throw an error which either means that the path it tried to backup couldn’t be found and/or isn’t in a valid format. If such an error occurs, MAGS will gradually reduce the encoding of the path in question to its simplest format (ultimately ASCII) to ensure that a path is being backed up. You will still see the failed attempts in STORAGE PROTECT’s errorlog. In such cases, please check routinely whether MAGS ultimately succeeded in backing up the date in question and do notify us if it didn’t. The same is true for Unix type backups. If you backed up that Unix type data before, you should use the same LOCALE for the Unix user defined with your remote STORAGE PROTECT client. Ideally you use the same user from the same machine as you did before starting with MAGS. If the data in question hasn’t been backed up before, we recommend using UTF-8 as the LOCALE. Refer to IBM’s STORAGE PROTECT client documentation for details on this crucial and often misunderstood detail.

Running via Web GUI

To start a MAGS job via Web GUI, click on the button.

and then choose START BACKUP from the available tasks.

A new page will show where you can define a summary and further options for the job you are about to start:

Click on NEXT to continue to the next step or RETURN to go back to the start page. After clicking on NEXT, you will see a confirmation page where you can click START BACKUP to start your task or RETURN to the start page.

When starting the backup, you will be redirected to the running jobs’ overview page.

Running via Command Line

MAGS itself consists of two executables called “mags.exe” (for Windows backups) and “magsX.exe” (for remote Unix backups). After installation, both reside in their default location (usually “program filesgeneral storage software gmbhmags”) and you may want to move them away from there into a more STORAGE PROTECT command scheduler friendly location like “c:mags”.

Then, to start a MAGS backup via command line, use the following syntax:

mags.exe <MAGS option file>
magsX.exe <MAGS option file>

Examples:

magsX.exe d:\magsfiles\mylinuxmagsjob.mags
mags.exe d:\magsfiles\mywindowsmagsjob.mags

Note

The MAGS Option File has to be specified as a fully qualified name including its path. So if you have defined a MAGS instance as “d:magsfilesmymagsjob.mags”, you can run it by changing to the path containing “mags.exe” and issuing “mags.exe d:magsfilesmymagsjob.mags”. If the MAGS instance is a remote (Unix) configuration, run “magsX.exe d:magsfilesmymagsjob.mags” instead.

Additional Options

Manual Expiration

Under certain circumstances, not all data in directories being directly handled by MAGS will expire during a regular MAGS backup if they have been deleted from your file server. Say you had a directory called \my-fileserverAB which contained other subdirectories and files and that directory was handled non-recursively by MAGS since it was within the scope of the set scandepth or an according subscan. During the first MAGS backup after deleting that directory, the directory itself will expire from STORAGE PROTECT and hence no longer be part of a restore …-latest. In your STORAGE PROTECT server that directory will be shown as “inactive” and it will expire from STORAGE PROTECT Storage according to retention and versioning you set in your management classes. However the content of these directories (files and subdirectories) will not automatically expire from STORAGE PROTECT storage and still show up as “active”. As already mentioned, this won’t have an effect on restore – however over time, data will accumulate in your STORAGE PROTECT server which shouldn’t necessarily be there depending on your management class settings. For these data to expire and become inactive, you should consider running MAGS with the “-expire” command line option from time to time (like once a month, once a year or on demand if there was a heavy re-structuring of top-level directories on your file server). Depending on how much data there is to process, the “-expire” parameter can cause MAGS backups to take considerably longer than regular backups.

Note

All deleted files and directories that have been backed up from structures that still exist will expire with the regular MAGS backup. Only deleted directories within the scope of your scandepth parameter will be picked up by MAGS when using the “expire” parameter.

You can activate expiration by using the “-expire” command line option with mags.exe or magsX.exe in the following way:

mags.exe -expire  <mags option file>

Note

When using the -expire function, MAGS is not able to use bunched jobs, so there will be more parallel jobs than usual if you are using the bunch functionality.

Examples:

magsX.exe -expire d:\magsfiles\mylinuxmagsjob.mags
mags.exe -expire d:\magsfiles\mywindowsmagsjob.mags

Expiration Preview

If you are not sure which files would expire with “-expire” and want to test that first, instead use the “-expirepreview” parameter:

mags.exe -expirepreview  <mags option file>

Examples:

magsX.exe -expirepreview d:\magsfiles\mylinuxmagsjob.mags
mags.exe -expirepreview d:\magsfiles\mywindowsmagsjob.mags

This will generate a special logfile with .expire-Extension and shows the commands to manually expire, if needed.

preview Option

If you want to do a “dry-run” with MAGS, e.g. to check if permissions are correct or to have a look at how many jobs MAGS would run with specific options, you can use the “-preview” option when executing MAGS via command line.

mags.exe -preview <mags option file>

Examples:

mags.exe -preview d:\magsfiles\mywindowsmagsjob.mags
magsX.exe -preview d:\magsfiles\myremotelinuxmagsjob.mags
magsC /etc/mags/jobs/share01.mags --preview

Note

With the “-preview” parameter, log files will be named with a timestamp to be distinguishable from other logs.

noroot Option

When using STORAGE PROTECT with NetApp filers in a specific combination of circumstances, issuing a dsmc backup command with “subdir=no” still results in subdirectories being backed up. This would lead to one Job taking a very long time to backup files which have already been backed up in the parallelised jobs MAGS creates. If you are encountering this specific issue, consider running MAGS with the “-noroot” parameter:

mags.exe -noroot <mags option file>

Examples:

mags.exe –noroot d:\magsfiles\mywindowsmagsjob.mags

Note

The “-noroot” parameter only applies to MAGS jobs on Windows.

This will lead to MAGS always only backing up files at least one level underneath the root backup level.