msynk/msynk.1.md

% MSYNK(1) msynk 1.1
% Matthias Quintern
% March 2022

# NAME
**msynk** - rsync helper that supports encryption and presets

# SYNOPSIS
| Local:
|    **msynk** [OPTION...] -r DEST_DIR -s SOURCE_DIR PATHS...

| Via remote shell:
|     Push:
|         **msynk** \[OPTION...] -r [USER@]HOST:DEST_DIR -s SOURCE_DIR PATHS...
|     Pull:
|         **msynk** [OPTION...] -r DEST_DIR -s [USER@]HOST:SOURCE_DIR PATHS...

| Using a configuration file:
|     **msynk** [OPTION...] -c CONFIG NAME [SELECTIONS...]

# DESCRIPTION
**msynk** uses *rsync* to synchronise files or directories locally or between devices.
In general, you should always add a trailing '/' to directories.

## Encryption
Files can also be encrypted or decrypted using *mkrypt*. If encryption is used, the files are encrypted to a temporary directory and then synced with *rsync*.
If you sync encrypted files to your system, the encrypted files are transferred with *rsync* to a temporary directory and then decrypted to your filesystem.

## Configuration Files
**msynk** can read from config files usually stored in ~/.config/msynk.
The config files are shellscripts run with bash to set certain environent variables. These are:\
- paths: array containing all paths (relative to sender) that should be synced\
- sender: the parent directory of the paths\
- receiver: the path where the files should be synced to\
- rsync_flags: array containing all the flags for rsync. If you just want to add a flag, use rsync_flags+=(-yourflag)\
- use_encryption: 0 for no, 1 for yes\ 
A template config file is stored in /usr/share/msynk.
You can change the location of the configuration directory by replacing $CONFIG_DIR with your directory in /usr/bin/msynk

### Example
To sync the directories "/home/user/foo" "/home/user/bar" and the file "/home/user/file.txt" to a remote server "user@foobar.com:~/backup" which is available with ssh at port 42, you could have a configuration file "my_backup":\
    sender=/home/user/\
    receiver=user@foobar.com:~/backup/\
    paths=(foo/ bar/ file.txt)\
    rsync_flags+=(--rsh="ssh -p 42")\
You can then run this with: "msynk -c my_backup"\, or if you only want to sync the "foo" directory and ".txt" files: "msynk -c my_backup foo .txt"

# OPTIONS
**-h**, **--help**
: Show a list of arguments.

**--settings**
: Show the current settings.

**-c**, **--config** config-name
: Retrieve settings from a config file in $CONFIG_DIR, eg ~/.config/msynk/*config-name*

**--show-config** config-name
: Print variables defined from a config with *config-name*.

**-s**, **--sender** path
: Set sender to directory. This can also be a remote, like user@domain.com:/dir. Defaults to to the current working directory.

**-r**, **--receiver** path
: Set the receiver directory. All files and directories will be placed inside this directory. This can also be a remote, like user@domain.com:/dir. This option always needs to be set. Note that this directory must already exist if it is on a remote.

**--reverse**
: Swaps sender and receiver. Useful when you want to reverse a config file.

**--encrypt**
: Encrypt files with *mkrypt* before sending them to the receiver.
: The files are encrypted to $TMP_DIR and then synced to the receiver. Does not work with --delete.

**--decrypt**
: Decrypt files with *mkrypt* after receiving them from the sender. Assumes that all files are encrypted and fails if that is not the case. 
: The files are synced to $TMP_DIR and then decrypted to the receiver directory. Does not work with --delete.

**--check-date**
: Can be used with -c and --encrypt or --decrypt: When running **msynk** with a config, the current date is stored in the config file. 
: When running with --check-date, only files that have been modified after the date stored in the config file are processed (by passing--date [date the config was last run] to *mkrypt*). 

**--mkrypt-flag** arg
: Additional argument for *mkrypt*, for example to set the key for the encryption.
: Only pass one argument at a time, so for passing two use '--mkrypt-flag "arg1" --mkrypt-flag "arg2"'

**-d**, **--delete**
: *rsync* --delete option. Deletes all files on the receiver that do not exist on the sender. *msynk* will open *less* with a list of all files that will be deleted and prompt you wether you want continue (unless --skip-dryrun is set)

**--skip-dryrun**
: Can be used with --delete. This skips listing the files that will be deleted and the prompt.

**--rsync-flag** arg
: Additional argument for *rsync*, for example to set the port for the connection. 
: Only pass one argument at a time, so for passing two use '--rsync-flag "arg1" --rsync-flag "arg2"'

**-v**, **--verbose**
: Increase verbosity: Passes -v to rsync and mkrypt.

**--silent**
: Decrease verbosity: Print only error messages and passes --silent to mkrypt.

**--debug**
: Maximum verbosity: -v but also print out rsync and mkrypt commands.

**--exclude**
: Interpret positional arguments as blacklist, not whitelist.

**positional arguments**
: If you are using a config file: pos. args. are strings that have to be contained in a path in order for it to be synced. If no pos. args. are given, all files are synced.
: If you are not using a config file: pos. args. are filepaths relative to the sender directory.

# Troubleshooting
## Not enough space when using encryption
When using --encrypt, the data is encrypted to a temporary directory $TMP_DIR, when using --decrypt the encrypted date is copied to the $TMP_DIR and then decrypted. 
The $TMP_DIR defaults to /tmp/mksynk and /tmp is usually limited to half the size of your memory.
You change the $TMP_DIR in the script in /usr/bin/msynk or temporarily increase the size of the tmpfs by running "sudo mount -o remount,size=XXG,noatime /tmp" if your $TMP_DIR is on /tmp and you have at least XXGB memory+swap space.

# COPYRIGHT
Copyright  ©  2022  Matthias  Quintern.  License GPLv3+: GNU GPL version 3 <https://gnu.org/licenses/gpl.html>.\
This is free software: you are free to change and redistribute it.  There is NO WARRANTY, to the extent permitted by law.