The support forum

Command-line control

Aug 15, 2014

Overview


When Bvckup 2 is running, it is possible to control and query the app from command line. For example, it's possible to start a backup job, to check its status or to query whether the app has a valid license.

The app can be controlled from the command line while it's running in both desktop or service mode.

It is possible to lock down the access so that only privileged accounts could access the app through this interface. It is also possible to disable this feature completely.

Version required


This feature was introduced in Release 70 and several new commands were later added in R74.20 and R76.

General syntax


From the command line run:

        bvckup2.exe --command <command> [<arguments>]

If you are using a custom configuration folder, then you will need to pass its location using the -c argument:

        bvckup2.exe --command -c <your-config-path> <command> ...

Completion status


Completion status of a command is returned as a process exit code, which Windows puts in the %errorlevel% variable. For example, if the following script is saved as command.bat:

        echo off
        bvckup2.exe --command %1 %2
        echo %errorlevel%

and then executed:

        command.bat enable "test backup"

it will print:

        0

meaning "OK" if a job called "test backup" was in fact enabled. Otherwise it will print a non-zero number, indicating a failure.

Return codes


Negative return codes come from the "bvckup2.exe --command" process:

        -10 through -60      =>   command syntax error
        -70                            =>   command parameter is too long
        -80 through -100    =>   can't find the process
        -110 through -130  =>   can't connect to the process
        -140                           =>   command aborted
        -150                           =>   timeout waiting for reply (30 sec)

Non-negative return codes come from the main bvckup2.exe process, meaning that it got to see the command and responded to it:

        0                                =>   OK
        1                                =>   Not found
        2                                =>   Bad state
        3                                =>   Not idle
        4                                =>   Bad parameter
        5                                =>   Not found
        100 through 106    =>   backup job status (see below)
        200 and 201            =>   licensing status (see below)

Commands - Job control


Backup jobs can be controlled using "start", "stop", "enable", "disable", "pause" and "resume" commands that do what you'd expect them to do.

Additionally, as of R77.3 it's possible to "delete" and "unload" backup jobs, whereby "delete" is equivalent to deleting a job via the UI and "unload" is a non-destructive variation of "delete" that merely removes the job from the app's run-time list for the duration of current run.

Each command also takes a job description as parameter:

        bvckup2.exe --command start "Daily to NAS"

Job description is the actual "Description" string from the backup's configuration. Alternatively, a job can be specified with its numerical ID:

        bvckup2.exe --command enable job:2

HOWEVER, note that if you re-sort backup tiles in the UI, you may end up with the 1st job sitting in the middle of the list. In other words - use with care.

Finally, as of R77.3 a job can be identified by the name of its folder in Bvckup2\engine directory, e.g.

        bvckup2.exe --command enable etc:backup-0001

Wildcard spec


As of R74.20 it is possible to use * as a job ID:

        bvckup2.exe --command pause *

In this case specified command is applied to all backups in matching state, e.g. "start" will kick off all idle jobs, "pause" will pause all jobs that are running, etc.

Commands - Job status


It is possible to query the exact state of a backup job:

        bvckup2.exe --command status <job>    

which is then returned through exit code as follows:

        100 - disabled
        101 - waiting for device
        102 - idle
        103 - queued to be run
        104 - running
        105 - cancelling
        106 - paused

Commands - Loading a new job


As of R77.3 it's possible to tell the app to pick up a new backup job from Bvckup2\engine folder. It's done with

        bvckup2.exe --command load etc:<job-folder>

This will effectively load the job and schedule it just as if it was present in the config folder when the app was launched.

Commands - General status


As of R74.20, it's possible to check if there are any running jobs or if the app is presently idle:

        bvckup2.exe --command is-idle

will return 0 if the app is idle and non-zero if there are any running backups.

Commands - Graceful shutdown


As of R76, it is possible to initiate graceful shutdown of the app with:

        bvckup2.exe --command terminate

If the app is running in service mode, this command will bring down the service, which will in turn bring down the UI if it's open.

Commands - License status


As of R76, it's possible to check app's licensing status with:

        bvckup2.exe --command is-activated

which will return 0 if the app has a valid, non-expired license (including a trial one), 200 if it's in the process of being activated and 201 if the app is running in "unlicensed" mode.

Commands - License activation


As of R76, the following command can be used to instruct the app to pull down a license using specified activation code:

        bvckup2.exe --command activate <code> [ <inventory-tag> ]

The inventory tag can be specified starting with R77.12. If present, it will be included in activation request. See [1] for more information on tags.

It will return 4 ("bad parameter") if <code> is not specified, 2 ("bad state") if the app is NOT in unlicensed state and 0 otherwise, meaning that it started the activation process.

[1] https://bvckup2.com/support/forum/topic/797/4370

highend :

Aug 15, 2014

Hey,

The status command isn't really working for me (returncode wise).

Profile "Test1"
bvckup2.exe --command start "Test1"
... This profile copies 10GB and is running now (can see it via the animated tray icon) ...
bvckup2.exe --command status "Test1"
echo %errorlevel%
0
... Profile was still running ...

0? It should return 104...

Alex Pankratov :

Aug 15, 2014

Can you search bvckup2.log for "External command" and show me what you see?

highend :

Aug 15, 2014

2014.08.15 20:24:46.840 (UTC+1) 3 00A34 en | External command 00001324 - [status] [Test1]
2014.08.15 20:24:46.840 (UTC+1) 3 00A34 en | External command 00001324 completed with 104

I'm currently using Bvckup2 with the redirect file (C:\Users\myusername\AppData\Local\Bvckup2\redirect.ini)

Maybe that causes this issue?

Alex Pankratov :

Aug 15, 2014

Nope, it shouldn't. It follows the redirects. Does this -

bvckup2.exe --command status "Test1"

echo %errorlevel%


sit in a batch file?

highend :

Aug 15, 2014

Nope. Why does it work if the commands are executed from inside a .bat file but not as single commands from a normal cmd?

Alex Pankratov :

Aug 15, 2014

I'm no Windows shell expert, but I'm guessing %errorlevel% gets reset to 0?

highend :

Aug 15, 2014

I don't know why this should be the case.

E.g. I take the windows version of "curl"
http://curl.haxx.se/dlwiz/?type=bin&os=Win32&flav=-&ver=2000%2FXP

curl.exe abcde
curl: (6) Could not resolve host: abcde

echo %errorlevel%
6

So other applications can return an (the correct) error code...

Alex Pankratov :

Aug 15, 2014

Oh, that's probably because "bvckup2 --command" is not a console, but a windowed process. So launching it from the shell creates a detached process, while launching it from the batch waits for the app to exit and then proceeds with the batch commands.

Alex Pankratov :

Aug 15, 2014

Yup.

C:\Program Files\Bvckup 2>bvckup2 --command status job:1
C:\Program Files\Bvckup 2>echo %errorlevel%
0

  -- vs --

C:\Program Files\Bvckup 2>cmd /c bvckup2 --command status job:1
C:\Program Files\Bvckup 2>echo %errorlevel%
101

highend :

Aug 15, 2014

Ok,

I'll take that as a workaround :)

Tomaz :

Jul 13, 2015

version 74.11

bvckup2 --command pause "jobdesc" does not do anything for me, there is no entry in logs either

Tomaz :

Jul 13, 2015

everything is ok, was looking at wrong location for logs

Bamit :

Oct 10, 2015

Alex,

Will the " --command start * " work if the configuration location as specified in the redirect.ini is NOT the default of %LocalAppData% ?

I have tried several times to run this from the command line but it has not worked.
Note:  the redirect.ini  IS Also  in the   ..\User\AppData\Local\Bvckup2\   directory.

I have tried the following without success:
C:\BIN\Bvckup2\bvckup2.exe -d --command start *
C:\BIN\Bvckup2\bvckup2.exe -c C:\Bin\BvckUp2\Cfg --command start *
C:\BIN\Bvckup2\bvckup2.exe --command start * -c C:\Bin\BvckUp2\Cfg
and even your script of:

@echo off
CD C:\Bin\Bvckup2
bvckup2.exe --command start *    

:again

timeout /t 1 /nobreak >nul
bvckup2.exe --command is-idle
if %errorlevel% neq 0 goto again


In addition to this problem, I found that if you have "run with full admin rights" checked in the preferences you can not automate this at all with
task scheduler or any other call command because it brings up the UAC permissions dialog.

Alex Pankratov :

Oct 10, 2015

Bamit,

Will the " --command start * " work if the configuration location as specified in the redirect.ini is NOT the default of %LocalAppData% ?


It should. Does any other command work as expected? E.g.

    bvckup2.exe --command start "Some job you have"

In other words, is it an issue with "start *" or with any command?

Bamit :

Oct 11, 2015

No, trying individual jobs or * does not work.  I have tried with and without Admin rights set in the preferences and still no success.  If you say it should work then I am sure I am doing something wrong.

Additional info:
Windows 10 Pro i7 920
Backing up to LG NAS
All jobs run correctly when run from GUI.

Alex Pankratov :

Oct 12, 2015

Ok, we'll need to look at the exact error code returned by "bvckup2 --command" then.  Do this - create a batch file and put the following in it -

    echo off
    bvckup2.exe --command %1 %2
    echo %errorlevel%

Then run it with "start SomeJob", whereby SomeJob is one of your jobs, obviously. Don't try with the wildcard though. Let me know what it prints.

Bamit :

Oct 12, 2015

I get -30 as a result.

Hope this helps....

Alex Pankratov :

Oct 15, 2015

-30 means that the command line instance ("bvckup2.exe --command ...") cannot locate the running instance. In particular, it cannot find a named event Bvckup2.etc-xxxx.Command, whereby xxxx is the file system ID of the configuration folder.

This should not be happening. Let me run a couple of extra tests here to try and reproduce this.

Bamit :

Oct 16, 2015

Thanks Alex.  Let me know if you need me to zip up any logs or ini files for you to look at.

Alex Pankratov :

Oct 16, 2015

Bamit, so - no, I cannot reproduce this. Tried everything I could think of and it all worked. Bummer, isn't it? :)

Please email me your %LocalAppData%\Bvckup2\bvckup2.log, details of your config redirect setup and the exact "bvckup2 --command ..." you use that yields -30.

Bamit :

Oct 17, 2015

Thanks Alex, it is On its way to your support address.

fraschizzato :

Nov 11, 2015

There's a way to show remaining time or completed % in command line?

Alex Pankratov :

Nov 12, 2015

No, not at the moment.

HMoradi :

Sep 14, 2017

if the job description contain \ start command will not work
example:
bvckup2.exe --command start "\\192.168.1.8\D$\Steam"

Alex Pankratov :

Sep 14, 2017

I can't reproduce this.

There's no special treatment of \ in job's description, so I can only guess that it's due to some sort of shell escaping or for an altogether unrelated reason.

Are you trying this from Windows regular shell?
What's the "errorlevel" code for the failure?
Is the job you are starting enabled?

I can also have a look at your %LocalAppData%\Bvckup2\bvckup2.log (or the tail part of it that covers the command execution).

HMoradi :

Sep 14, 2017

tested it again
if the job description ends with \ start command will not work
example:
bvckup2.exe --command start "\\192.168.1.8\D$\Steam\"

and can you add a command line to update network password for a job
or at least allow to add plain text password in settings.ini of the job and then bvckup2 encrypt it itself

Alex Pankratov :

Sep 14, 2017

You need to double the trailing slash in quoted strings to offset the effects of Windows shell character escaping. For example, see https://ss64.com/nt/syntax-esc.html, search for "escape can cause".

Re: password change suggestion - noted, let me see what we can do.

Alex Pankratov :

Sep 18, 2017

Re: password change suggestion

In 78.5 - https://bvckup2.com/support/forum/topic/973/5447

HMoradi :

Sep 21, 2017

didn't work password was cleared after loading

example settings.ini
conf._description                                  \\192.168.1.8\D$\Steam\
conf.src                                           E:\Steam\
conf.dst                                           \\192.168.1.8\D$\Steam\
conf.dst_net_user                                  guest
conf.dst_net_pass                                  !SuperSecret
conf.when                                          3
conf.detect                                        0000000f
conf.vss                                           1
conf.deletion                                      1
state.ignore_ctimes_once                           1
misc.version                                       1.78.5.0

Alex Pankratov :

Sep 21, 2017

Argh. You are right, of course. Stand by for a patch...

New topic

Create
Made by Pipemetrics in Switzerland
Support


Follow
Twitter
Dev blog
Miscellanea Press resources
Testimonials
On robocopy
Company
Imprint

Legal Terms
Privacy