README.md 5.79 KB
Newer Older
Yuanle Song's avatar
Yuanle Song committed
1
2
3
4
5
6
mbackup for windows
====================

Intro
------
mbackup is a file backup tool based on [rsync](https://rsync.samba.org/).
Yuanle Song's avatar
Yuanle Song committed
7
8
9
It supports backup a list of files and directories to local directory or
remote ssh node. Since mbackup is based on rsync, it supports incremental
backup efficiently.
Yuanle Song's avatar
Yuanle Song committed
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

Difference with rsync: rsync doesn't have an official windows build.  rsync
doesn't support windows style path in source, target, and file lists.  You can
run rsync in cygwin or msys2 shell. But usually it's painful to run it in
windows cmd or powershell directly. Mbackup is a thin wrapper around rsync,
with support for windows style path and bundled openssh client.

Installation
-------------

mbackup is written in F# and C# in dotnet core 3.

To install mbackup, get .NET Core Installer and .NET Core Desktop Installer
from [dotnet core 3](https://dotnet.microsoft.com/download/dotnet-core/3.0)
and install both.

Get mbackup msi installer from
Yuanle Song's avatar
Yuanle Song committed
27
https://blog.emacsos.com/mbackup-for-windows.html and run it. I don't have a
Yuanle Song's avatar
Yuanle Song committed
28
29
30
31
32
33
34
35
36
37
key to sign the exe, you should verify sha256sum if you worry about file
integrity.

Backup List and Exclude lists
------------------------------
By default, the following files are backed up by mbackup:

   - C:\ProgramData\mbackup
   - C:\Docs
   - D:\Docs
Yuanle Song's avatar
Yuanle Song committed
38
39
40
41
42
   - Documents
   - Desktop
   - Downloads
   - Pictures\Saved Pictures\
   - <dot files> in %userprofile%
Yuanle Song's avatar
Yuanle Song committed
43
44
45
46
47
48
49
50
51
52

By default, some files are ignored, such as iso, rar, zip, exe etc. mbackup is
designed to backup user created contents, not downloaded contents. That's why
archives and executables are excluded by default.

You can add more dirs to backup in %programdata%\mbackup\local-list.txt

Here are the backup list files and exclude pattern files:

   - backup file list
Yuanle Song's avatar
Yuanle Song committed
53
54
55
     - %programdata%\mbackup\default-list.txt
     - %programdata%\mbackup\user-default-list.txt
     - %programdata%\mbackup\local-list.txt (managed by user)
Yuanle Song's avatar
Yuanle Song committed
56
57

   - exclude pattern
Yuanle Song's avatar
Yuanle Song committed
58
59
     - %programdata%\mbackup\default-exclude.txt
     - %programdata%\mbackup\local-exclude.txt (managed by user)
Yuanle Song's avatar
Yuanle Song committed
60

Yuanle Song's avatar
Yuanle Song committed
61
local-list.txt and local-exclude.txt are managed by user. mbackup will not
Yuanle Song's avatar
Yuanle Song committed
62
63
64
65
66
67
68
69
70
71
72
73
modify those files when it is uninstalled or upgraded. The other lists are
shipped with mbackup and will be removed/overwritten when
uninstalling/upgrading mbackup.

To learn more about file list and exclude patterns, read rsync man page
https://download.samba.org/pub/rsync/rsync.html --files-from option,
--exclude-from option, and INCLUDE/EXCLUDE PATTERN RULES section.

How to Invoke mbackup
----------------------

mbackup for windows is designed to run automatically in the background via
Yuanle Song's avatar
Yuanle Song committed
74
75
76
Windows Task Scheduler (Win+R taskschd.msc). You can also run it from windows
cmd or powershell to trigger a backup immediately (or test setup or do initial
backup).
Yuanle Song's avatar
Yuanle Song committed
77
78
79
80

For the automatic backup to work, you need to specify a target in mbackup
config file.

Yuanle Song's avatar
Yuanle Song committed
81
82
Open mbackup config file in any text editor,
Win+R %programdata%\mbackup\mbackup-config.txt,
Yuanle Song's avatar
Yuanle Song committed
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

To backup to local disk, add config

    target=D:\backup

Replace D:\backup with the dir you want to save backup files to.

To backup to remote ssh node, add config

    target=user@somehost.example.com:/path/to/dir
    ssh-key=D:\path\to\id_rsa

Replace ssh-key path with your ssh private key. Since mbackup is designed to
run in the background, only ssh key based authentication (with no passphrase)
is supported. If you use password to login your server, you may learn
[how to set up ssh keys](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2).

Save mbackup-config.txt file, now auto backup will work. The default scheduler
Yuanle Song's avatar
Yuanle Song committed
101
runs mbackup 15 minutes after user logon and every 2 hours during
Yuanle Song's avatar
Yuanle Song committed
102
103
daytime. You can open Task Scheduler to check the scheduler.

Yuanle Song's avatar
Yuanle Song committed
104
Here is how to run mbackup in cmd or powershell:
Yuanle Song's avatar
Yuanle Song committed
105
106
107
108
109
110
111
112
113
114
115
116
117
118

    %programfiles%\mbackup\publish\mbackup.exe --help
	%programfiles%\mbackup\publish\mbackup.exe

You can also drag the mbackup shortcut to cmd window:

    C:\Users\Public\Desktop\mbackup.lnk --help
    C:\Users\Public\Desktop\mbackup.lnk

You can also click mbackup.exe shortcut on desktop or start menu. The downside
is the window will auto close after mbackup finishes.

You can check mbackup run log in %localappdata%\mbackup\mbackup.log

119
120
121
122
123
124
125
126
127
128
129
130
Developer Notes
----------------

dotnet core 3 SDK and GNU make is required to build this project.

mbackup-for-windows includes the following components

    mbackup          a dotnet core console project written in F#, it parses command line arguments, parse mbackup config files and runs rsync.
	mbackup-tests    unit tests for mbackup. in F#.
	mbackupw         a winforms project written in C#, it is a winforms application just used to call mbackup, but do not show cmd.exe window. This is used in Windows Task Scheduler.
	mbackup.wxs      wix xml configuration to create msi installer
    Makefile         used to build the project
Yuanle Song's avatar
Yuanle Song committed
131
	mbackup-config/  default mbackup config files
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

See ./operational file for design notes, dev instructions and some development
history.

mbackup-for-windows version is set in mbackup.fsproj file.

To build the project:

    make build

To run tests:

    make test

To create a msi release:

    make dist

Yuanle Song's avatar
Yuanle Song committed
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
License
--------

Copyright (C) 2019  Yuanle Song <sylecn@gmail.com>

This file is part of mbackup-for-windows.

mbackup-for-windows is free software: you can redistribute
it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any
later version.

mbackup-for-windows is distributed in the hope that it will
be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public
License along with this program.  If not, see
<https://www.gnu.org/licenses/>.