### Links

TimeDicer Website
Online Manual

### Sections

Top of Page

Usage

User Files

Options

Error Codes

TimeDicer.txt Example

Advanced Options

Dependencies

#
Client Manual v8.15 by Dominic Raferd

TimeDicer Client (TimeDicer.cmd) is a Windows command-line program which can perform attended or unattended push backups to a TimeDicer Server, optionally using Windows Volume Shadow Services. It is essentially a Windows wrapper for rdiff-backup. For more information visit https://www.timedicer.co.uk.

## Usage

TimeDicer.cmd [Switches]

## User Files

TimeDicer is normally used with a ConfigFile (default %APPDATA%\TimeDicer\TimeDicer.txt, or as specified with /f option) which should hold

- variable definitions and
- a comma-separated list of source-directories and destination-directories.

For more details about the ConfigFile see below. However TimeDicer can be run purely from the command line using switches. Where there is a configuration file and one or more switches, specification by switch will override a conflicting specification in the configuration file. (There is no command-line equivalent for the contents of the excludelist file.)

TimeDicer requires a private key file (.ppk) created with puttygen. By default this file should be named privatekey.ppk and saved at %APPDATA%\TimeDicer\privatekey.ppk.

A cumulative log file is created (default: %APPDATA%\TimeDicer\timedicer-log.html). With the compare option, the log is also sent to the console.

## Options/Switches

When specified, a command line switch overrides any conflicting setting in ConfigFile:

- /a [yn] : skip rdiff-backup if source has not changed (default y)
- /b name : specify basearchive as name
- /c : compare rather than backup
- /d : force deletion of pre-existing volume shadow sets
- /e file : specify the excludelist file
- /f conf : specify the ConfigFile (default %APPDATA%\TimeDicer\TimeDicer.txt) - this switch, if used, should be put first after /g
- /g : run with debug messages (and pause before backup actually begins) - this switch, if used, should be put first
- /h /? : see these instructions (html)
- /i [yn] : specify whether vss mode is to be used (default y)
- /j : skip initial testing for presence of rdiff-backup on server
- /k key : specify the private key file (default %APPDATA%\TimeDicer\privatekey.ppk)
- /l log : specify the html log file (default %APPDATA%\TimeDicer\timedicer-log.html)
- /o option: specify additional backup options for rdiff-backup (default empty; use quotes for multiple options)
- /n "SourceDirectory1,DestinationRepo1[|Source2,Dest2...]": specify pairs of source drives/directories and destination repositories, source and destination to be separated by a comma and pairs to be separated by a vertical stroke|
- /p number: specify the TimeDicer Server connection port (default 22)
- /q : reduce output messages (quiet)
- /s ip : specify the address (ip) of the TimeDicer Server
- /t : test - do everything except call rdiff-backup
- /u name : specify the user name (default lower case %USERNAME%-%USERDOMAIN%)
- /v : show version of TimeDicer
- /x : if error occurs, exit immediately at end instead of pausing

## Error Codes

- 1: failure at second call of vshadow/vscsc
- 2: unable to access mapped drive - ensure source drive is formatted with NTFS or use add line 'SET vss=n' to configfile
- 3: Windows Volume Shadow Services not operating correctly - if it has worked on this machine before, try rebooting, otherwise do Start/Run services.msc and check for Volume Shadow Copy which should be started, then retry.
- 4: cannot find excludelist file on local machine - check SET excludelist= setting
- 5: missing dependency file
- 7: vshadow/vscsc -da was unable to delete existing shadow copies - reboot to fix
- 8: cannot find private key file on local machine - check SET key= setting and/or .ppk file location
- 9: cannot connect to Server
- 10: cannot find configuration file
- 11: needs to be run with administrative privileges when using VSS
- 12: cannot run under this version of Windows
- 13: cannot complete
- 14: cannot connect to rdiff-backup on Server
- 15: server undefined, or invalid configuration file
- 16: cannot decode short date format
- 17: recovering - cannot identify source directory as one used by TimeDicer
- 18: recovering/listing - an error occurred when recovering, or listing versions of, the specified file
- 19: no valid sources found, please check configuration file
- 20: error at second invocation of vshadow/vscsc - try running with /d option
- 30: error performing rdiff-backup
- 50: error performing rdiff-backup + error with vshadow/vscsc
- 101+: internal error - please report

## TimeDicer.txt Example

    # TimeDicer.txt file - example/template config file

    # Lines that are blank or any text after # on a line are ignored, lines
    # beginning with SET are processed, all other lines are assumed to be part
    # of the list of sources and destinations. The file must terminate with
    # an end-of-line.

    # The only required lines are one beginning SET server= (specifying the address
    # of the TimeDicer Server), and at least one comma-separated line specifying a
    # source folder and destination archive. Even these can be avoided by
    # specifying them on the command line (see above), in which case a
    # configuration file is not needed at all.

    # 'server' is the DNS name or IP address of the TimeDicer Server
    SET server=192.168.100.125

    # 'excludelist' optionally identifies a file which lists (in Windows format,
    # case insensitive) files/paths to be excluded from backup e.g. thumbs.db.
    # Each file/path should appear on a separate line in the file. Do not begin
    # or end an entry in the list with * as this is prefixed/suffixed
    # anyway, and do not use quotes. So a line:
    #   "C:\Documents And Settings\Fred\My Documents\thumbs.*"
    # should instead be written as:
    #   C:\Documents And Settings\Fred\My Documents\thumbs.
    # or even:
    #   thumbs.
    # (which will exclude all files or paths which contain the text 'thumbs.')
    #SET excludelist=c:\exclfolders.txt

    # Backups:a comma-separated list of source directories and their
    # destination archive names, with an optional third field holding extra
    # parameters to be added to the rdiff-backup command line (these appear before
    # any 'excludelist' and 'options' parameters and thus are processed after
    # them). Environment variables can be used as shown below. Source
    # directories should not have surrounding quotes, nor a terminating backslash.
    %USERPROFILE%\My Documents,mydocs,--exclude "**/*.accd?" --exclude **/*.md?
    %USERPROFILE%\Desktop,desktop
    c:\Utils,utils
    c:\Bas,bas

## TimeDicer.txt file - Advanced Options

You will not normally need to use these more advanced options:

    # 'user' is the login name of the user on the TimeDicer Server, it is
    # optional and defaults to lower-case %USERNAME%-%USERDOMAIN% with
    # any spaces stripped. 'user' must not contain spaces
    SET user=fred

    # 'key' is ppk file (created with Puttygen and containing private key - the
    # corresponding public key must be saved on the TimeDicer Server in
    # ~/.ssh/authorized_keys). For TimeDicer to run unattended, the public key
    # must be saved without passphrase. 'key' is optional; if not supplied it
    # defaults to %APPDATA%\TimeDicer\privatekey.ppk, or if this is not found
    # then %USERPROFILE%\privatekey.ppk.
    SET key=C:\Documents and Settings\Fred\mykey.ppk

    # 'port' is the ssh port to reach the TimeDicer Server, default 22.
    SET port=21

    # 'basearchive' is optional, all archive destinations will have this prefix.
    # Unless 'basearchive' starts with / it will be defined in relation to the home
    # directory of the user on the TimeDicer Server; if it is undefined, archives
    # will be directly located in that home directory. If using ecryptfs under
    # Ubuntu then 'basearchive=Private' should provide good protection against data
    # theft resulting from physical theft of the TimeDicer Server, but it does not
    # prevent the administrator of the TimeDicer Server (superuser) getting access
    # to your data. 'basearchive' is case sensitive.
    SET basearchive=archives/

    # 'options' is optional (default: empty) and contains additional command-line
    # options for rdiff-backup backup action, it appears before 'excludelist' and
    # thus is processed after it. The following are automatically applied anyway:
    # --create-full-path --no-acls --no-hard-links --print-statistics
    # --remote-schema
    SET options=--compare-inode

    # 'vss' is optionally y or n (default: y) -  set to n to disable Volume Shadow
    # Services. You need to do this is if the source drive is formatted with FAT32
    # (or FAT), uses EFS, or is a not a local drive.
    SET vss=n

    # 'skip_on_no_change' is optionally y or n (default: y) - set to n to disable
    # skipping of backup if the source data has not changed since last time. After
    # each run TimeDicer records the date of each successful backup and if
    # 'skip_on_no_change' is 'y' then it looks for changes in the source data
    # (using xcopy) since [and including] that date. Backup is skipped if there
    # are no changes. This can avoid bloating of backups on the TimeDicer Server
    # especially with sources that rarely change.
    SET skip_on_no_change=n

    # 'skip-rdiff-backup-test' is optionally y (default: n) - this forces TimeDicer
    # to skip initial testing for ssh access to the server, for /home/tmp and for
    # a valid version of rdiff-backup on the server. This can be helpful if you
    # restrict access rights to the server, for instance if you permit the user
    # only to run 'rdiff-backup --server', and no other commands,
    # by adding a suitable line to their .ssh/authorized_keys file.
    SET skip-rdiff-backup-test=y

    # 'log' optionally defines the location for TimeDicer's log file and it defaults to
    # %APPDATA%\TimeDicer\timedicer-log.html. If you do not want a log set it to NUL.
    SET log=J:\mylog.htm

    # 'rdiffbackup_on_client' (default: rdiff-backup.exe) optionally defines the
    # name of the rdiff-backup program to be run on this client
    SET rdiffbackup_on_client=rdiff-backup-1.3.3.exe

    # 'rdiffbackup_on_server' (default: rdiff-backup) optionally defines the
    # name of the rdiff-backup program to be run on the server
    SET rdiffbackup_on_server=rdiff-backup-1

## Dependencies (all free) software

- On Linux server:

- rdiff-backup
- openssh

- On Windows client (in same folder as TimeDicer):

- rdiff-backup.exe (Windows port)
- Microsoft Visual C++ 2008 Redistributables
- ssed.exe (Windows port of sed)
- plink.exe
- and if you wish to use Volume Shadowing with NTFS (recommended) you also need:

- vscsc.exe (but instead you actually need the vshadow program provided with TimeDicer client)
- dosdev.exe

If the instructions at the TimeDicer website are followed, all dependencies are met automatically. In any case, TimeDicer Client performs checks for its dependencies before starting backup.

Questions? Send an email to Dominic Raferd dominic@timedicer.co.uk