From d952b5057f0bbb974a7c16c35f9ee0e5cfc909ad Mon Sep 17 00:00:00 2001 From: Nils <> Date: Tue, 29 Mar 2022 13:54:37 +0200 Subject: [PATCH] add chapter and changelog in the api document about write protection --- docs/api/index.html | 34 +++++++++++++++++++++++++++++----- docs/index.html | 2 +- docs/src/api/index.adoc | 18 ++++++++++++++++++ 3 files changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/api/index.html b/docs/api/index.html index 90513d7..bc03e3b 100644 --- a/docs/api/index.html +++ b/docs/api/index.html @@ -466,8 +466,9 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • 1.2.3. Session Root and Session Directories
    • @@ -753,7 +754,25 @@ element in the hierarchy.

    -
    1.2.3.2. Lockfiles
    +
    1.2.3.2. Write-Protection for Session Templates
    +
    +

    Write protection for a whole session directory can either happen by "accident" (files from +another user, a network mount etc.) or on purpose, to protect a session template against accidental +changes. The latter is possible with a recursive chown, chmod or chattr -R +i session-dir.

    +
    +
    +

    nsmd itself just checks if session.nsm is read-only. In this case it will not send the save +command to it’s session clients. This does not prevent hypothetical problems when the user +triggers a clients internal save command in a write protected directory. Clients SHOULD handle +their write protected save files themselves.

    +
    +
    +

    Advanced contraptions, like overlay filesystems or copy-on-write hardlinks to create read-only +sessions without the clients noticing, are out of scope for nsm.

    +
    +
    +
    +
    1.2.3.3. Lockfiles

    Because multiple nsmd can run at the same time we need to prevent accidental write-access to the same session by different nsm-daemons, and subsequently GUIs.

    @@ -798,7 +817,7 @@ osc.udp://myuser.localdomain:11287/
    -
    1.2.3.3. Daemon Discovery
    +
    1.2.3.4. Daemon Discovery

    Each running nsmd, per user, creates a state file under $XDG_RUNTIME_DIR/nsm/d/ (usually /run/user/XXXX/nsm/d/) that can be used to look up running daemons, even if no session is loaded. @@ -1888,6 +1907,11 @@ behaviour more strictly as well, removing false session entries in 3rd party cli if of no consequence to clients but required documentation nevertheless, which was described as "background information" in the chapters for lock files and daemon disovery.

    +
  • +

    nsmd now gracefully handles read-only session.nsm files. This theoretically enables read-only +sessions and session-templates. It is included in the patch-level because this was marked as a +long-standing FIXME in the code by the original author. Or in other words: just a bug fix.

    +
    • @@ -1897,7 +1921,7 @@ if of no consequence to clients but required documentation nevertheless, which w diff --git a/docs/index.html b/docs/index.html index 5049367..c322c07 100644 --- a/docs/index.html +++ b/docs/index.html @@ -557,7 +557,7 @@ Documentation and tutorials for software-developers will be added at a later dat diff --git a/docs/src/api/index.adoc b/docs/src/api/index.adoc index 5e975bb..7c1fbe3 100644 --- a/docs/src/api/index.adoc +++ b/docs/src/api/index.adoc @@ -201,6 +201,20 @@ Any session itself MUST be a "leaf" in this directory tree. A session MUST NOT c session subdirectories: any directory that contains a file `session.nsm` is the final element in the hierarchy. +===== Write-Protection for Session Templates + +Write protection for a whole session directory can either happen by "accident" (files from +another user, a network mount etc.) or on purpose, to protect a session template against accidental +changes. The latter is possible with a recursive `chown`, `chmod` or `chattr -R +i session-dir`. + +nsmd itself just checks if `session.nsm` is read-only. In this case it will not send the save +command to it's session clients. This does not prevent hypothetical problems when the user +triggers a clients internal save command in a write protected directory. Clients SHOULD handle +their write protected save files themselves. + +Advanced contraptions, like overlay filesystems or copy-on-write hardlinks to create read-only +sessions without the clients noticing, are out of scope for nsm. + ===== Lockfiles Because multiple `nsmd` can run at the same time we need to prevent accidental write-access to the @@ -922,3 +936,7 @@ behaviour more strictly as well, removing false session entries in 3rd party cli * nsmd now follows the XDG Base Directory Specifications for it's session root and lock files. This if of no consequence to clients but required documentation nevertheless, which was described as "background information" in the chapters for lock files and daemon disovery. + +* nsmd now gracefully handles read-only `session.nsm` files. This theoretically enables read-only +sessions and session-templates. It is included in the patch-level because this was marked as a +long-standing `FIXME` in the code by the original author. Or in other words: just a bug fix.