docs: Add tedge-write documentation page by Bravo555 · Pull Request #3116 · thin-edge/thin-edge.io

Bravo555 · 2024-09-06T16:08:50Z

Proposed changes

Adds a documentation page for tedge-write component, which should contain information about the component relevant to users and references relevant tedge-write information in config_update operation reference.

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
Documentation Update (if none of the other choices apply)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue

configuration update fails due to tedge-write when thin-edge.io is installed in a non-standard location #3073

Checklist

I have read the CONTRIBUTING doc
I have signed the CLA (in all commits with git commit -s)
I ran cargo fmt as mentioned in CODING_GUIDELINES
I used cargo clippy as mentioned in CODING_GUIDELINES
I have added tests that prove my fix is effective or that my feature works
I have added necessary documentation (if appropriate)

Further comments

github-actions · 2024-09-10T08:43:28Z

Robot Results

✅ Passed	❌ Failed	⏭️ Skipped	Total	Pass %	⏱️ Duration
505	0	2	505	100	1h25m49.965053999s

codecov · 2024-09-10T08:59:23Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Additional details and impacted files

📢 Thoughts on this report? Let us know!

rina23q

Left small improvement suggestions

docs/src/references/tedge-write.md

albinsuresh

The content looks fine. Just a few suggestions.

albinsuresh · 2024-09-12T05:42:21Z

crates/core/tedge_write/src/bin.rs

+/// A binary used for writing standard input to files which `tedge` user does not have write
+/// permissions for, using sudo.


Suggested change

/// A binary used for writing standard input to files which `tedge` user does not have write

/// permissions for, using sudo.

/// A binary used for writing to files which `tedge` user does not have write

/// permissions for, using sudo.

/// File content to be passed via standard input.

Just focussing on the primary purpose first, and the details later.

My proposal:

Suggested change

/// A binary used for writing standard input to files which `tedge` user does not have write

/// permissions for, using sudo.

/// A binary used for writing to files which `tedge` user does not have write permissions for.

///

/// To be used in combination with sudo, passing the file content via standard input.

Decided to go with 2nd proposal keeping first sentence short, also referenced tee which is very similar and users should be familiar with.

06a566e

albinsuresh · 2024-09-12T06:35:33Z

docs/src/references/tedge-write.md

+**tedge-write** is a helper thin-edge component used by tedge-agent for privilege elevation.
+tedge-agent spawns a `tedge-write` process when it needs to write to files that `tedge` user/group
+has no write permissions to (e.g. system files or files owned by other packages), for example when


Suggested change

**tedge-write** is a helper thin-edge component used by tedge-agent for privilege elevation.

tedge-agent spawns a `tedge-write` process when it needs to write to files that `tedge` user/group

has no write permissions to (e.g. system files or files owned by other packages), for example when

**tedge-write** is a helper thin-edge component used by tedge-agent for privilege elevation,

when it needs to write to files that `tedge` user/group

has no write permissions to (e.g. system files or files owned by other packages), for example when

I'd rather keep first sentence as a short summary and explain more in detail in the second sentence.

albinsuresh · 2024-09-12T06:37:53Z

docs/src/references/tedge-write.md

+writing an updated configuration file as part of [`config_update` operation][1]. `tedge-agent` will
+first try to write to a file directly and only retry using `tedge-write` if direct write fails due
+to `tedge` user/group not having write permissions to either the file itself or its parent
+directory. Write permission to the parent directory is required to guarantee config updates are


Suggested change

directory. Write permission to the parent directory is required to guarantee config updates are

directory.

Write permission to the parent directory is required to guarantee config updates are

In docs, we try to follow a convention where new sentences are always started on a new line, to have smaller diffs when changes are made in future. A single line which is too long can be broken into smaller ones across multiple lines (I usually break where there's a punctuation). Would be nice if you could do that for the remaining sentences as well.

I will follow this style more closely.
Usually I use rewrap extension in Vscode which automatically wraps text to a defined number of columns, but it reflows whole paragraphs, so it tends to merge back two sentences when separated by only a single newline, which is a bit unfortunate.

albinsuresh · 2024-09-12T06:44:33Z

docs/src/references/tedge-write.md

+`tedge-write` will perform an atomic write, i.e. it will write to a temporary file, set file
+ownership and mode, and finally rename the temporary into the final file. If the target file already
+exists, its original ownership/mode will be preserved and optionally provided new values will be
+ignored.


Suggested change

`tedge-write` will perform an atomic write, i.e. it will write to a temporary file, set file

ownership and mode, and finally rename the temporary into the final file. If the target file already

exists, its original ownership/mode will be preserved and optionally provided new values will be

ignored.

While updating a file, `tedge-write` performs an atomic write, i.e. it first writes to a temporary file, set file ownership and mode, and finally moves it to the target location.

If the target file already exists, its original ownership/mode is preserved and the optionally provided new values are ignored.

albinsuresh · 2024-09-12T06:46:51Z

docs/src/references/tedge-write.md

+exists, its original ownership/mode will be preserved and optionally provided new values will be
+ignored.
+
+For `tedge-write` to work, it needs to be able to write to and set ownership and mode of all files.


Suggested change

For `tedge-write` to work, it needs to be able to write to and set ownership and mode of all files.

For `tedge-write` to work, it needs to be able to write to and set ownership and mode of the target files.

fixed 14fe31f

albinsuresh · 2024-09-12T06:49:15Z

docs/src/references/tedge-write.md

+To achieve this we can use `sudo` with a `sudoers` configuration that allows `tedge` user to run
+`tedge-write` as root without password if the destination file is inside `/etc`:


Suggested change

To achieve this we can use `sudo` with a `sudoers` configuration that allows `tedge` user to run

`tedge-write` as root without password if the destination file is inside `/etc`:

To achieve this we can use `sudo` with a `sudoers` configuration that allows `tedge` user to run

`tedge-write` as root without password.

For example, the following setting allows `tedge-write` to update any file inside `/etc` with elevated privileges:

docs/src/references/tedge-write.md

albinsuresh · 2024-09-12T07:02:32Z

docs/src/references/tedge-write.md

+The sudoers entry will be created by thin-edge.io automatically under `/etc/sudoers.d/tedge`, but in
+non-standard setups the default configuration may need to be changed. It's necessary to provide a
+full path to `tedge-write` in the `sudoers` entry. See [`sudoers(5)`][2] for additional details.


Suggested change

The sudoers entry will be created by thin-edge.io automatically under `/etc/sudoers.d/tedge`, but in

non-standard setups the default configuration may need to be changed. It's necessary to provide a

full path to `tedge-write` in the `sudoers` entry. See [`sudoers(5)`][2] for additional details.

When %%te%% is installed using any one of the standard installation methods, the sudoers entry is automatically created under `/etc/sudoers.d/tedge`,

but in non-standard setups the sudoers configuration may need to be updated manually.

It's necessary to provide a full path to `tedge-write` in the `sudoers` entry. See [`sudoers(5)`][2] for additional details.

fixed 14fe31f

albinsuresh · 2024-09-12T07:03:21Z

docs/src/references/tedge-write.md

+## Command help
+
+```sh title="tedge-write"
+A binary used for writing to files which `tedge` user does not have write permissions for, using sudo


Nitpick: This message got updated in this PR.

Indeed manually generating command help is quite a churn and easy to forget to update, it would be good to generate automatically in the future so we could easily see help for all commands in the documentation.

pros:

command help always in sync

would be easier to verify that flags and options for commands are consistent between different commands

cons:

more build scripts for the CI pipeline

fixed 14fe31f

it would be good to generate it automatically

We already have that: Command block

Instead of sh title="tedge-write" use:

text command="tedge-write --help" title="tedge-write"

Replaced with a call to command block, but I'll need to verify when it's deployed to gh-pages that the output is present as when the command could not be started (e.g. because it wasn't found) the build doesn't fail but the text is left empty.

fb530fb

docs/src/references/agent/tedge-configuration-management.md

docs/src/references/tedge-write.md

rina23q

Looks good!

didier-wenzek

Approved

gligorisaev

Documentation describes the feature correctly

Signed-off-by: Marcel Guzik <marcel.guzik@inetum.com>

Bravo555 temporarily deployed to Test Pull Request September 6, 2024 16:08 — with GitHub Actions Inactive

Bravo555 temporarily deployed to Test Auto September 10, 2024 08:28 — with GitHub Actions Inactive

reubenmiller added documentation Improvements or additions to documentation theme:configuration Theme: Configuration management labels Sep 10, 2024

Bravo555 removed the theme:configuration Theme: Configuration management label Sep 11, 2024

Bravo555 force-pushed the docs/tedge-write branch from 7b863cc to b3da147 Compare September 11, 2024 12:35

Bravo555 had a problem deploying to Test Pull Request September 11, 2024 12:35 — with GitHub Actions Failure

Bravo555 marked this pull request as ready for review September 11, 2024 12:35

Bravo555 requested review from albinsuresh, didier-wenzek, gligorisaev, jarhodes314, reubenmiller and rina23q as code owners September 11, 2024 12:35

Bravo555 force-pushed the docs/tedge-write branch from b3da147 to 687cc6e Compare September 11, 2024 12:52

Bravo555 temporarily deployed to Test Pull Request September 11, 2024 12:52 — with GitHub Actions Inactive

Bravo555 mentioned this pull request Sep 11, 2024

configuration update fails due to tedge-write when thin-edge.io is installed in a non-standard location #3073

Closed

4 tasks

Bravo555 temporarily deployed to Test Auto September 11, 2024 12:57 — with GitHub Actions Inactive

rina23q reviewed Sep 11, 2024

View reviewed changes

docs/src/references/tedge-write.md Outdated Show resolved Hide resolved

docs/src/references/tedge-write.md Outdated Show resolved Hide resolved

albinsuresh reviewed Sep 12, 2024

View reviewed changes

didier-wenzek reviewed Sep 12, 2024

View reviewed changes

docs/src/references/agent/tedge-configuration-management.md Outdated Show resolved Hide resolved

docs/src/references/tedge-write.md Outdated Show resolved Hide resolved

docs/src/references/tedge-write.md Outdated Show resolved Hide resolved

Bravo555 had a problem deploying to Test Pull Request September 12, 2024 10:59 — with GitHub Actions Failure

Bravo555 force-pushed the docs/tedge-write branch from 0799957 to 06a566e Compare September 12, 2024 12:19

Bravo555 had a problem deploying to Test Pull Request September 12, 2024 12:19 — with GitHub Actions Failure

Bravo555 had a problem deploying to Test Pull Request September 12, 2024 12:34 — with GitHub Actions Failure

Bravo555 self-assigned this Sep 13, 2024

Bravo555 temporarily deployed to Test Pull Request September 13, 2024 09:11 — with GitHub Actions Inactive

Bravo555 temporarily deployed to Test Auto September 13, 2024 09:31 — with GitHub Actions Inactive

Bravo555 temporarily deployed to Test Pull Request September 13, 2024 10:13 — with GitHub Actions Inactive

rina23q approved these changes Sep 13, 2024

View reviewed changes

didier-wenzek approved these changes Sep 13, 2024

View reviewed changes

gligorisaev reviewed Sep 16, 2024

View reviewed changes

Bravo555 temporarily deployed to Test Auto September 18, 2024 11:11 — with GitHub Actions Inactive

Bravo555 added 3 commits September 18, 2024 13:14

Clarify tedge-write writes standard input in tedge-write help

75b8ba9

Signed-off-by: Marcel Guzik <marcel.guzik@inetum.com>

docs: Add tedge-write documentation page

0c9d646

Signed-off-by: Marcel Guzik <marcel.guzik@inetum.com>

docs: reference tedge-write in config_update reference

8adcbc7

Signed-off-by: Marcel Guzik <marcel.guzik@inetum.com>

Bravo555 force-pushed the docs/tedge-write branch from 6ed9c1c to 8adcbc7 Compare September 18, 2024 11:15

Bravo555 temporarily deployed to Test Pull Request September 18, 2024 11:16 — with GitHub Actions Inactive

Bravo555 temporarily deployed to Test Auto September 18, 2024 11:21 — with GitHub Actions Inactive

Bravo555 added this pull request to the merge queue Sep 18, 2024

Bravo555 removed their assignment Sep 18, 2024

Merged via the queue into thin-edge:main with commit a4a57ae Sep 18, 2024

Bravo555 deleted the docs/tedge-write branch June 3, 2025 10:44

		/// A binary used for writing standard input to files which `tedge` user does not have write
		/// permissions for, using sudo.

	directory. Write permission to the parent directory is required to guarantee config updates are
	directory.
	Write permission to the parent directory is required to guarantee config updates are

	For `tedge-write` to work, it needs to be able to write to and set ownership and mode of all files.
	For `tedge-write` to work, it needs to be able to write to and set ownership and mode of the target files.

		To achieve this we can use `sudo` with a `sudoers` configuration that allows `tedge` user to run
		`tedge-write` as root without password if the destination file is inside `/etc`:

Conversation

Bravo555 commented Sep 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Types of changes

Paste Link to the issue

Checklist

Further comments

Uh oh!

github-actions bot commented Sep 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Robot Results

Uh oh!

codecov bot commented Sep 10, 2024

Codecov Report

Uh oh!

rina23q left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

albinsuresh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bravo555 Sep 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

didier-wenzek Sep 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bravo555 Sep 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rina23q left a comment

Choose a reason for hiding this comment

Uh oh!

didier-wenzek left a comment

Choose a reason for hiding this comment

Uh oh!

gligorisaev left a comment

Choose a reason for hiding this comment

Uh oh!

Bravo555 commented Sep 6, 2024 •

edited

Loading

github-actions bot commented Sep 10, 2024 •

edited

Loading

Bravo555 Sep 12, 2024 •

edited

Loading

didier-wenzek Sep 13, 2024 •

edited

Loading

Bravo555 Sep 13, 2024 •

edited

Loading