init: Modify docs and add release note for 12255

2 files changed, 34 insertions, 1 deletions

diff --git a/doc/init.md b/doc/init.md
index 5778b09d05..a6c9bb94d8 100644
--- a/doc/init.md
+++ b/doc/init.md
@@ -56,7 +56,7 @@ All three configurations assume several paths that might need to be adjusted.
 Binary:              `/usr/bin/bitcoind`  
 Configuration file:  `/etc/bitcoin/bitcoin.conf`  
 Data directory:      `/var/lib/bitcoind`  
-PID file:            `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/var/lib/bitcoind/bitcoind.pid` (systemd)  
+PID file:            `/var/run/bitcoind/bitcoind.pid` (OpenRC and Upstart) or `/run/bitcoind/bitcoind.pid` (systemd)
 Lock file:           `/var/lock/subsys/bitcoind` (CentOS)  
 
 The configuration file, PID directory (if applicable) and data directory
@@ -65,6 +65,22 @@ reasons to make the configuration file and data directory only readable by the
 bitcoin user and group.  Access to bitcoin-cli and other bitcoind rpc clients
 can then be controlled by group membership.
 
+NOTE: When using the systemd .service file, the creation of the aforementioned
+directories and the setting of their permissions is automatically handled by
+systemd. Directories are given a permission of 710, giving the bitcoin group
+access to files under it _if_ the files themselves give permission to the
+bitcoin group to do so (e.g. when `-sysperms` is specified). This does not allow
+for the listing of files under the directory.
+
+NOTE: It is not currently possible to override `datadir` in
+`/etc/bitcoin/bitcoin.conf` with the current systemd, OpenRC, and Upstart init
+files out-of-the-box. This is because the command line options specified in the
+init files take precedence over the configurations in
+`/etc/bitcoin/bitcoin.conf`. However, some init systems have their own
+configuration mechanisms that would allow for overriding the command line
+options specified in the init files (e.g. setting `BITCOIND_DATADIR` for
+OpenRC).
+
 ### macOS
 
 Binary:              `/usr/local/bin/bitcoind`  
diff --git a/doc/release-notes/release-notes-pr12255.md b/doc/release-notes/release-notes-pr12255.md
new file mode 100644
index 0000000000..5ac8b44283
--- /dev/null
+++ b/doc/release-notes/release-notes-pr12255.md
@@ -0,0 +1,17 @@
+systemd init file
+=========
+
+The systemd init file (`contrib/init/bitcoind.service`) has been changed to use
+`/var/lib/bitcoind` as the data directory instead of `~bitcoin/.bitcoin`. This
+change makes Bitcoin Core more consistent with other services, and makes the
+systemd init config more consistent with existing Upstart and OpenRC configs.
+
+The configuration, PID, and data directories are now completely managed by
+systemd, which will take care of their creation, permissions, etc. See
+[`systemd.exec (5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#RuntimeDirectory=)
+for more details.
+
+When using the provided init files under `contrib/init`, overriding the
+`datadir` option in `/etc/bitcoin/bitcoin.conf` will have no effect. This is
+because the command line arguments specified in the init files take precedence
+over the options specified in `/etc/bitcoin/bitcoin.conf`.