MKSBackup common features

This page bring together all features and parameters common to all back-end

• The destination syntax
• The mail configuration
• Send mail report via HTTP through MagiKmon
• Mail report
• Misc

The destination syntax

MKSBackup provide an original syntax to define where to save your backup depending on the date.

Destination is composed of rules, each rules is on a separate line and has the following format :

< type = time_selector > target

The type define the type of the backup and depend of the front-end. For example, ntbackup known: full, differential or incremental. Check the front-end documentation for possible values.

The time_selector is a comma separeted list of time atome. Atome can be day name or day number. If one atome match the day then the target part becomes the backup location.

The target is the directory or the file where to store the backup. The target can contain time related variables.

Some samples will help you to understand the syntax.

destination=<full=mon-sun>S:\backup\server01-${nweekdayname}.bkf

This unique rule tell MKSBackup to run a full backup every day, and store it in a different archive every day of the week. ${nweekdayname} is a variable and will be replaced by the name of the day.

destination=<full=sun>\\nas01\backup\data-full.bkf
            <inc=mon,wed,fri>\\nas01\backup\data-${nweekdayname}.bkf

Above, MKSBackup will do a full backup on Sunday and an incremental every two days.

A week divisor can be used, if you want to change the backup location every weeks. If you use a week divisor, you need to define the first day of the week. This is useful when you want to dispatch your backup between multiple destination, to keep more than one week of backup.

destination=<full=sun,wsun/2>S:\backup\week${nweek}\data-full-${nweekdayname}.bkf
            <inc=mon-sat,wsun/2>S:\backup\week${nweek}\data-inc-${nweekdayname}.bkf

Above the week divisor is 2 and the week start on Sunday. w in wsun means week and is used to distinguish wsun from the normal day selector sun. This means we have 2 directories S:\backup\week0 and S:\backup\week1 in wich we will have the file data-full-Sun.bkf, and data-inc-Mon.bkf up to data-inc-Sat.bkf. ${nweek} will be replaced by the number of the week in the cycle of two weeks, here 0 or 1.

destination=<full=sat,wsat0/2>\\nas_alpha\backup\data-full-${nweekdayname}.bkf
            <inc=mon-sat,wsat0/2>\\nas_alpha\backup\data-inc-${nweekdayname}.bkf
            <full=sat,wsat1/2>\\nas_beta\backup\data-full-${nweekdayname}.bkf
            <inc=mon-fri,wsat1/2>\\nas_alpha\backup\data-inc-${nweekdayname}.bkf

Above we are backuping on \\nas_alpha and \\nas_beta, switching every week.
wsat0/2 means:

• w is for week, to distinguish from the normal day selector
• sat point the first day of the week, here Saturday
• 0 means this concern the week 0 in the cycle of two weeks, 0 is the first one
• /2 is the week divisor, meaning we are working with a cycle of 2 weeks, weeks having number 0 and 1

It is also possible to deal with day of the month and month.

destination=<full=1,jan,jul>\\nas\backup\data-${nmonthname}.bkf

Above we are doing a full backup the first of January and July. ${nmonthname} will be replaced by the abbreviated month name.

Days, week days, month can be mixed toghether.

destination=<full=1-7,sun,jan,jul>\\nas\backup\data-${nmonthname}-${nweekdayname}.bkf

The day will match the rule above if the day of the month is between 1 and 7 and if the day is a Sunday and if the month is January or Juli. In other word we are doing a full backup the first Sunday of January and July.

Valid Day of the month are decimal number between 1 and 31.

Valid weekday are :

mon, tue, wed, thu, fri, sat, sun

Valid month are :

jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec

Variables

MKSBackup allow you to customise the target location and name using build-in variables. Here are the time variables:

• %a Locale's abbreviated weekday name.
• %A Locale's full weekday name.
• %b Locale's abbreviated month name.
• %B Locale's full month name.
• %c Locale's appropriate date and time representation.
• %d Day of the month as a decimal number [01,31].
• %H Hour (24-hour clock) as a decimal number [00,23].
• %j Day of the year as a decimal number [001,366].
• %m Month as a decimal number [01,12].
• %M Minute as a decimal number [00,59].
• %S Second as a decimal number [00,61].
• %U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0.
• %w Weekday as a decimal number [0(Sunday),6].
• %W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
• %x Locale's appropriate date representation.
• %X Locale's appropriate time representation.
• %y Year without century as a decimal number [00,99].
• %Y Year with century as a decimal number.
• %% A literal % character.

Using a different notation, MKSBackup provide also these variables :

• ${epoch} This is the time in second from 1 Jan 1970 called the epoch.
• ${week} When using a week divisor, this is the week number. Default is 0.

Some front-end provide also specific variables, look the front-end page fore more.

The environment variables

The variables defined in the environment are available from inside the destination syntax. For example, under win32 architecture, ${COMPUTERNAME} will be replaced by the host name

The night shift

Most of the time your backups will run during the night. It will start before or after midnight. Even if the day change at midnight, the night is still the same and their is no reason to give different name to a backup started at 23:00 and one started 2H later at 1:00 !

This is why MKSBackup invent the night shift. When enable, the first rule of the destination below,

destination=<full=sun>\\nas01\backup\data-full.bkf
            <inc=mon-sat>\\nas01\backup\data-${nweekdayname}.bkf

will match Sunday April 25 at 22H00 but also Monday 26 at 2H00. And in both case the target is \\nas01\backup\data-full.bkf.

This allow you to have uniformity in your file naming, for all your backups running during the night.

night_shift (default is on)

This allow you to enable the night_shift for one job or for all job if set in the [DEFAULT] section.

night_shift=on

These variables will vary with the night shift when set or match the real date and time when not set :

• ${nday} Day of the month as a decimal number [01,31].
• ${nmonth} Month as a decimal number [01,12].
• ${nyear} Year with century as a decimal number..
• ${nweekday} Weekday as a decimal number [0(Sunday),6].
• ${nyearday} Day of the year as a decimal number [001,366].
• ${nweekdayname} Locale's abbreviated weekday name.
• ${nmonthweek} Week of the month as a decimal number. 0 for days 1-7, 1 for days 8-14 ...
• ${nmonthname} Locale's abbreviated month name.
• ${nweek} Like ${week} but for the night day.

The mail configuration

mail (default is yes)

This enable or disable the check of the mail configuration and the sending of any email. Possibles value are yes, no or fail (to send an email only when backup fail).

mail=yes

smtp_host (default is 127.0.0.1)

This the name or the IP address of your mail relay.

smtp_host=relay.example.com

smtp_port (default in 25, 465, 587 depending of smtp_mode)

This the port to connect on the mail relay.

smtp_port=25

smtp_mode (default is normal)

Can be normal, ssl or tls

smtp_mode=tls

smtp_login

When you need SMTP authentication, this is the login.

smtp_login=your.address@yourdomain.com

smtp_password

When you need SMTP authentication, this is the password.

smtp_password=secret

sender (mandatory)

This is the sender address for the emails MKSBackup will send. More and more mail relay expect a valid email address and a valid domain name !

sender=foo.bar@example.com

recipients (mandatory)

This is a space separated list of email addresses. Each of them will receive the backup report, or test mail.

recipient=bill@hotmail.com barack@gmail.com

attachment_gzip (default is 100)

Attachment above this size will be gzip'ed.

attachment_size=100

attachment_size (default is 1000)

This is the maximum size of an attachment in K bytes. Attachment above this size will be skipped.

attachment_size=1000

Here are some samples

The simple setup, using port 25, no SSL nor TLS, no authentication

smtp_host=smtp.yourisp.com
sender=your.address@yourdomain.com
recipients=your.address@yourdomain.com someone.else@otherdomain.com

A connection using SSL and authentication, default port for SSL is 465.

smtp_host=yourserver.yourdomain.com
smtp_mode=ssl
smtp_login=your.address@yourdomain.com
smtp_password=yourpassword
sender=your.address@yourdomain.com
recipients=your.address@gmail.com someone.else@otherdomain.com

A connection using TLS and authentication, default port for TLS is 587. This configuration is the recommended one when using GMAIL smtp relay.

smtp_host=smtp.gmail.com
smtp_mode=tls
smtp_login=your.address@gmail.com
smtp_password=yourpassword
sender=your.address@gmail.com
recipients=your.address@gmail.com someone.else@otherdomain.com

Send mail report via HTTP through MagiKmon

People having subscribed to the MagiKmon service can send the backup mail report via the HTTP protocol. The service monitoring their backups provides an URL they can use with the magikmon option below. The recipients set in the mail configuration are ignored in this process (except for the generation of the mail). If a forward has been configured for the MagiKmon service, then the report will be forwarded to this address.

Both, mail configuration and magikmon option can be set together ! The report will be first sent using SMTP protocol to the recipients, then it will be sent to the MagiKmon service.

magikmon

This must refer to the address of the MagiKmon service monitoring your backup.

magikmon=http://monitoring.magikmon.com/sendbackup/123/yourdomaine.com

The full URL is available from Service panel of the monitoring service. Here 123 is the number of the service, and yourdomaine.com is used as a password to access this service, to avoid abuse.

To work, mail option sender and recipients must be set ! This is required to generate the body of the email ! Options attachment_gzip and attachment_size or their default values will be used too. This is required to generate a well formated email able to be forwarded later by MagiKmon.

Mail report

The mail report always use the same structure :

Mail Subject

The subject is formatted in a way to help the user to quickly sort emails. The usual format is :
MKSBACKUP <command> <status> <job_name>

• command Can be BACKUP or CONFIG depending the command backup or checkmail used as first parameter of the mksbackup command.
• status Can be OK, ERR or WAR .
• job_name This is the name of the job.

Mail body

The mail body contains user friendly information, error messages and backup status.

Attachments

To not overload the mail body, extra data are stored in attachments. Each front-end provides its own attachment files. Here are the common attachments, check the front-end page for specific's ones:

• config.ini This is the configuration file, selected using the -c option.
• status.txt This is a key=value digest of the backup.
• logging.txt This is the MKSBackup log of the backup.
• traceback.txt This attachment contains a python stack trace when an unexpected error appends.

Misc

update_check (default is yes)

This is a boolean switch, if set to yes, MKSBackup will check for the availability of a new version and warn you at the beginning of each emails.

update_check=no