1#  Copyright 2020 Northern.tech AS
2
3#  This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
4
5#  This program is free software; you can redistribute it and/or modify it
6#  under the terms of the GNU General Public License as published by the
7#  Free Software Foundation; version 3.
8
9#  This program is distributed in the hope that it will be useful,
10#  but WITHOUT ANY WARRANTY; without even the implied warranty of
11#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12#  GNU General Public License for more details.
13
14# You should have received a copy of the GNU General Public License
15# along with this program; if not, write to the Free Software
16# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
17
18# To the extent this program is licensed as part of the Enterprise
19# versions of Cfengine, the applicable Commercial Open Source License
20# (COSL) may apply to this file if you as a licensee so wish it. See
21# included file COSL.txt.
22
23# This example shows how to use the missing_ok attribute in copy from bodies. If
24# the source file is missing, the promise will be seen to be a promise kept
25# instead of a failure. The exception is that a remote copy that fails to make a
26# connection to the remote server will still be seen as a promise failure.
27
28#+begin_src cfengine3
29bundle agent main
30{
31  files:
32    "/tmp/copied_from_missing_ok"
33      copy_from => missing_ok( "/var/cfengine/masterfiles/missing" ),
34      classes => results("bundle", "copy_from_missing_ok");
35
36  reports:
37    "$(with)"
38      with => string_mustache( "{{%-top-}}", sort( classesmatching( "copy_from_.*" ), lex));
39}
40body copy_from missing_ok( file_path )
41{
42  source => "$(file_path)";
43  missing_ok => "true";
44
45    # Run with these classes to try remote copies
46    remote_copy_self::
47        servers => { "127.0.0.1" };
48
49    remote_copy_policy_hub::
50        servers => { $(sys.policy_hub) };
51}
52body classes results(scope, class_prefix)
53{
54  scope => "$(scope)";
55
56  promise_kept => { "$(class_prefix)_reached",
57                    "$(class_prefix)_kept" };
58
59  promise_repaired => { "$(class_prefix)_reached",
60                        "$(class_prefix)_repaired" };
61
62  repair_failed => { "$(class_prefix)_reached",
63                     "$(class_prefix)_error",
64                     "$(class_prefix)_not_kept",
65                     "$(class_prefix)_failed" };
66
67  repair_denied => { "$(class_prefix)_reached",
68                     "$(class_prefix)_error",
69                     "$(class_prefix)_not_kept",
70                     "$(class_prefix)_denied" };
71
72  repair_timeout => { "$(class_prefix)_reached",
73                      "$(class_prefix)_error",
74                      "$(class_prefix)_not_kept",
75                      "$(class_prefix)_timeout" };
76}
77#+end_src
78#@ In the above example `/tmp/copied_from_missing_ok` promises to be a copy of the local file
79#@ `/var/cfengine/masterfiles/missing`. In the `missing_ok` `copy_from` body
80#@ `missing_ok` is set to true. This causes the promise to be considered kept if
81#@ the source file is missing. The `results` classes body is used to define bundle
82#@ scoped classes prefixed with `copy_from_missing_ok`. The `reports` promise
83#@ outputs a sorted list of the classes defined starting with `copy_from_`.
84#+begin_src example_output
85#@ ```
86#@ R: [
87#@   "copy_from_missing_ok_kept",
88#@   "copy_from_missing_ok_reached"
89#@ ]
90#@ ```
91#+end_src
92#@ We can see in the output that the class defined for copying a local file that
93#@ does not exist is seen to be a promise kept.
94