Skip to content

Commit

Permalink
docs: further usage updates and clarifications
Browse files Browse the repository at this point in the history 
[skip ci]
  • Loading branch information
@tomeon
tomeon committed Oct 11, 2023
1 parent c617863 commit 6bbed5a
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 45 deletions.
64 changes: 39 additions & 25 deletions USAGE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <subcommand>
```

**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:

Expand All @@ -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`

Expand All @@ -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:

Expand All @@ -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`

Expand Down Expand Up @@ -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)
Expand Down
61 changes: 41 additions & 20 deletions doc/asd.1
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -57,9 +60,9 @@ $ ASDCONF=/here/for/some/reason/lives/asd.conf asd <subcommand>
\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:
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -133,34 +140,42 @@ 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]).
.TP
\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
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 6bbed5a

Please sign in to comment.