From 1247f4a4641e5ddf714cd6f695752609619600a2 Mon Sep 17 00:00:00 2001 From: Todd Walton Date: Wed, 29 Aug 2018 16:12:32 -0400 Subject: [PATCH] Clarify docs re mode's octal representation (#44410) * Clarify docs re mode's octal representation I changed the language about how to use mode to make it more obvious that using "01777" is not a typo, because the leading zero is not meant to reflect the way that number might have been given on a command line. See also: issues #5409 #9196 #11385 #13115 #18952 #23491 #23521 --- lib/ansible/modules/files/copy.py | 6 +++--- lib/ansible/modules/files/file.py | 3 ++- lib/ansible/modules/files/template.py | 6 +++--- lib/ansible/utils/module_docs_fragments/files.py | 4 ++-- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/lib/ansible/modules/files/copy.py b/lib/ansible/modules/files/copy.py index 53bedfca253..1cc7b139d8d 100644 --- a/lib/ansible/modules/files/copy.py +++ b/lib/ansible/modules/files/copy.py @@ -60,9 +60,9 @@ options: mode: description: - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that - modes are actually octal numbers. You must either specify the leading zero so that - Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it - (like C('644') or C('0644') so Ansible receives a string and can do its own conversion from + modes are actually octal numbers. You must either add a leading zero so that Ansible's + YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it + (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). As of diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index 64921d14a33..c61318bcc24 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -103,11 +103,12 @@ options: ''' EXAMPLES = ''' -# change file ownership, group and mode. When specifying mode using octal numbers, first digit should always be 0. +# change file ownership, group and mode - file: path: /etc/foo.conf owner: foo group: foo + # when specifying mode using octal numbers, add a leading 0 mode: 0644 - file: path: /work diff --git a/lib/ansible/modules/files/template.py b/lib/ansible/modules/files/template.py index 3b34440961e..4f6b9a58b56 100644 --- a/lib/ansible/modules/files/template.py +++ b/lib/ansible/modules/files/template.py @@ -98,9 +98,9 @@ options: mode: description: - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that - modes are actually octal numbers. You must either specify the leading zero so that - Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it - (like C('644') or C('0644') so Ansible receives a string and can do its own conversion from + modes are actually octal numbers. You must either add a leading zero so that Ansible's + YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it + (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). As of diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/utils/module_docs_fragments/files.py index 95615c1ec5f..4e95120f691 100644 --- a/lib/ansible/utils/module_docs_fragments/files.py +++ b/lib/ansible/utils/module_docs_fragments/files.py @@ -27,8 +27,8 @@ options: mode: description: - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. - You must either specify the leading zero so that Ansible's YAML parser knows it is an octal - number (like C(0644) or C(01777)) or quote it (like C('644') or C('0644') so Ansible + You must either add a leading zero so that Ansible's YAML parser knows it is an octal + number (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))."