From a894f8e7ebc28bab587879d98edb0ae704faf837 Mon Sep 17 00:00:00 2001 From: Lincoln Wallace Date: Sun, 13 Oct 2024 07:08:11 -0300 Subject: [PATCH] snap: improve documentation (#8972) * plugins/modules/snap: improve documentation Signed-off-by: Lincoln Wallace * undo helper setence about finding avaible snaps. Co-authored-by: Farshid Tavakolizadeh * wip: adress reviews Signed-off-by: Lincoln Wallace * fix: revert sentence Signed-off-by: Lincoln Wallace * feat: improve explanation on snap options Co-authored-by: Farshid Tavakolizadeh * clean: remove duplicated and leave reference Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * feat: add note about priviledge scalation and switch sentence position Signed-off-by: Lincoln Wallace * fix: remove additional dash. Co-authored-by: Farshid Tavakolizadeh * feat: reword note and use better doc cross-ref syntax Signed-off-by: Lincoln Wallace * refact: add period. Co-authored-by: Farshid Tavakolizadeh * fix: linter errors Signed-off-by: Lincoln Wallace * fix: remove redundant sentence Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * fix: remove confuse sentence Co-authored-by: Farshid Tavakolizadeh * fix: remove redudant content Signed-off-by: Lincoln Wallace * feat: add missing word Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * refact: remove abreviation Co-authored-by: Felix Fontein * refact: remove abreviation Co-authored-by: Felix Fontein * refact: remove abreviation Co-authored-by: Felix Fontein --------- Signed-off-by: Lincoln Wallace Co-authored-by: Farshid Tavakolizadeh Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Felix Fontein --- plugins/modules/snap.py | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/plugins/modules/snap.py b/plugins/modules/snap.py index 16c3aec48b..15637f3315 100644 --- a/plugins/modules/snap.py +++ b/plugins/modules/snap.py @@ -1,6 +1,7 @@ #!/usr/bin/python # -*- coding: utf-8 -*- +# Copyright (c) 2024, Lincoln Wallace (locnnil) # Copyright (c) 2021, Alexei Znamensky (russoz) # Copyright (c) 2021, Marcus Rickert # Copyright (c) 2018, Stanislas Lange (angristan) @@ -31,8 +32,7 @@ options: - Name of the snaps to be installed. - Any named snap accepted by the C(snap) command is valid. - > - Notice that snap files might require O(dangerous=true) to ignore the error - "cannot find signatures with metadata for snap". + O(dangerous=true) may be necessary when installing `.snap` files. See O(dangerous) for more details. required: true type: list elements: str @@ -47,10 +47,13 @@ options: type: str classic: description: - - Confinement policy. The classic confinement allows a snap to have - the same level of access to the system as "classic" packages, - like those managed by APT. This option corresponds to the C(--classic) argument. - This option can only be specified if there is a single snap in the task. + - Install a snap that has classic confinement. + - This option corresponds to the C(--classic) argument of the C(snap install) command. + - This level of confinement is permissive, granting full system access, + similar to that of traditionally packaged applications that do not use sandboxing mechanisms. + This option can only be specified when the task involves a single snap. + - See U(https://snapcraft.io/docs/snap-confinement) for more details about classic confinement and confinement levels. + type: bool required: false default: false @@ -69,18 +72,27 @@ options: - Set options with pattern C(key=value) or C(snap:key=value). If a snap name is given, the option will be applied to that snap only. If the snap name is omitted, the options will be applied to all snaps listed in O(name). Options will only be applied to active snaps. + - Options will only be applied when C(state) is set to V(present). + This is done after the necessary installation + or refresh (upgrade/downgrade) of all the snaps listed in O(name). + - See U(https://snapcraft.io/docs/configuration-in-snaps) for more details about snap configuration options. + required: false type: list elements: str version_added: 4.4.0 dangerous: description: - - Install the given snap file even if there are no pre-acknowledged signatures for it, - meaning it was not verified and could be dangerous. + - Install the snap in dangerous mode, without validating its assertions and signatures. + - This is useful when installing local snaps that are either unsigned or have signatures that have not been acknowledged. + - See U(https://snapcraft.io/docs/install-modes) for more details about installation modes. type: bool required: false default: false version_added: 7.2.0 +notes: + - Privileged operations, such as installing and configuring snaps, require root priviledges. + This is only the case if the user has not logged in to the Snap Store. author: - Victor Carceler (@vcarceler)