Powershell Backup Script
------------------------

This is a simple backup script write in Powershell for Microsoft Windows. It
needs `7za` and `rclone` executable into the `./bin` directory to work properly.

You must configure it with JSON files, one example is provided in
`./etc/example.json`.

## usage

```
powershell -File backup.ps1 [-conf ./etc/example.json] [-log ./log/example.log] [-debug]
```

 - `-conf` : configuration file (JSON), default `./etc/backup.json`
 - `log` : log file, default `$false`
 - `-debug` : verbose output on stdout (not log file)

## Configuration example

Here is the `example.json` file :

```json
{
    "actions" : 
    [
        {
            "name" : "document_backup",
            "source" : "C:\\Users\\people\\document",
            "source_eval" : false,
            "dest" : "\\\\backup_srv\\srv01\\",
            "type" : "compress",
            "options" : {
                "-mx" : 3,
                "-mmt" : 4,
                "-xr@" : "C:\\backup\\etc\\7z\\exclude.txt"
            },
            "hook_postexec" : "<command>",
            "username" : "bkp_example",
            "pass" : "<secure_string>"
        },   
        {
            "name" : "project_copy",
            "source" : "C:\\Users\\people\\project",
            "dest" : "X:\\",
            "type" : "clone",
            "options" : {
                "--exclude" : "*.zip"
            }
        },
        {
            "name" : "database_backup",
            "source" : false,
            "dest" : "X:\\databases",
            "type" : "dump_mssql",
            "options" : {
                "server": "srv_host",
                "instance" : "SQL2016",
                "databases": "mydatabase",
                "compression" : false 
            }
        }
    ]
}
```

All actions performed by the script are defined by `actions [...]` object :

 - `name` : name of the action, it will be use as filename for the `.zip` output
     in `compress` type (see below)
 - `source` : the source path, can be `{{tmpdir}}` to give the temporary folder
     or a powershell expression if `source_eval` is set to `true`
 - `source_eval` : evaluate the powershell expression in source, for example
     `$env:HOMEDATA\Music` will be interpreted as `C:\Users\name\Music`
 - `dest` : the destination path, can be a network path (like `\\<host>\<path>`
     ) can be `{{tmpdir}}` to give the script temporary folder.
 - `type` define the action, action is represented by a powershell module file
     in `lib/` directory
 - `options` : options for the module
 - `hook_postexec` : Powershell command to execute when current action is 
      terminated
 - `username` : user name for destination network share (if needed)
 - `pass`: password for destination network share (if needed)


## Modules

This script works with Powershell modules located in `lib/` directory. Here is
the list of defaults module

### `clone` : Clone a directory

This module Clone a directory from `source` to `dest`. It use
[rclone][l_rclone] so you can add rclone command line parameters in `options`.

### `compress` : Compress files / directory

This module create a compressed file in `dest` with `source`. It use
[7zip][l_7zip] so you can add `7za` command line parameters in `options`. 

### `dump_mssql` : Dump MSSQL database(s)

This module backup Microsoft SQL Server databases, for this one, `source` must
be `false`. Here are json options :

 - `server` : MSSQL Server, required parameter (localhost doesn't work 😢)
 - `instance` : Server instance, required parameter
 - `compression` : activate compression output (zip format - default `false`)
 - `databases` : list of databases to be backuped (default all)

You must execute backup script with an user that have the right of backupping
MSSQL databases. For now, authentication for databases export is not supported.
The user that run the MSSQL daemon must have right to access destination path.

## temporary folder

You can use `{{tempdir}}` in `source` or `destination` to specify a temporary
directory (formely `<script_folder>\tmp`). This can be useful, for example, when
you want to dump database but use 7zip to compress them :

 - first action dump databases to `{{tempdir}}`
 - second action compress files in `{{tempdir}}` to final destination

## Password for network share

In this script, network share need a password. `password` **must be created on
the machine** and tha **user account** which execute the script with following
command

```powershell
"PassW0rd" |  ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString
```
Copy-paste the result in your json file into `pass` (in example, replace
`<secure_string>`).

## Log

This backup script log information to your terminal, but it can also log to a
file, useful when you execute it in scheduled task for example. Log are in the
`log/` directory. Script create a logfile per day named with the configuration
file basename plus date of execution (eg `example.20210112.log`)

If a logfile is older that 15 day, it will be move to a compressed file
(`example.log.archives.<year>.<month>.7z`)

## disclaimer

Until I'm a Linux/*BSD system administrator, I'm not too familiar with Windows
system, in particular with MSSQL command line backup tool. So I could do some
misktakes, if i do then you can contact me on the fediverse at
[@ephase@toot.aquilenet.fr][l_fediverse] (and if you have some questions, bug 
reports, suggestions too).

## Licence

This script is released under le [MIT licence][l_mit]

Copyright © 2021 Yorick Barbanneau

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice (including the next
paragraph) shall be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[l_rclone]:https://rclone.org
[l_7zip]:https://www.7-zip.org/
[l_fediverse]:https://toot.aquilenet.fr/@ephase
[l_mit]:https://opensource.org/licenses/mit-license.php