Last updated on Sunday 3rd of April 2022 12:42:15 PM

©XSIBackup-DC GUI Manual



Introduction

©XSIBackup-DC is a command line tool developed in plain C and aimed at backing up VMs in an ©ESXi environment. It is managed through command line switches that allow to easily backup and replicate running Virtual Machines to a locally accessible file system or over IP to any remote file system that can be accessed through SSH.

You don't need this GUI to use ©XSIBackup-DC to its full extent, in fact many sysadmins prefer the command line. Nonetheless the GUI will allow you to use the software faster, if you are a novice user, through an interface that will filter information and format arguments, so that you don't need to use the command line to set up backup & replication jobs.

Still, this is not software for users and our support team is not there to take your hand and teach you basic Linux administration concepts. On the other hand, if you are a ©VMWare ©ESXi sysadmin, you are going to find this GUI extremely useful.


Configure the GUI

©XSIBackup-DC's GUI is based on nCurses, thus, it works on any SSH terminal. We can't fit all options and buttons in a classic bare 80 characters wide window though. You need to set your terminal to work in a graphic environment. This is how most SSH clients work by default, like Putty (our reference tool in Windows).

Nonetheless, if you use some basic SSH terminal software, you may be constrained by its reduced dimensions, such as that things just don't fit on your terminal window. This can cause from things not showing up to windows being printed partially on the available window size. Just stretch your window size.
Windows
If you are working in a Windows desktop, just use Putty, you don't even need to install it and it will work out of the box. We have configured the GUI to work without even setting an ideal character map. The borders and corners will be drawn with standard ASCII characters.

There are many other Windows SSH client terminals available out there. If you decide to use some of them, please be aware that you will need to get it going in a graphical way, so that it is able to print 'n' columns and rows.

Linux
Most SSH clients in a Linux desktop will also come configured out of the box, like the Gnome terminal in Linux Mint and many other distros. Still, not any terminal in any distro will work out of the box. Some clients have reported the necessity to export a TERM variable like this:

export TERM=xterm

Mac
Same as in Linux. Mac OS is a UNIX os running a desktop, setting the terminal mode to xterm will fix all problems in case you are running into some issue derived from a limited window size.


Installation

Installing ©XSIBackup-DC is covered in the user manual and the README.txt file and is a trivial task. An install script is provided. All you have to do is copy the .zip package to the /tmp dir, extract, set execute permissions to the install file and run.

unzip XSIBackup-DC_1.4.0.0.zip
chmod 0700 install
./install


We won't comment anything else on installation, as it is something that you can't miss. Of course, choosing the default installation dir is the recommended option. If you choose some other directory, you assume the responsability to control every relevant aspect, as whether the path is persistent in the ©ESXi file system or not.


Invoking the GUI

You invoke the GUI by running

./xsibackup-gui

(*) The above syntax is relative to the installation dir. You must have previously changed dir to the ©XSIBackup-DC installation directory (default is /scratch/XSI/XSIBackup-DC)


Linking Hosts

Linking hosts is the action by means of which you exchange your ©XSIBackup-DC public key with a remote server to be able to copy data to the remote file system through key authentication.

The GUI keeps a gui/dat/.links file with the hosts that are currently linked to the host where the GUI is being run. You may edit this file manually to remove some zombie entry, but adding the remote host's information will not link the working host to it. you do need to use the GUI or the --add-key command line argument, for which this part of the GUI is a graphical substitute, but in the end does the same.

You need to link to a server before even attempting to use a remote path. Only previously linked remote servers will be available to choose to build a remote path. ©XSIBackup-DC uses a pair of RSA keys which are generated the first time that you run a command or open the GUI. You can delete them and they will be generated again, but you will loose any pre-stablished trust relationship with other linked servers. Thus, you must back that key pair and associated files (anything containing RSA in its name) up to be able to recover access to some server to which you added your public key.

We are making obvious statements for any experienced sysadmin. If you are a power user, the need to keep any configuration file in a safe place, with special attention to the RSA keys, is something we should not need to keep insisting on. Keeping a copy of your installation directory out of each server is enough to be able to rebuild your backup topology in case of a full reinstall.

©XSIBackup-DC: link hosts main screen

Above is the host linking main screen from where you can add remote hosts. Your .pub key will be added to the remote host's authorized_keys file and you will be able to read and write to the remote file system passwordlessly.

©XSIBackup-DC: add new liked host To add a new host go to [Add new...] and press enter. You will be presented with a form to add some remote IPv4 address, port and username.

All examples that we are going to pose in the manual will make use of the root user. You can use other users, but it's your job to set their permissions on the remote system so that they have the priviledges to write to your remote path. Som operations, like adding a key are virtually impossible to be made with other user than root. The use of alternative users for backup operatios will be treated in specific posts, the subject is not trivial though, you need to know, not only how to set permissions, but where to assign them.

Once you enter the host's details you may be asked to confirm whether you want to add the remote host's key to the known_hosts file

©XSIBackup-DC: add remote host's key to known_hosts file

A confirm message will appear, just accept it.

©XSIBackup-DC: known_hosts fonfirmed

From this point, you will be asked to enter the remote server's password a number of times until the RSA .pub key is effectively introduced in the remote system's authorized_keys file.

(*) Please, note that the prompt to enter the password will be printed at the bottom of the terminal.

Once you complete all steps the host you are working at will be linked with the remote host.

©XSIBackup-DC: linked host final confirmation

Now you can select it in the list of linked hosts and press [Check/Add] to receive a confirmation that the host is correctly linked and the Last check column to be updated with a time stamp.

©XSIBackup-DC: link check

To delete a linked host select delete. Deleting the linked host removes the entry from the local gui/dat/.links file, but leaves the public key entry in the remote host's authorized_keys file. Thus, if you later on link to the same host, you will only be asked to enter the remote password once.

©XSIBackup-DC: delete linked host


SMTP Servers

SMTP servers allow to communicate the result of some --backup or --replica operation to the System Administrator. You don't need to set any SMTP server up to perform backups and replicas. It is highly recommended if you set up cron scheduled jobs though, as it will be the easiest way to have an overview on what was the result of your scheduled jobs.

SMTP servers are kept in the /etc/smtpsrvs.conf file, which is a semicolon delimited database holding one server per line. You can find each fields description in the very same file. This file can be indeed manually edited if you will.

• Ordinal: integer number which uniquely identifies the SMTP server. It can't be duplicated.

• Server:port: string containing the SMTP server's address or FQDN and port. Please, note that the server and port are separated by a colon, which is a different character than the field separator (semicolon).

• Mail-from: e-mail address the server will report the communication to be originated from.

• Username: username to use to authenticate to the server.

• Password: password associated to the above username. Please double quote the password should it contain some special character able to break a bash script (the SMTP module is a bash script).

• SMTP-Auth: it can be set to none keyword or yes.

• SMTP-Sec: it can be TLS or none.

• SMTP-delay: possible range is 0-4. Most of the times it doesn't need to be set, leave it as 0.

Add an SMTP server

Adding an smtp server by choosing the [Add a new smtp server] menu entry will create a template with provisional values to be edited. Please, edit each field to match your SMTP server's creddentials.

©XSIBackup-DC: add an SMTP server

Check SMTP servers

Once you have added an SMTP server you can check them via the corresponding entry in the SMTP server's main screen. You can select one or more servers to check. You will have to enter an e-mail address where to send the e-mail check.

©XSIBackup-DC: check an SMTP server

Delete SMTP servers

Deleting an SMTP server is an identical operation to checking, just select one or more servers and press the [Delete server/s] button.

©XSIBackup-DC: delete an SMTP server


Job Management

As you should know by now ©XSIBackup-DC stores commands into files inside the etc/jobs directory. You store jobs via the --save-job command when you are working in the command line. This formats the job as an absolute path to the xsibackup binary and one argument per line, redirecting everything to the var/log/xsibackup.log file.

You can then invoke those job files from the command line, the hosts's crontab, a composite bash script, an external crontab or whatever other means that you can imagine and is compatible with a bash shell.

The ©XSIBackup-DC GUI offers a way to create jobs based on the different available actions and arguments, still you need to know what each argument is and wht is the effect it will produce, as well as which arguments are compatible with a given action. Thus, reading the user manual is a must and using the GUI as a way to skip that reading is the shortest path to disaster.

At the time to write this GUI manual, most of the functionality is present at the User interface. Still you may need to use the command line to read logs, kill processes and do regular maintenance tasks.

©XSIBackup-DC: job management From the main job management screen you can add jobs and enter the [Edit] screen, which aglutinates the edition, deletion and job scheduling functions into a single screen.

Adding a job

Creating a job starts by choosing its unique Id, which is a numerical string ranging from 000 to 999. We have limited this by design and you must stick to it. There are 1000 possible values, which is more than enough to cover your needs. You have an additional optional argument field: --description that will allow you to use some more verbosy definition. Once you have created the job's unique Id you will be redirected to the job editing screen, which allows to set the three mandatory arguments of a backup job, namely: action, source and target, as well as all the additional arguments that allow to choose from a wide variety of options to fine tune your job.

Editing a job

When you choose the [Edit] entry from the first screen in the job management options, you are presented a list of jobs by job id, action and description. That list allows to select a job for editing, deleting or scheduling a cron entry. Select a job and then move the cursor to the appropiate button.

©XSIBackup-DC: job edit list

Choosing the [Edit job] button opens up the job editing screen, which lists all configured job arguments and thir values. There are three mandatory arguments: action, source and target for any given --backup or --replica job. You must set those three mandatory arguments for a --backup or --replica job to work. If you omit some fundamental argument you will get an error later on. We will kepp on refining the GUI to guide you through the process of creating a job, in any case, we are talking about extremely easy to understand concepts: you obviously need some type of backup, something to backup and somewhere to store the data.

©XSIBackup-DC: editing a backup job

From the above screen you can:
• Edit some argument's value.
• Save the backup job.
• Exit the screen.
• Schedule some job in the cron.
The <add new> entry allows to add more arguments from a list. Selecting each argument will present a list with the available options or an input box, in case the argument's value is open, such as in the case of a job's description.

©XSIBackup-DC: available job arguments

Remove a job

To remove a job, you just have to select the entry in the main job edit view and move the cursor to the [delete job] button. The job will be immediately deleted.

Scheduling a job

Scheduling a job consists in creating the ©XSIBackup-DC job entry in the /var/spool/cron directory and copying that entry to the ©ESXi crontab. Of course you will have to select the different date and time options that will set when the job will be triggered. ©XSIBackup-DC: job cron set time Again from the main job editing window, use the tab key to move to the [Cron sched.] button and press enter. This will open up the screen on the right, which allows to set the time.

Most cron jobs are scheduled daily, if that is the case, just set the time and skip the subsequent screens. You have 5 options at the time to create a cron schedule as per the classic Unix cron design:
1 - Minutes
2 - Hours
3 - DoM or Days of Month
4 - Months
5 - DoW or Day of Week
Skipping any of the screens after the Hours and Minutes selection (previous image) will set an asterisk in the cron entry, which means that the column is not set and thus the job will be executed in all possible periods. Per instance, if you skip the month selection screen, an asterisk will be set to the Month column and the job will be run every month. The same applies to the DoM and DoW columns.

The above is classicly represented in crontabs of Unix and Linux systems with the following schematic text.

©XSIBackup-DC: classic cron explanation ©XSIBackup-DC: job cron set day of month

All screens for the rest of possible cron columns look like the image at the left of this text. You can select one or more values and press [OK] or skip the window to set an asterisk that will ignore the column. At the end of the process the corresponding cron entry will be generated.

Multiple values will be comma separated, like when you choose the job to run in some specific weekdays, which is probably the most used type of cron schedule apart from the everyday schedule.

Running a job multiple times during the day is not supported in the GUI by now. You will have to edit the crontab manually to achieve that.

(*) Users that are not very experienced as sysadmins tend to think in non realistic terms, like: backing up a 4 TB VM every hour or setting endless loops that end up clogging their servers.

Once you finish editing a cron schedule you will see the crontab general view. For that view to show up, you will need to at least have added some cron schedule for some job. When the crontab is empty, it will invite you to add some schedule from the job edit screen first, which looks like the screenshot below. The columns may distort its comtents if you add a lot of entries in one of the fields, don't worry, the crontab will be O.K.

You can from this screen edit or delete any of the entries

©XSIBackup-DC: cron main