diff --git a/USAGE.md b/USAGE.md index 0b66097..1e55e72 100644 --- a/USAGE.md +++ b/USAGE.md @@ -31,17 +31,19 @@ and responsiveness. # SETUP -`/etc/asd.conf` contains all user-managed settings. The configuration file -location can be overridden by specifying a pathname in the `ASDCONF` -environment variable. For instance, to load `asd` settings from +The `asd` configuration file contains all user-managed settings. See the entry +on `ASDCONF` in the [`ENVIRONMENT VARIABLES`](#environment-variables) section +for information on the default `asd` configuration file location. The +configuration file location can be overridden by specifying a pathname in the +`ASDCONF` environment variable. For instance, to load `asd` settings from `/here/for/some/reason/lives/asd.conf`: ```shell-session $ ASDCONF=/here/for/some/reason/lives/asd.conf asd ``` -**Note** that edits made to `/etc/asd.conf` while `asd` is running will be -applied only after `asd` has been restarted. +**Note** that edits made to the `asd` configuration file while `asd` is running +will be applied only after `asd` has been restarted. In the `asd` configuration file, you may define the following variables: @@ -56,8 +58,10 @@ In the `asd` configuration file, you may define the following variables: : A path that lives on a tmpfs or zram mount. This is where `asd` will store the data eventually synchronized back to the physical disk. By default, - `asd` sets `VOLATILE=/tmp`. **Note** that it is a fatal error to set - `VOLATILE` to a path that does not live on a tmpfs or zram mount. + when running as `root` and `ASDNOV1PATHS` is unset or set to a false value, + `asd` sets `VOLATILE=/tmp`. Otherwise, `VOLATILE` defaults to `ASDRUNDIR`. + **Note** that it is a fatal error to set `VOLATILE` to a path that does not + live on a tmpfs or zram mount. `USE_OVERLAYFS` @@ -79,12 +83,12 @@ In the `asd` configuration file, you may define the following variables: : A boolean variable controlling whether to issue debugging output. -**Note** that the default value of `/tmp` should work just fine for the -`VOLATILE` setting. If using [`bleachbit`][BleachBit], do NOT invoke it with -the `--clean system.tmp` switch or you will remove a key dot file (`.foo`) from -`/tmp` that `asd` needs to keep track of sync status. Also note that using a -value of `/dev/shm` can cause problems with systemd's `NAMESPACE` spawning only -when users enable the OverlayFS option. +**Note** that the default values of `/tmp`/`ASDRUNDIR` should work just fine +for the `VOLATILE` setting. If using [`bleachbit`][BleachBit], do NOT invoke +it with the `--clean system.tmp` switch or you will remove a key dot file +(`.foo`) from `/tmp` that `asd` needs to keep track of sync status. Also note +that using a value of `/dev/shm` can cause problems with systemd's `NAMESPACE` +spawning only when users enable the OverlayFS option. Example: @@ -110,33 +114,38 @@ WHATTOSYNC=( `ASDCONF` -: Path to the `asd` configuration file. Defaults to `/etc/asd.conf` when - `ASDNOV1PATHS` is disabled; otherwise, defaults to `${ASDCONFDIR}/asd.conf`. +: Path to the `asd` configuration file. Defaults to `/etc/asd.conf` when `asd` + is running as `root` and `ASDNOV1PATHS` is unset or set to a false value; + otherwise, defaults to `${ASDCONFDIR}/asd.conf`. `ASDNOV1PATHS` : A boolean variable controlling whether to use "version 1" paths or not. When set to a false value, `asd` will use old-style defaults for its daemon file - (`/run/asd`), lock file (`/run/asd-lock`), configuration file - (`/etc/asd.conf`) . **NOTE** that this variable is - ignored when `asd` is running as a non-`root` user. Defaults to disabled - (effectively, `ASDNOV1PATHS=0`). + (`/run/asd`), lock file (`/run/asd-lock`), and configuration file + (`/etc/asd.conf`). **NOTE** that this variable is ignored when `asd` is + running as a non-`root` user. Defaults to disabled (effectively, + `ASDNOV1PATHS=0`). `ASDCONFDIR` : Parent directory of `asd.conf` if `ASDCONF` is not defined. Ignored when running as `root` and `ASDNOV1PATHS` is unset or set to a false value. - Otherwise, defaults to `CONFIGURATION_DIRECTORY` (which is set when `asd` - runs under systemd), falling back to `/etc/asd` when running as `root` and - `${XDG_CONFIG_DIR}/asd` when running as a non-`root` user. + Otherwise, defaults to the first (leftmost) of the colon-separated paths in + the `CONFIGURATION_DIRECTORY` environment variable (which is set when `asd` + runs under systemd and the `asd.service` unit defines at least one + `ConfigurationDirectory` entry), falling back to `/etc/asd` when running as + `root` and `${XDG_CONFIG_DIR}/asd` when running as a non-`root` user. `ASDRUNDIR` : Directory where `asd` should store runtime state. Ignored when running as `root` and `ASDNOV1PATHS` is unset or set to a false value. Otherwise, - defaults to `RUNTIME_DIRECTORY` (which is set when `asd` runs under systemd), - falling back to `/run/asd` when running as `root` and - `${XDG_RUNTIME_DIR}/asd` when running as a non-`root` user. + defaults to the first (leftmost) of the colon-separated paths in the + `RUNTIME_DIRECTORY` (which is set when `asd` runs under systemd and the + `asd.service` unit defines at least one `RuntimeDirectory` entry), falling + back to `/run/asd` when running as `root` and `${XDG_RUNTIME_DIR}/asd` when + running as a non-`root` user. `ASDCONFTIMEOUT` @@ -360,6 +369,11 @@ Discover a bug? Please open an issue on the project page linked below. - Project page: https://github.com/graysky2/anything-sync-daemon - Wiki page: https://wiki.archlinux.org/index.php/Anything-sync-daemon +# SEE ALSO + +`bash`(1), `cron`(8), `crontab`(1), `crontab`(5), `mount`(5), +`systemd.exec`(5), `systemd.service`(5), `systemd.timer`(5), `systemd.unit`(5) + # AUTHOR graysky (graysky AT archlinux DOT us) diff --git a/doc/asd.1 b/doc/asd.1 index 152aa2f..54594b4 100644 --- a/doc/asd.1 +++ b/doc/asd.1 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pandoc 2.19.2 +.\" Automatically generated by Pandoc 3.1.6 .\" .\" Define V font for inline verbatim, using C font in formats .\" that render this, and otherwise B font. @@ -45,7 +45,10 @@ is redirected from the physical disc to RAM, reducing wear to the physical disc and improving speed and responsiveness. .SH SETUP .PP -\f[V]/etc/asd.conf\f[R] contains all user-managed settings. +The \f[V]asd\f[R] configuration file contains all user-managed settings. +See the entry on \f[V]ASDCONF\f[R] in the +\f[V]ENVIRONMENT VARIABLES\f[R] section for information on the default +\f[V]asd\f[R] configuration file location. The configuration file location can be overridden by specifying a pathname in the \f[V]ASDCONF\f[R] environment variable. For instance, to load \f[V]asd\f[R] settings from @@ -57,9 +60,9 @@ $ ASDCONF=/here/for/some/reason/lives/asd.conf asd \f[R] .fi .PP -\f[B]Note\f[R] that edits made to \f[V]/etc/asd.conf\f[R] while -\f[V]asd\f[R] is running will be applied only after \f[V]asd\f[R] has -been restarted. +\f[B]Note\f[R] that edits made to the \f[V]asd\f[R] configuration file +while \f[V]asd\f[R] is running will be applied only after \f[V]asd\f[R] +has been restarted. .PP In the \f[V]asd\f[R] configuration file, you may define the following variables: @@ -75,7 +78,10 @@ list, \f[V]asd\f[R] will complain and bail out. A path that lives on a tmpfs or zram mount. This is where \f[V]asd\f[R] will store the data eventually synchronized back to the physical disk. -By default, \f[V]asd\f[R] sets \f[V]VOLATILE=/tmp\f[R]. +By default, when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is +unset or set to a false value, \f[V]asd\f[R] sets +\f[V]VOLATILE=/tmp\f[R]. +Otherwise, \f[V]VOLATILE\f[R] defaults to \f[V]ASDRUNDIR\f[R]. \f[B]Note\f[R] that it is a fatal error to set \f[V]VOLATILE\f[R] to a path that does not live on a tmpfs or zram mount. .TP @@ -97,8 +103,9 @@ keep. \f[V]DEBUG\f[R] A boolean variable controlling whether to issue debugging output. .PP -\f[B]Note\f[R] that the default value of \f[V]/tmp\f[R] should work just -fine for the \f[V]VOLATILE\f[R] setting. +\f[B]Note\f[R] that the default values of +\f[V]/tmp\f[R]/\f[V]ASDRUNDIR\f[R] should work just fine for the +\f[V]VOLATILE\f[R] setting. If using \f[V]bleachbit\f[R] (https://www.bleachbit.org/), do NOT invoke it with the \f[V]--clean system.tmp\f[R] switch or you will remove a key dot file (\f[V].foo\f[R]) from \f[V]/tmp\f[R] that \f[V]asd\f[R] needs @@ -133,13 +140,17 @@ WHATTOSYNC=( .TP \f[V]ASDCONF\f[R] Path to the \f[V]asd\f[R] configuration file. -Defaults to \f[V]/etc/asd.conf\f[R] when \f[V]ASDNOV1PATHS\f[R] is -disabled; otherwise, defaults to \f[V]${ASDCONFDIR}/asd.conf\f[R]. +Defaults to \f[V]/etc/asd.conf\f[R] when \f[V]asd\f[R] is running as +\f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is unset or set to a false +value; otherwise, defaults to \f[V]${ASDCONFDIR}/asd.conf\f[R]. .TP \f[V]ASDNOV1PATHS\f[R] A boolean variable controlling whether to use \[lq]version 1\[rq] paths or not. -When set to a false value, \f[B]FIXME\f[R]. +When set to a false value, \f[V]asd\f[R] will use old-style defaults for +its daemon file (\f[V]/run/asd\f[R]), lock file +(\f[V]/run/asd-lock\f[R]), and configuration file +(\f[V]/etc/asd.conf\f[R]). \f[B]NOTE\f[R] that this variable is ignored when \f[V]asd\f[R] is running as a non-\f[V]root\f[R] user. Defaults to disabled (effectively, \f[V]ASDNOV1PATHS=0\f[R]). @@ -147,20 +158,24 @@ Defaults to disabled (effectively, \f[V]ASDNOV1PATHS=0\f[R]). \f[V]ASDCONFDIR\f[R] Parent directory of \f[V]asd.conf\f[R] if \f[V]ASDCONF\f[R] is not defined. -Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is set -to a false value. -Otherwise, defaults to \f[V]CONFIGURATION_DIRECTORY\f[R] (which is set -when \f[V]asd\f[R] runs under systemd), falling back to -\f[V]/etc/asd\f[R] when running as \f[V]root\f[R] and +Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is +unset or set to a false value. +Otherwise, defaults to the first (leftmost) of the colon-separated paths +in the \f[V]CONFIGURATION_DIRECTORY\f[R] environment variable (which is +set when \f[V]asd\f[R] runs under systemd and the \f[V]asd.service\f[R] +unit defines at least one \f[V]ConfigurationDirectory\f[R] entry), +falling back to \f[V]/etc/asd\f[R] when running as \f[V]root\f[R] and \f[V]${XDG_CONFIG_DIR}/asd\f[R] when running as a non-\f[V]root\f[R] user. .TP \f[V]ASDRUNDIR\f[R] Directory where \f[V]asd\f[R] should store runtime state. -Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is set -to a false value. -Otherwise, defaults to \f[V]RUNTIME_DIRECTORY\f[R] (which is set when -\f[V]asd\f[R] runs under systemd), falling back to \f[V]/run/asd\f[R] +Ignored when running as \f[V]root\f[R] and \f[V]ASDNOV1PATHS\f[R] is +unset or set to a false value. +Otherwise, defaults to the first (leftmost) of the colon-separated paths +in the \f[V]RUNTIME_DIRECTORY\f[R] (which is set when \f[V]asd\f[R] runs +under systemd and the \f[V]asd.service\f[R] unit defines at least one +\f[V]RuntimeDirectory\f[R] entry), falling back to \f[V]/run/asd\f[R] when running as \f[V]root\f[R] and \f[V]${XDG_RUNTIME_DIR}/asd\f[R] when running as a non-\f[V]root\f[R] user. .TP @@ -403,6 +418,12 @@ if a hung process has something open there, it can be messy. Project page: https://github.com/graysky2/anything-sync-daemon .IP \[bu] 2 Wiki page: https://wiki.archlinux.org/index.php/Anything-sync-daemon +.SH SEE ALSO +.PP +\f[V]bash\f[R](1), \f[V]cron\f[R](8), \f[V]crontab\f[R](1), +\f[V]crontab\f[R](5), \f[V]mount\f[R](5), \f[V]systemd.exec\f[R](5), +\f[V]systemd.service\f[R](5), \f[V]systemd.timer\f[R](5), +\f[V]systemd.unit\f[R](5) .SH AUTHOR .PP graysky (graysky AT archlinux DOT us)