Command Line Interface Specification Linux Mac
Online Backup Client version 4.1.x and higher
1. Introduction
These modifications make it possible to access the BackupAgent Client software from the
command line. The following actions will be implemented: backup, delete, dir en restore. These
actions will be described in more detail in the following paragraphs.
For all actions applies that a successful action is indicated by means of exit code 0. In all other
cases a status code of 1 will be used.
2. Configuration
The command line client does not need any configuration for it to function properly. All necessary
information required to complete a given action is supplied via command line options. The
default values for options otherwise configurable via the full BackupAgent client should be such
that these are satisfactory in the majority of installations.
However, to allow the user to modify the values of options that cannot be set via a command line
option, the command line client is able to read default values from a configuration file. When
used, this configuration file is expected to reside in one of the following folders: application
installation location or the config folder in the application installation location.
If the command line client detects a configuration file in one of the aforementioned folders, it will
load and process the contents of this configuration file before processing the command line
options. If an error is found in the configuration file, the command line client will issue an error
message describing which value, setting or option is causing the error and terminate with an exit
value of 1. In addition, the error message will specify the line on which the error was detected
and the full path to the configuration file the error was found in.
1
3. Backup
This action makes it possible to perform a command line backup. The following arguments will
be used:
java -jar cli.jar backup -login <login name> -pass <login>
-key <key> -server <server address> [-uid <unique id>] [-r] –retention:<retention value> file1 file2
…<path to folder or file>
3.1 Arguments explained
-login <login name>
This is the login name of the user. The user name has a minimum length of 6 characters and a
maximum length of 150 characters. The user name must start with an alphanumerical character
and may contain one or more of the following characters: !#$%&()+,-.;@'~[]{}_\` and may include
whitespace. If the login name contains any special characters (any characters that may be
interpreted by the shell such as the pipe character, whitespace, semi-colon, double-colon,
percent and dollar signs, etc…), the login name should be placed within quotes.
-pass <password>
This is the password for the specified login name. The password has a minimum length of 6
characters and a maximum length of 20 characters. If the password contains any special
characters (any characters that may be interpreted by the shell such as the pipe character,
whitespace, semi-colon, double-colon, percent and dollar signs, etc.), the password should be
placed within quotes.
-key <key>
This is the encryption key of the user. The encryption key will be used to encrypt the stored files.
The encryption key has a minimum of 6 characters and a maximum of 40 characters. Only alpha-
numerical characters are allowed.
-server <server address>
2
The network address or domain name of the BackupAgent Server specified
as https://<servername>.
-uid <unique id>
This is an optional unique identification number. When specified, this value will be used instead
of the computer name to identify the files of the user. This allows the user to access the stored
files from different locations. Only alpha-numerical characters, underscore (_) and hyphen (-) are
allowed.
-task <task name>
This is the name of the task that needs to be executed. The actual task definition is read by the
agent from the xml file containing the task definitions1, and this file is expected to reside in one
of the following folders: application installation location, the config folder in the application
installation location or the current directory. If the task definition file cannot be found, the client
must issue a proper error message and terminate with an exit value of 1. This argument is
optional but mutually exclusive when specifying a list of files and/or folders to be backed up.
However, either this option or the list of files and/or folders must be specified
1
The command line client does not offer functionality to create such a task definition. It is
assumed that the actual task definition has been created by the user, either by using a properly
installed version of the OnlineBackupClient software or by manually creating the correct
definition via a text editor. The Task.xml file needs to be placed in the ../CommandLine/store
folder.
-r
When specifying a list of files and/or folders to be backed up, this argument specifies to
recursively backup the contents of a folder. This argument is optional but mutually exclusive with
the -task command line option.
-retention <retention value>
This retention value is an optional value and it defines the numbers of days the data must be
kept. If not specified, the value will be 30.
3
file1 file2 …
Value
Meaning
0
Completed successfully
1
Command line error or unknown error
2
Completed successfully with skipped resources
3
Completed successfully with not found resources
4
Completed successfully with not found resources and skipped resources
5
Completed unsuccessfully
6
Completed unsuccessfully with skipped resources
7
Completed unsuccessfully with not found resources
8
Completed unsuccessfully with not found resources and skipped resources
9
User canceled
This argument specifies a list of files and/or folders to be backed up. Multiple files and/or folders
are separated with any amount of whitespace. It is the user’s responsibility to properly quote any
file or folder name containing embedded whitespace or other special characters. If the optional
-r option is specified, all specified folders will be backed up recursively. The use of relative paths
is allowed and will be treated properly by the agent (this means that the agent will fully resolve
any relative path into the correct absolute path and automatically compress any redundant path
components). This argument is optional but mutually exclusive with the task command line
option. However, either this option or the -task option must be specified.
3.2 Output
As output and when the command progresses, the backup command will print the list of files
backed up on standard output, one line for each file (the full path will be shown). When the
backup completed successfully, it will print ‘backup completed successfully’ and exit with a status
value of 0. If during the backup problems are encountered with files and/or folders which cause
these items to be skipped, an appropriate notification (including the full path) must be printed to
standard error. If an error was encountered during the backup, a detailed error message must
be printed to standard error and the client must exit with an appropriate exit value according to
the following list:
4
If neither the -task or a set of files and/or folders was provided on the command line, the client
must inform the user that a required option is missing and that either the -task option must be
used or a list of files and/or folders must be specified.
4. Delete
This command makes it possible to delete files and directories of the BackupAgent Server.
Java -jar cli.jar delete -login <login name> -pass <password>
-server <server address> [-version [all|last|<number>]]
-input <file> | <file> <file> ...
4.1 Arguments explained
-login <login name>
This is the login name of the user. See the backup command for more information.
-pass <password>
This is the password for the specified login name. See the backup command for more
information.
-key <key>
This is the encryption key of the user. See the backup command for more information.
-server <server address>
This is the network address or domain name of the BackupAgent Server.
For example: http:--<server name> or https:--<server name>
-version [all | last | <number>]
5
An optional parameter specifying which version of a file has to be deleted. There are 3 possible
values for this parameter:
Version all: specifies that all versions of the file have to be deleted.
Version last: specifies that the last version of a file has to be deleted.
Version <number>: specifies that the defined version has to be deleted.
When version is not specified -version all is assumed.
-input <file>
This option specifies that the list of files to be deleted must be read from the given file. This option
may be useful if a large number of files need to be removed. The input file must be structured as
follows:
<version> <path>
<version> <path>
…
Where <version> is one of all, last or a number (see the -version command line option for more
information), and <path> is the full path to a file or folder that must be deleted. Please note that
the -input command line option is mutually exclusive with a list of files specified on the command
line.
File file....
This is the name or names of files and/or directories that need to be deleted. The name should
contain the whole path where the directory or file is located. The server will stop the operation if
the user tries to delete a file or directory which is not located on the server.
4.2 Output
As output, the delete command will print the list of deleted files or folders on standard output,
one line for each file (the full path will be shown). When the delete completed successfully, it will
print ‘delete completed successfully’ and exit with a status value of 0. If an error is encountered
6
during the delete, an appropriate error message will be printed to standard error and the client
will exit with a status value of 1.
5. Dir
This command makes it possible to display one or multiple directories on the BackupAgent
Server. It is even possible to see if this file exists by using this command:
Java -jar cli.jar dir -login <login name> -pass <password>
-server <server address> [-r[:<depth>]] [-l|-s] <file>
5.1 Arguments explained
-login <login name>
This is the user login name of the user. See the backup command for more information.
-pass <password>
This is the password of a user. See the backup command for more information.
-key <key>
This is the encryption key of the user. See the backup command for more information.
-r [:depth]
This option request a recursive list of the content of the defined file. This option would be only
efficient when the defined file represents a directory. The optional number specifies the
maximum recursion depth. For example, a value of 1 specifies a listing of the specified folder
only, a value of 2 specifies that the listing may be two levels deep. Please note that the recursive
directory listing will always result in full paths to be listed on the output. If this option is not
specified a non-recursive listing of the specified folder or file will be returned.
-l
7
This option will display the long File version. This option is mutually exclusive with the -s
command line option. This option is implied unless the -s option is provided.
-s
This option will display the short File version. This option is mutually exclusive with the -l
command line option.
File
This is the name of the file or folder that needs to be displayed. When a file or directory does not
exist, the server will respond with the following message: “file or folder not found” and the
application will be closed. When no file or directory is defined then the server could response
with the message “file or folder not found” message (this could be caused when no backup has
been made).
5.2 Format long File version
The long version will display the result in the following format:
<type>|<name>|<size in bytes>|<date created>|<date changed>|<version#>
The type indicator indicates if a field has to be displayed as a file or directory. Possible values are:
F (File)
D (Directory)
For a single-directory listing, the name will only contain the name of a file or directory and will
not contain the path. For a recursive directory listing the name will contain the full path. If the
name contains a “|” then the “|” will be replaced with a “\|”. As example “something|something”
will be replaced with “something\|something”. It is the choice of the user to delete the backslash.
The size of a file will be displayed in bytes. The size of a directory will be displayed in 0 bytes.
The date created and date changed displays the date when a file has been created or changed.
The directories will contain date created and date changed with the value 0. The date format for
files will be MM-DD-YYYY HH:MM:SS.
8
The version number will define the file version. Most of the files will have version 1. Directories
will always have version 1.
5.2.1 Examples
The request to display the top of the backup tree for the user test on backup server 10.0.0.1 is:
C:\>OnlineBackupAgent dir -login test -pass test -server 10.0.0.1 -l
d|DMA_684|0|0|0|1
d|MIJN_PC|0|0|0|1
C:\>
The request to display the top of the backup tree with the unique identification DMA_684 is:
C:\>OnlineBackupAgent dir -login test -pass test -server 10.0.0.1 -l DMA_684
d|C_Root|0|0|0|1
d|D_Root|0|0|0|1
d|X_Root|0|0|0|1
C:\>
The request of the backup tree under DMA_684-C_Root (for example the C-drive of a scan pc for
the user of the DMA application with client number 684 displays) is:
C:\>OnlineBackupAgent dir -login test -pass test -server 10.0.0.1 -l DMA_684-C_Root
d|Program Files|0|0|0|1
d|Documents and Settings|0|0|0|1
f|msizap.exe|94720|02-17-2007 15:03:48|02-17-2007 15:03:48|1
f|pagefile.sys|603979776|10-01-2007 13:29:42|10-29-2007 01:14:07|1
9
f|pagefile.sys|515263981|10-01-2007 13:29:42|10-30-2007 14:56:37|2
C:\>
5.3 Format short File version
The short version will display the result in the following format:
<type>|<name>
The type indicator indicates if a field has to be displayed as a file or directory. Possible values are:
F (File)
D (Directory)
For a single-directory listing, the name will only contain the name of a file or directory and will
not contain the path. For a recursive directory listing, the name will contain the full path. If the
name contains a “|” then the “|” will be replaced with a “\|”. As example “something|something”
will be replaced with “something\|something”. It is the choice of the user to delete the backslash.
6. Restore
This action makes it possible to perform a restore by using the command line.
Java -jar cli.jar restore -login <login name> -pass <password> -key <key>
-server <server address> [-version [all|last|<number>]]
[-dest <destination location>] -input <file> | <file> <file> ...
6.1 Arguments explained
-login <login name>
This is the user login name of the user. See the backup command for more information.
-pass <password>
10
This is the password of a user. See the backup command for more information.
-key <key>
This is the encryption key of the user. See the backup command for more information.
-server <server address>
This is the network address or domain name of the BackupAgent Server.
As example: http://<server name> or https://<server name>
-version [all | last| <number>]
This optional parameter specifies which version of a file has to be restored. There are 3
possibilities for this parameter:
Version all: specifies that all versions of the file has to be restored.
Version last: specifies that the last version of a file has to be restored.
Version <number>: specifies that the version that the defined version has to be restored.
When a user uses -version all then all versions of a file will be stored. This will be done such as
<file>.1 <file> 2 etc. If this option is not used -version last is assumed. This parameter is ignored
when the -input parameter is used.
-dest <destination location>
This parameter defines the location on the file system where the requested files have to be
restored. This must be an existing location on the file system. The client will use the original
location when a user does not specify this.
-input <file>
This option specifies that the list of files to be restored must be read from the given file. This
option may be useful if a large number of files needs to be restored. The input file must be
structured as follows:
<version> <path>
11
<version> <path>
Value
Meaning
0
Completed successfully
1
Command line error or unknown error
2
Completed successfully with skipped resources
3
Completed successfully with not found resources
4
Completed successfully with not found resources and skipped resources
5
Completed unsuccessfully
6
Completed unsuccessfully with skipped resources
7
Completed unsuccessfully with not found resources
8
Completed unsuccessfully with not found resources and skipped resources
9
User canceled
Where <version> is one of all, last or a number (see the -version command line option for more
information), and <path> is the full path to a file or folder that must be restored.
Please note that when the -input command line option is mutually exclusive with a list of files
specified on the command line.
file file ....
This is the list of files that must be restored. The specified names must contain the whole path.
Please beware that if a filename contains whitespace or any other characters that have a special
meaning to the command shell, the filename must be placed within double quotes.
6.2 Output
As output, the restore command will print the list of restored files and folders on standard output,
one line for each file (the full path will be shown). When the restore completed successfully, it will
print ‘restore completed successfully’ and exit with a status value of 0. If an error is encountered
during the restore, an appropriate error message will be printed to standard error and the client
will exit with an appropriate exit value as follows:
12
Loading...